arkgate 4.5.6 → 4.5.7

package/CHANGELOG.md

@@ -5,6 +5,29 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 4.5.7 — 2026-08-12
+
+**Patch** over **4.5.6**. Cursor hard write path: project `.cursor/hooks.json` `preToolUse`
+gate for `Write` / `StrReplace` (failClosed), host matrix + doctor honesty, payload mapping
+(`contents` / `StrReplace`), install/merge without wiping sibling hooks. Repair envelope may
+emit; Write `updated_input` reinjection is **not** claimed. Codex/OpenCode stay advisory at
+write. Shell/Tab/human edits still rely on required CI. **No required config migration.**
+
+**Status: prepared** (not published).
+
+### Added
+
+- **Cursor hard write (CH01):** install writes `.cursor/hooks.json` with
+  `preToolUse` matcher `Write|StrReplace`, `failClosed: true`, `--hook --hook-repair`,
+  `--root-env CURSOR_PROJECT_DIR`. Merge preserves sibling Cursor hooks.
+- **Hook runtime:** Cursor payload normalization (`contents` → `content`, `StrReplace` → Edit)
+  and stdout `{ permission: "deny", agent_message, user_message }` on block.
+
+### Changed
+
+- Host support matrix: Cursor `hard-write: true` for listed ops; soft hosts are Codex/OpenCode.
+- Docs: `docs/ai-gates.md`, agent guide, README matrix, CLI help.
+
 ## 4.5.6 — 2026-08-11
 
 **Patch** over **4.5.5**. Field upgrade & multi-project MCP truth (Phase FX): registry-aware
@@ -12,7 +35,7 @@ package install, structured skip recovery, skill drift + opt-in refresh, post-up
 MCP process package honesty, host selection notes, early whatsNew, inventory UX-copy quieting.
 **No required config migration.** No new skill names, sensors, or scores. Freezes held.
 
-**Status: prepared** (not on npm `latest` until publish train completes; see
+**Status: published** (on npm `latest`; see
 `docs/releases/4.5.6.md`).
 
 ### Added

package/README.md

@@ -16,8 +16,8 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 4.5.5** is on npm `latest` — deep-module coach, upgrade what’s new, session honesty.
-> [4.5.5 notes](docs/releases/4.5.5.md) · [4.5.0](docs/releases/4.5.0.md) · [4.4.0](docs/releases/4.4.0.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
+> **ArkGate 4.5.6** is on npm `latest` — field upgrade truth, multi-project MCP honesty, skill drift.
+> [4.5.6 notes](docs/releases/4.5.6.md) · [4.5.5](docs/releases/4.5.5.md) · [4.5.0](docs/releases/4.5.0.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
 
 ---
 
@@ -113,16 +113,16 @@ Details: [docs/use.md](docs/use.md).
 | Claude Code | **Hard** block for listed ops (PreToolUse `Write` / `Edit` / `MultiEdit`) when installed + trusted | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Emitted on hook deny; host must re-inject (hard path when installed + trusted) |
 | Grok Build | **Hard** block for listed ops (PreToolUse `write` / `search_replace` (plus aliases)) when installed + trusted | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Emitted on hook deny; host must re-inject (hard path when installed + trusted) |
 | Google Antigravity | **Hard** block for listed ops (PreToolUse `write_to_file` / `replace_file_content` / `multi_replace_file_content`) when installed + trusted | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Emitted on hook deny; host must re-inject (hard path when installed + trusted) |
-| Cursor | **Advisory only** at write (no hard hook) | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | No hard-boundary payload |
-| OpenAI Codex | **Advisory / best-effort** at write (not equivalent to Claude/Grok hard block) | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Envelope may emit (`--hook-repair`); reinjection **not** guaranteed (advisory host) |
+| Cursor | **Hard** block for listed ops (preToolUse `Write` / `StrReplace`) when installed + trusted | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Envelope may emit (`--hook-repair`); reinjection **not** guaranteed (advisory host) |
+| OpenAI Codex | **Advisory / best-effort** at write (not equivalent to Claude/Grok/Cursor hard block) | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Envelope may emit (`--hook-repair`); reinjection **not** guaranteed (advisory host) |
 | OpenCode | **Advisory / best-effort** at write (MCP + optional plugin; not a hard boundary) | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | No hard-boundary payload |
 
 **Read the CI column:** for every host, the repository-wide hard guarantee is a **required**
 GitHub **status context** that runs the CLI — not “CI file present,” and not the CLI binary name alone.
-Cursor/Codex/OpenCode never get a fake hard write claim.
+Codex/OpenCode never get a fake hard write claim. Cursor hard write covers only listed
+`preToolUse` ops when `.cursor/hooks.json` is installed and trusted — Shell/Tab/human edits still rely on CI.
 
 This table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair **envelopes** may be emitted without reinjection being guaranteed; silent auto-apply never happens. Run `arkgate-check --doctor` (or `ark-check --doctor`) for the evidence actually detected in the current repository.
-
 <!-- arkgate-host-support:end -->
 
 #### Why the hard guarantee lives at the merge gate
@@ -208,7 +208,7 @@ for real systems. Details: [docs/production-hardening.md](docs/production-harden
 | Config · package surface · TS | [configuration](docs/configuration.md) · [package-surface](docs/package-surface.md) · [typescript-support](docs/typescript-support.md) |
 | Brownfield | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |
 | Security | [SECURITY.md](SECURITY.md) |
-| Current release (4.5.5 on npm `latest`) | [docs/releases/4.5.5.md](docs/releases/4.5.5.md) · [CHANGELOG](CHANGELOG.md) |
+| Current release (4.5.6 on npm `latest`) | [docs/releases/4.5.6.md](docs/releases/4.5.6.md) · [CHANGELOG](CHANGELOG.md) |
 | Prior (4.5.0) | [docs/releases/4.5.0.md](docs/releases/4.5.0.md) |
 | Prior (4.4.0) | [docs/releases/4.4.0.md](docs/releases/4.4.0.md) |
 | Prior (4.3.0) | [docs/releases/4.3.0.md](docs/releases/4.3.0.md) |

package/bin/ark-check-runtime.mjs

@@ -322,9 +322,10 @@ function usage() {
     'transition. Weakening or judgment-required findings fail unless --policy-ack names',
     'every finding and is bound to both policy hashes. Use --policy-base/--policy-base-ref',
     'for an explicit comparison; ARK_POLICY_BASE_REF is the CI environment equivalent.',
-    'Add --require-write-hook claude|grok to validate a hard local write boundary for that',
-    'specific host. Cursor and Codex expose advisory MCP tools plus the shared CI check;',
-    'merge blocking requires repository policy to make that status required.',
+    'Add --require-write-hook claude|grok|antigravity|cursor to validate a hard local write',
+    'boundary for that specific host. Codex and OpenCode expose advisory MCP (plus best-effort',
+    'hooks where applicable) and the shared CI check; merge blocking requires repository policy',
+    'to make that status required.',
     '',
     '--require-gates implies --strict-config and fails when the Ark contract in AGENTS.md,',
     'the project-rooted Ark server in .mcp.json, or fail-closed CI is missing/invalid.',
@@ -332,7 +333,8 @@ function usage() {
     '',
     '--install-agent-gates writes AGENTS.md, .mcp.json, and the CI workflow for every',
     'project, plus tool-specific templates. Known tools: claude, cursor, codex, grok',
-    '(Claude/Grok hard-write hooks; Cursor/Codex advisory MCP; shared CI check for all) and',
+    '(Claude/Grok/Antigravity/Cursor hard-write hooks when covered; Codex advisory MCP;',
+    'shared CI check for all) and',
     'windsurf, cline, copilot, kiro, roo, continue, gemini',
     '(instruction-tier rule files derived from the same contract).',
     'It also installs the /ark-* skills shipped in templates/skills/ into each',

package/bin/ark-mcp-runtime.mjs

@@ -5,8 +5,11 @@ import path from 'node:path';
 import readline from 'node:readline';
 import { createHash, randomUUID } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
-import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
+import {
+  buildProcessPackageHonesty,
+  readProjectInstalledArkgateVersion,
+} from './lib/mcp-process-package.mjs';
 import {
   DEFAULT_INTENT_PREFIXES,
   DEFAULT_LAYER_DIRECTORIES,
@@ -351,6 +354,8 @@ function mapAntigravityToolCall(toolCall) {
  * Grok Build:  { toolName, toolInput:  { file_path, content | old_string/new_string } }
  *              (aliases Write/Edit/MultiEdit → write/search_replace; matcher keeps both)
  * Antigravity: { toolCall: { name, args: { TargetFile, CodeContent, … } } }
+ * Cursor:      { tool_name, tool_input, hook_event_name?, workspace_roots? }
+ *              Write uses `contents`; StrReplace maps to Edit (path/old_string/new_string).
  */
 function normalizeHookPayload(payload, grokHookEvent = Boolean(process.env.GROK_HOOK_EVENT)) {
   const antigravityStyle =
@@ -367,17 +372,25 @@ function normalizeHookPayload(payload, grokHookEvent = Boolean(process.env.GROK_
       toolInput: { ...(mapped?.toolInput ?? {}), file_path: filePath },
       grokStyle: true, // decision JSON on stdout (deny)
       antigravityStyle: true,
+      cursorStyle: false,
       operation: mapped?.operation ?? mapped?.toolName ?? null,
     };
   }
 
   const rawName = payload?.tool_name ?? payload?.toolName ?? '';
-  const toolInput = payload?.tool_input ?? payload?.toolInput ?? {};
+  const toolInputRaw = payload?.tool_input ?? payload?.toolInput ?? {};
+  const toolInput =
+    toolInputRaw && typeof toolInputRaw === 'object' ? { ...toolInputRaw } : {};
+  // Cursor Write uses `contents`; Claude/Grok use `content`.
+  if (toolInput.content == null && typeof toolInput.contents === 'string') {
+    toolInput.content = toolInput.contents;
+  }
   const nameMap = {
     Write: 'Write',
     write: 'Write',
     Edit: 'Edit',
     search_replace: 'Edit',
+    StrReplace: 'Edit',
     MultiEdit: 'MultiEdit',
     ApplyPatch: 'ApplyPatch',
     apply_patch: 'ApplyPatch',
@@ -388,6 +401,15 @@ function normalizeHookPayload(payload, grokHookEvent = Boolean(process.env.GROK_
   const toolName = nameMap[rawName] ?? rawName;
   const filePath =
     toolInput.file_path ?? toolInput.filePath ?? toolInput.path ?? toolInput.target_file;
+  const cursorStyle =
+    Boolean(process.env.CURSOR_PROJECT_DIR) ||
+    Boolean(process.env.CURSOR_VERSION) ||
+    (payload != null &&
+      typeof payload === 'object' &&
+      (payload.hook_event_name === 'preToolUse' ||
+        Array.isArray(payload.workspace_roots) ||
+        rawName === 'StrReplace' ||
+        (rawName === 'Write' && typeof toolInputRaw?.contents === 'string')));
   return {
     toolName,
     toolInput: { ...toolInput, file_path: filePath },
@@ -396,7 +418,8 @@ function normalizeHookPayload(payload, grokHookEvent = Boolean(process.env.GROK_
       grokHookEvent ||
       (payload != null && typeof payload === 'object' && 'toolName' in payload),
     antigravityStyle: false,
-    operation: null,
+    cursorStyle,
+    operation: rawName === 'StrReplace' ? 'StrReplace' : null,
   };
 }
 
@@ -551,7 +574,7 @@ function designDeltaViolations(delta) {
  * generated code are inserted literally, never interpreted as replacement patterns.
  */
 function proposedSource(toolName, toolInput) {
-  if (toolName === 'Write') return toolInput.content;
+  if (toolName === 'Write') return toolInput.content ?? toolInput.contents;
 
   let text = '';
   try {
@@ -607,18 +630,30 @@ function emitAntigravityAllow(output, antigravityStyle) {
   output.stdout(`${JSON.stringify({ decision: 'allow' })}\n`);
 }
 
+/** Cursor preToolUse accepts explicit allow; exit 0 alone also works. */
+function emitCursorAllow(output, cursorStyle) {
+  if (!cursorStyle) return;
+  output.stdout(`${JSON.stringify({ permission: 'allow' })}\n`);
+}
+
+function emitHostAllow(output, { antigravityStyle, cursorStyle }) {
+  emitAntigravityAllow(output, antigravityStyle);
+  emitCursorAllow(output, cursorStyle);
+}
+
 function runHookPayload(payload, gate, config, args, ts, attemptContext, output = processHookOutput()) {
-  const { toolName, toolInput, grokStyle, antigravityStyle, operation } = normalizeHookPayload(
-    payload,
-    attemptContext?.grokHookEvent ?? Boolean(process.env.GROK_HOOK_EVENT)
-  );
+  const { toolName, toolInput, grokStyle, antigravityStyle, cursorStyle, operation } =
+    normalizeHookPayload(
+      payload,
+      attemptContext?.grokHookEvent ?? Boolean(process.env.GROK_HOOK_EVENT)
+    );
   if (toolName === 'ApplyPatch') {
     const patch = toolInput.patch ?? toolInput.input ?? toolInput.content;
     const parsedPatch = codexPatchWrites(patch, args.root);
     // Codex ApplyPatch is only preflighted when Ark can reconstruct every file operation.
     // An incomplete reconstruction must not be mislabeled as atomic or hard enforcement.
     if (!parsedPatch.complete) {
-      emitAntigravityAllow(output, antigravityStyle);
+      emitHostAllow(output, { antigravityStyle, cursorStyle });
       return;
     }
     const patchWrites = parsedPatch.writes;
@@ -684,7 +719,7 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
         );
       }
       if (changes.length === 0) {
-        emitAntigravityAllow(output, antigravityStyle);
+        emitHostAllow(output, { antigravityStyle, cursorStyle });
         return;
       }
       result = prepareChangeFromRoot({
@@ -742,7 +777,7 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
       ? evaluateWriteDesignDelta({ root: args.root, config, changes, ts })
       : null;
     if (result.valid && (designDelta?.valid ?? true)) {
-      emitAntigravityAllow(output, antigravityStyle);
+      emitHostAllow(output, { antigravityStyle, cursorStyle });
       return;
     }
     const message = [
@@ -776,23 +811,23 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
   const filePath = toolInput.file_path;
   if (!['Write', 'Edit', 'MultiEdit'].includes(toolName)) {
     // Non-file tools: fail-open. Antigravity still needs an explicit allow decision.
-    emitAntigravityAllow(output, antigravityStyle);
+    emitHostAllow(output, { antigravityStyle, cursorStyle });
     return;
   }
   if (typeof filePath !== 'string' || !SOURCE_FILE.test(filePath) || filePath.endsWith('.d.ts')) {
-    emitAntigravityAllow(output, antigravityStyle);
+    emitHostAllow(output, { antigravityStyle, cursorStyle });
     return;
   }
   const rel = path.relative(args.root, path.resolve(filePath));
   const segments = rel.split(path.sep);
   if (segments[0] === '..' || segments.includes('node_modules')) {
-    emitAntigravityAllow(output, antigravityStyle);
+    emitHostAllow(output, { antigravityStyle, cursorStyle });
     return;
   }
 
   const source = proposedSource(toolName, toolInput);
   if (typeof source !== 'string') {
-    emitAntigravityAllow(output, antigravityStyle);
+    emitHostAllow(output, { antigravityStyle, cursorStyle });
     return;
   }
 
@@ -830,7 +865,7 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
       })
     : null;
   if (result.valid && (designDelta?.valid ?? true)) {
-    emitAntigravityAllow(output, antigravityStyle);
+    emitHostAllow(output, { antigravityStyle, cursorStyle });
     return;
   }
 
@@ -861,7 +896,7 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
     return false;
   });
   if (newViolations.length === 0 && (designDelta?.valid ?? true)) {
-    emitAntigravityAllow(output, antigravityStyle);
+    emitHostAllow(output, { antigravityStyle, cursorStyle });
     return;
   }
   const combinedViolations = [...newViolations, ...designDeltaViolations(designDelta)];
@@ -923,7 +958,13 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
       enforcement: hookEnforcement(
         args.root,
         attemptContext?.host ??
-          (antigravityStyle ? 'antigravity' : grokStyle ? 'grok' : 'claude'),
+          (antigravityStyle
+            ? 'antigravity'
+            : cursorStyle
+              ? 'cursor'
+              : grokStyle
+                ? 'grok'
+                : 'claude'),
         attemptContext?.operation ??
           operation ??
           (antigravityStyle
@@ -932,11 +973,15 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
               : toolName === 'MultiEdit'
                 ? 'multi_replace_file_content'
                 : 'write_to_file'
-            : grokStyle
+            : cursorStyle
               ? toolName === 'Edit'
-                ? 'search_replace'
-                : 'write'
-              : toolName),
+                ? 'StrReplace'
+                : 'Write'
+              : grokStyle
+                ? toolName === 'Edit'
+                  ? 'search_replace'
+                  : 'write'
+                : toolName),
         toolName === 'Write' || Boolean(attemptContext?.completePatch)
       ),
       ...(layer ? { layer } : {}),
@@ -968,6 +1013,16 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
       }) + '\n'
     );
   }
+  // Cursor preToolUse: permission deny + agent_message (exit 2 also blocks).
+  if (cursorStyle) {
+    output.stdout(
+      JSON.stringify({
+        permission: 'deny',
+        agent_message: message,
+        user_message: `ArkGate blocked write to ${rel}`,
+      }) + '\n'
+    );
+  }
   output.status(2);
 }
 
@@ -1852,47 +1907,13 @@ export async function runArkMcp({ hookInput } = {}) {
    * FX06 — process package vs project install honesty (multi-project field truth).
    * Process arkgateVersion is startup-loaded; after consumer `npm i arkgate@newer`,
    * long-lived MCP can report a stale process version until restart.
+   * Algorithm lives in bin/lib/mcp-process-package.mjs for unit coverage.
    */
-  function readProjectInstalledArkgateVersion() {
-    try {
-      const shallow = path.join(resolvedRoot, 'node_modules', 'arkgate', 'package.json');
-      if (fs.existsSync(shallow)) {
-        const v = JSON.parse(fs.readFileSync(shallow, 'utf8')).version;
-        return typeof v === 'string' && v.trim() ? v.trim() : null;
-      }
-    } catch {
-      /* fall through */
-    }
-    try {
-      const requireFromProject = createRequire(path.join(resolvedRoot, 'package.json'));
-      const pkgJson = requireFromProject.resolve('arkgate/package.json');
-      const v = JSON.parse(fs.readFileSync(pkgJson, 'utf8')).version;
-      return typeof v === 'string' && v.trim() ? v.trim() : null;
-    } catch {
-      return null;
-    }
-  }
-
   function processPackageHonesty() {
-    const processVersion = typeof ark.version === 'string' ? ark.version : null;
-    const projectInstalledVersion = readProjectInstalledArkgateVersion();
-    const mismatch =
-      processVersion != null &&
-      projectInstalledVersion != null &&
-      processVersion !== projectInstalledVersion;
-    return {
-      schemaVersion: '1.0',
-      notAScore: true,
-      processArkgateVersion: processVersion,
-      projectInstalledVersion,
-      processPackageMismatch: mismatch,
-      processStale: mismatch,
-      nextAction: mismatch
-        ? 'Restart or retarget the Ark MCP server so process arkgateVersion matches the project install. Prefer project-local CLI (`npx arkgate` / `npx arkgate-check`) until identity is matched and versions align. Multi-checkout users: one expectedRoot per project; never reuse another checkout’s projectId.'
-        : projectInstalledVersion == null
-          ? 'Project has no resolvable node_modules/arkgate; install the package or use CLI from a project that pins arkgate.'
-          : 'Process package version matches project install for this MCP root.',
-    };
+    return buildProcessPackageHonesty({
+      processVersion: typeof ark.version === 'string' ? ark.version : null,
+      root: resolvedRoot,
+    });
   }
 
   function contextFor(binding) {

package/bin/ark.mjs

@@ -207,8 +207,8 @@ Options:
   --remove-host <host>
                Preview or apply removal of that compact host integration; re-add it with --tools <host>.
   --require-write-hook <host>
-               Require and verify a hard local write hook for Claude or Grok. Cursor/Codex are
-               advisory-write plus hard CI merge only; impossible requests fail before any write.
+               Require and verify a hard local write hook for Claude, Grok, Antigravity, or Cursor.
+               Codex/OpenCode are advisory-write plus hard CI merge only; impossible requests fail before any write.
 
 Interactive mode (TTY, no --yes): asks what application shape you are building and maps it to a preset.
 Non-interactive (no TTY): uses the same defaults as --yes — never calls readline on a null interface.

package/bin/lib/agent-gates.mjs

@@ -26,9 +26,11 @@ export {
   antigravityHooks,
   claudeSettings,
   codexProjectConfig,
+  cursorHooks,
   grokHooks,
   grokProjectConfig,
   mergeAntigravityArkHook,
+  mergeCursorArkHook,
   mergeOpencodeArkMcp,
   opencodeProjectConfig,
 } from './hook-templates.mjs';

package/bin/lib/ci-and-commands.mjs

@@ -370,7 +370,8 @@ ${steps}
 ${placementBody}
 
 The project is only considered Ark-enforced when its host-appropriate write path is configured
-and the CI check passes. Only Claude/Grok provide a hard local write boundary; Cursor/Codex use
+and the CI check passes. Only Claude/Grok/Antigravity/Cursor provide a hard local write boundary
+(Cursor: Write/StrReplace when .cursor/hooks.json is trusted); Codex/OpenCode use
 advisory MCP plus CI. The experimental runtime is not required.
 `;
 }

package/bin/lib/gate-files.mjs

@@ -127,7 +127,7 @@ const FAIL_CLOSED_ARK_FLAG = /(?:^|\s)--(?:strict|strict-merge|require-gates)(?=
 const COMPACT_HOST_FILES = {
   claude: ['.claude/settings.json'],
   grok: ['.grok/config.toml', '.grok/hooks/ark-write-gate.json'],
-  cursor: ['.cursor/mcp.json'],
+  cursor: ['.cursor/mcp.json', '.cursor/hooks.json'],
   codex: ['.codex/hooks.json', '.codex/config.toml'],
   windsurf: ['.windsurf/rules/ark.md'],
   cline: ['.clinerules/ark.md'],

package/bin/lib/hook-templates.mjs

@@ -1,20 +1,22 @@
 // Generated from hook-templates.source.mjs — run npm run generate:packaged-tooling.
-import{execCommandParts as i,execRunner as s}from"../ark-shared.mjs";const c="arkgate-mcp";function l(o){const r=s(o);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",command:`${r} ${c} --session-context --root . --root-env CLAUDE_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"Write|Edit|MultiEdit",hooks:[{type:"command",command:`${r} ${c} --hook --hook-repair --fail-on-new-smells --root . --root-env CLAUDE_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
-`}function p(o){const r=s(o);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${r} ${c} --session-context --root . --root-env CODEX_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"ApplyPatch|apply_patch|Write|Edit|MultiEdit",hooks:[{type:"command",timeout:30,command:`${r} ${c} --hook --hook-repair --fail-on-new-smells --root . --root-env CODEX_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
-`}function f(o){const{command:r,args:e}=i(o,c,["--root",".","--config","ark.config.json"]),t=a=>a.replace(/\\/g,"\\\\").replace(/"/g,'\\"'),n=e.map(a=>`"${t(a)}"`).join(", ");return`# Generated by ark-check --install-agent-gates (Codex project scope).
+import{execCommandParts as l,execRunner as i}from"../ark-shared.mjs";const s="arkgate-mcp";function h(e){const r=i(e);return`${JSON.stringify({version:1,hooks:{preToolUse:[{command:`${r} ${s} --hook --hook-repair --fail-on-new-smells --root . --root-env CURSOR_PROJECT_DIR --config ark.config.json`,matcher:"Write|StrReplace",failClosed:!0,timeout:30}]}},null,2)}
+`}function y(e){const r=i(e);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",command:`${r} ${s} --session-context --root . --root-env CLAUDE_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"Write|Edit|MultiEdit",hooks:[{type:"command",command:`${r} ${s} --hook --hook-repair --fail-on-new-smells --root . --root-env CLAUDE_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
+`}function $(e){const r=i(e);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${r} ${s} --session-context --root . --root-env CODEX_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"ApplyPatch|apply_patch|Write|Edit|MultiEdit",hooks:[{type:"command",timeout:30,command:`${r} ${s} --hook --hook-repair --fail-on-new-smells --root . --root-env CODEX_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
+`}function O(e){const{command:r,args:o}=l(e,s,["--root",".","--config","ark.config.json"]),t=a=>a.replace(/\\/g,"\\\\").replace(/"/g,'\\"'),c=o.map(a=>`"${t(a)}"`).join(", ");return`# Generated by ark-check --install-agent-gates (Codex project scope).
 # CONFIGURED ON DISK \u2014 RUNTIME NOT VERIFIED.
 # Restart Codex, then call ark_identity with expectedRoot before trusting MCP verdicts.
 [mcp_servers.ark]
 command = "${t(r)}"
-args = [${n}]
-`}function g(o){const{command:r,args:e}=i(o,c,["--root",".","--config","ark.config.json"]),t=e.map(n=>`"${n.replace(/\\/g,"\\\\").replace(/"/g,'\\"')}"`).join(", ");return`# Generated by ark-check --install-agent-gates (Grok Build project scope).
+args = [${c}]
+`}function R(e){const{command:r,args:o}=l(e,s,["--root",".","--config","ark.config.json"]),t=o.map(c=>`"${c.replace(/\\/g,"\\\\").replace(/"/g,'\\"')}"`).join(", ");return`# Generated by ark-check --install-agent-gates (Grok Build project scope).
 # Restart Grok (or /mcps \u2192 refresh) after changes. Also loads repo-root .mcp.json.
 [mcp_servers.ark]
 command = "${r.replace(/\\/g,"\\\\").replace(/"/g,'\\"')}"
 args = [${t}]
-`}function u(o){const r=s(o);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${r} ${c} --session-context --root . --root-env GROK_WORKSPACE_ROOT,CLAUDE_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"Write|Edit|MultiEdit|write|search_replace",hooks:[{type:"command",timeout:30,command:`${r} ${c} --hook --hook-repair --fail-on-new-smells --root . --root-env GROK_WORKSPACE_ROOT,CLAUDE_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
-`}function k(o){const r=s(o);return`${JSON.stringify({"ark-write-gate":{PreToolUse:[{matcher:"write_to_file|replace_file_content|multi_replace_file_content",hooks:[{type:"command",timeout:30,command:`${r} ${c} --hook --hook-repair --fail-on-new-smells --root . --config ark.config.json`}]}]}},null,2)}
-`}function d(o){const{command:r,args:e}=i(o,c,["--root",".","--config","ark.config.json"]);return`${JSON.stringify({$schema:"https://opencode.ai/config.json",mcp:{ark:{type:"local",command:[r,...e],enabled:!0}}},null,2)}
-`}function h(o,r){let e,t;try{e=o&&o.trim()?JSON.parse(o):{},t=JSON.parse(r)}catch{return null}if(!e||typeof e!="object"||Array.isArray(e)||!t||typeof t!="object"||Array.isArray(t))return null;const n=t["ark-write-gate"];if(!n||typeof n!="object")return null;const a={...e,"ark-write-gate":n};return`${JSON.stringify(a,null,2)}
-`}function y(o,r){let e,t;try{e=o&&o.trim()?JSON.parse(o):{},t=JSON.parse(r)}catch{return null}if(!e||typeof e!="object"||Array.isArray(e))return null;const n={...e};!n.$schema&&t.$schema&&(n.$schema=t.$schema);const a=e.mcp&&typeof e.mcp=="object"&&!Array.isArray(e.mcp)?{...e.mcp}:{};return a.ark=t.mcp.ark,n.mcp=a,`${JSON.stringify(n,null,2)}
-`}export{c as PREFERRED_MCP_BIN,k as antigravityHooks,l as claudeSettings,p as codexHooks,f as codexProjectConfig,u as grokHooks,g as grokProjectConfig,h as mergeAntigravityArkHook,y as mergeOpencodeArkMcp,d as opencodeProjectConfig};
+`}function _(e){const r=i(e);return`${JSON.stringify({hooks:{SessionStart:[{hooks:[{type:"command",timeout:30,command:`${r} ${s} --session-context --root . --root-env GROK_WORKSPACE_ROOT,CLAUDE_PROJECT_DIR --config ark.config.json`}]}],PreToolUse:[{matcher:"Write|Edit|MultiEdit|write|search_replace",hooks:[{type:"command",timeout:30,command:`${r} ${s} --hook --hook-repair --fail-on-new-smells --root . --root-env GROK_WORKSPACE_ROOT,CLAUDE_PROJECT_DIR --config ark.config.json`}]}]}},null,2)}
+`}function A(e){const r=i(e);return`${JSON.stringify({"ark-write-gate":{PreToolUse:[{matcher:"write_to_file|replace_file_content|multi_replace_file_content",hooks:[{type:"command",timeout:30,command:`${r} ${s} --hook --hook-repair --fail-on-new-smells --root . --config ark.config.json`}]}]}},null,2)}
+`}function j(e){const{command:r,args:o}=l(e,s,["--root",".","--config","ark.config.json"]);return`${JSON.stringify({$schema:"https://opencode.ai/config.json",mcp:{ark:{type:"local",command:[r,...o],enabled:!0}}},null,2)}
+`}function E(e,r){let o,t;try{o=e&&e.trim()?JSON.parse(e):{},t=JSON.parse(r)}catch{return null}if(!o||typeof o!="object"||Array.isArray(o)||!t||typeof t!="object"||Array.isArray(t))return null;const c=t.hooks,p=(Array.isArray(c?.preToolUse)?c.preToolUse:[]).find(n=>n&&typeof n=="object"&&typeof n.command=="string"&&/arkgate-mcp|ark-mcp/.test(n.command)&&/\s--hook(?:\s|$)/.test(` ${n.command} `));if(!p)return null;const m=o.hooks&&typeof o.hooks=="object"&&!Array.isArray(o.hooks)?{...o.hooks}:{},f=Array.isArray(m.preToolUse)?[...m.preToolUse]:[],k=n=>n&&typeof n=="object"&&typeof n.command=="string"&&/arkgate-mcp|ark-mcp/.test(n.command)&&/\s--hook(?:\s|$)/.test(` ${n.command} `)&&(typeof n.matcher!="string"||/Write/.test(n.matcher)||/StrReplace/.test(n.matcher)),g=f.filter(n=>!k(n));m.preToolUse=[...g,p];const u={...o,version:o.version??t.version??1,hooks:m};return`${JSON.stringify(u,null,2)}
+`}function S(e,r){let o,t;try{o=e&&e.trim()?JSON.parse(e):{},t=JSON.parse(r)}catch{return null}if(!o||typeof o!="object"||Array.isArray(o)||!t||typeof t!="object"||Array.isArray(t))return null;const c=t["ark-write-gate"];if(!c||typeof c!="object")return null;const a={...o,"ark-write-gate":c};return`${JSON.stringify(a,null,2)}
+`}function C(e,r){let o,t;try{o=e&&e.trim()?JSON.parse(e):{},t=JSON.parse(r)}catch{return null}if(!o||typeof o!="object"||Array.isArray(o))return null;const c={...o};!c.$schema&&t.$schema&&(c.$schema=t.$schema);const a=o.mcp&&typeof o.mcp=="object"&&!Array.isArray(o.mcp)?{...o.mcp}:{};return a.ark=t.mcp.ark,c.mcp=a,`${JSON.stringify(c,null,2)}
+`}export{s as PREFERRED_MCP_BIN,A as antigravityHooks,y as claudeSettings,$ as codexHooks,O as codexProjectConfig,h as cursorHooks,_ as grokHooks,R as grokProjectConfig,S as mergeAntigravityArkHook,E as mergeCursorArkHook,C as mergeOpencodeArkMcp,j as opencodeProjectConfig};

package/bin/lib/host-support-matrix.mjs

@@ -70,9 +70,27 @@ export const HOST_SUPPORT_MATRIX = Object.freeze({
     true,
     true
   ),
-  cursor: hostProfile('Cursor', null, null, [], false, false, {
-    operationCoverage: { shell: false, 'pre-commit': false },
-  }),
+  // Cursor: official preToolUse deny / exit 2 is a hard block for matched tools when
+  // `.cursor/hooks.json` is installed + trusted. Claim hard only for Write|StrReplace;
+  // Shell/Tab/human edits still rely on CI. Repair envelope may emit; Write updated_input
+  // reinjection is not guaranteed on Cursor (agent_message + retry is the supported path).
+  cursor: hostProfile(
+    'Cursor',
+    '.cursor/hooks.json',
+    'preToolUse `Write` / `StrReplace`',
+    ['Write', 'StrReplace'],
+    true,
+    false,
+    {
+      repairEnvelopeEmitted: true,
+      operationCoverage: {
+        Write: true,
+        StrReplace: true,
+        shell: false,
+        'pre-commit': false,
+      },
+    }
+  ),
   codex: hostProfile(
     'OpenAI Codex',
     '.codex/hooks.json',
@@ -134,14 +152,15 @@ export function renderHostSupportMatrixMarkdown() {
   const rows = HOST_SUPPORT_HOSTS.map((host) => {
     const profile = HOST_SUPPORT_MATRIX[host];
     const capabilities = profile.capabilities;
-    // Fail-closed honesty: Cursor/Codex/OpenCode never claim hard write; CI is required-status.
-    // hookSurface already includes "PreToolUse …" — do not prefix PreToolUse again.
+    // Fail-closed honesty: Codex/OpenCode never claim hard write; CI is required-status.
+    // Cursor claims hard only for listed preToolUse ops when hooks are installed + trusted.
+    // hookSurface already includes "PreToolUse/preToolUse …" — do not prefix again.
     let local;
     if (capabilities['hard-write']) {
       local = `**Hard** block for listed ops (${profile.hookSurface}) when installed + trusted`;
     } else if (host === 'codex') {
       local =
-        '**Advisory / best-effort** at write (not equivalent to Claude/Grok hard block)';
+        '**Advisory / best-effort** at write (not equivalent to Claude/Grok/Cursor hard block)';
     } else if (host === 'opencode') {
       local =
         '**Advisory / best-effort** at write (MCP + optional plugin; not a hard boundary)';
@@ -169,7 +188,8 @@ ${rows}
 
 **Read the CI column:** for every host, the repository-wide hard guarantee is a **required**
 GitHub **status context** that runs the CLI — not “CI file present,” and not the CLI binary name alone.
-Cursor/Codex/OpenCode never get a fake hard write claim.
+Codex/OpenCode never get a fake hard write claim. Cursor hard write covers only listed
+\`preToolUse\` ops when \`.cursor/hooks.json\` is installed and trusted — Shell/Tab/human edits still rely on CI.
 
 This table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair **envelopes** may be emitted without reinjection being guaranteed; silent auto-apply never happens. Run \`arkgate-check --doctor\` (or \`ark-check --doctor\`) for the evidence actually detected in the current repository.`;
 }
@@ -203,14 +223,14 @@ export function doctorWritePathHonestyMessage(activeHost, hardWriteActive) {
   // EH07: distinguish CLI command (arkgate-check / ark-check) from the GitHub required status context name.
   const mergeBoundary =
     'Required CI hard merge boundary = a required GitHub status context that runs arkgate-check --strict-merge (alias ark-check --strict-merge)';
-  if (host === 'cursor') {
-    return `Cursor: write path is advisory (MCP/rules; no hard PreToolUse). ${mergeBoundary}.`;
+  if (host === 'cursor' && !hardWriteActive) {
+    return `Cursor: hard preToolUse is supported for Write/StrReplace when .cursor/hooks.json is installed + trusted; without runtime-observed hook evidence, hard is unverified. ${mergeBoundary}.`;
   }
   if (host === 'codex') {
-    return `Codex: write path is advisory / best-effort at write (not Claude/Grok hard). ${mergeBoundary}.`;
+    return `Codex: write path is advisory / best-effort at write (not Claude/Grok/Cursor hard). ${mergeBoundary}.`;
   }
   if (host === 'opencode') {
-    return `OpenCode: write path is advisory / best-effort (MCP + optional plugin; not Claude/Grok/Antigravity hard). ${mergeBoundary}.`;
+    return `OpenCode: write path is advisory / best-effort (MCP + optional plugin; not Claude/Grok/Antigravity/Cursor hard). ${mergeBoundary}.`;
   }
   if ((host === 'claude' || host === 'grok' || host === 'antigravity') && !hardWriteActive) {
     const label =

package/bin/lib/install-migrate.mjs

@@ -25,9 +25,11 @@ import {
   claudeSettings,
   codexHooks,
   codexProjectConfig,
+  cursorHooks,
   grokHooks,
   grokProjectConfig,
   mergeAntigravityArkHook,
+  mergeCursorArkHook,
   mergeOpencodeArkMcp,
   opencodeProjectConfig,
 } from './hook-templates.mjs';
@@ -194,6 +196,9 @@ export function buildManagedAssetCatalog({ root, tools, compact = false, skillsO
     );
     if (selectedTools.has('cursor')) {
       add('.cursor/mcp.json', mcpJson(root));
+      // whole-file for managed upgrade/manifest (json-merge is install-time only via
+      // mergeCursorArkHook below — same pattern as Antigravity hooks).
+      add('.cursor/hooks.json', cursorHooks(root));
       if (!compact) add('.cursor/rules/ark.mdc', cursorRule(root));
     }
     if (selectedTools.has('claude')) add('.claude/settings.json', claudeSettings(root));
@@ -516,6 +521,25 @@ export function runInstallAgentGates(args) {
       if (merged === existing) return { relativePath, status: 'skipped' };
       return writeTemplate(root, relativePath, merged, true);
     }
+    if (relativePath === '.cursor/hooks.json') {
+      const fullPath = path.join(root, relativePath);
+      let existing = '';
+      try {
+        existing = fs.readFileSync(fullPath, 'utf8');
+      } catch {
+        // Missing hooks file → write generated Cursor preToolUse gate.
+      }
+      if (!existing) {
+        return writeTemplate(root, relativePath, content, true);
+      }
+      const merged = mergeCursorArkHook(existing, content);
+      if (merged == null) {
+        return { relativePath, status: 'skipped-non-ark' };
+      }
+      if (merged === existing) return { relativePath, status: 'skipped' };
+      // Upsert Ark preToolUse without requiring --force; never wipe sibling hooks.
+      return writeTemplate(root, relativePath, merged, true);
+    }
     if (relativePath === '.agents/hooks.json') {
       const fullPath = path.join(root, relativePath);
       let existing = '';

package/bin/lib/managed-upgrade.mjs

@@ -126,7 +126,12 @@ function hasArkText(root, relativePath) {
 
 const HOST_SIGNALS = {
   claude: ['.claude/settings.json', '.claude/skills/ark-upgrade/SKILL.md'],
-  cursor: ['.cursor/mcp.json', '.cursor/rules/ark.mdc', '.cursor/commands/ark-upgrade.md'],
+  cursor: [
+    '.cursor/mcp.json',
+    '.cursor/hooks.json',
+    '.cursor/rules/ark.mdc',
+    '.cursor/commands/ark-upgrade.md',
+  ],
   codex: ['.codex/hooks.json', '.codex/config.toml', '.agents/skills/ark-upgrade/SKILL.md'],
   grok: ['.grok/config.toml', '.grok/hooks/ark-write-gate.json', '.grok/skills/ark-upgrade/SKILL.md'],
   antigravity: ['.agents/hooks.json', '.agents/skills/ark-upgrade/SKILL.md'],