@cleocode/adapters 2026.9.19 → 2026.9.20

package/dist/index.js

@@ -43274,7 +43274,53 @@ var init_spawn = __esm({
 // packages/adapters/src/providers/claude-code/paths.ts
 import { homedir as homedir3 } from "node:os";
 import { join as join3 } from "node:path";
-var ClaudeCodePathProvider;
+function claudeSettingsPath() {
+  return new ClaudeCodePathProvider().getSettingsPath() ?? join3(homedir3(), ".claude", "settings.json");
+}
+function isPlainObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isCleoHookEntry(entry, commandIncludes) {
+  if (!isPlainObject2(entry) || !Array.isArray(entry.hooks)) return false;
+  return entry.hooks.some(
+    (hook) => isPlainObject2(hook) && typeof hook.command === "string" && hook.command.includes(CLEO_HOOK_MARKER) && (commandIncludes === void 0 || hook.command.includes(commandIncludes))
+  );
+}
+function hasCleoHook(entries, commandIncludes) {
+  return Array.isArray(entries) && entries.some((e) => isCleoHookEntry(e, commandIncludes));
+}
+function hookMap(settings) {
+  const existing = settings.hooks;
+  if (existing === void 0) {
+    const created = {};
+    settings.hooks = created;
+    return created;
+  }
+  if (!isPlainObject2(existing)) {
+    throw new Error('settings.json "hooks" is not an object; not modifying it');
+  }
+  return existing;
+}
+function appendHookEntry(hooks, event, entry) {
+  const existing = hooks[event];
+  if (existing !== void 0 && !Array.isArray(existing)) {
+    throw new Error(`settings.json "hooks.${event}" is not an array; not modifying it`);
+  }
+  hooks[event] = [...existing ?? [], entry];
+}
+function removeCleoHookEntries(hooks) {
+  let changed = false;
+  for (const [event, entries] of Object.entries(hooks)) {
+    if (!Array.isArray(entries)) continue;
+    const kept = entries.filter((e) => !isCleoHookEntry(e));
+    if (kept.length !== entries.length) {
+      hooks[event] = kept;
+      changed = true;
+    }
+  }
+  return changed;
+}
+var ClaudeCodePathProvider, CLEO_HOOK_MARKER;
 var init_paths = __esm({
   "packages/adapters/src/providers/claude-code/paths.ts"() {
     "use strict";
@@ -43296,6 +43342,7 @@ var init_paths = __esm({
         return process.env["CLAUDE_MEM_DB"] ?? join3(homedir3(), ".claude-mem", "claude-mem.db");
       }
     };
+    CLEO_HOOK_MARKER = "# cleo-hook";
   }
 });
 
@@ -43427,14 +43474,15 @@ var init_context_monitor = __esm({
 });
 
 // packages/adapters/src/providers/claude-code/hooks.ts
-import { existsSync as existsSync4, mkdirSync, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "node:fs";
+import { existsSync as existsSync4 } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
-import { homedir as homedir5 } from "node:os";
 import { join as join5 } from "node:path";
+import { updateJsonConfigFile } from "@cleocode/caamp";
 var PROVIDER_ID, CLAUDE_CODE_EVENT_MAP, ClaudeCodeHookProvider;
 var init_hooks = __esm({
   "packages/adapters/src/providers/claude-code/hooks.ts"() {
     "use strict";
+    init_paths();
     PROVIDER_ID = "claude-code";
     CLAUDE_CODE_EVENT_MAP = {
       // CAAMP: toNative('SessionStart',      'claude-code') = 'SessionStart'
@@ -43506,39 +43554,16 @@ var init_hooks = __esm({
       async registerNativeHooks(projectDir) {
         this.projectDir = projectDir;
         this.registered = true;
-        try {
-          const home = homedir5();
-          const settingsPath = join5(home, ".claude", "settings.json");
-          let settings = {};
-          if (existsSync4(settingsPath)) {
-            try {
-              settings = JSON.parse(readFileSync4(settingsPath, "utf-8"));
-            } catch {
-            }
-          }
-          const hooks = settings.hooks ?? {};
-          const alreadyRegistered = Object.values(hooks).some(
-            (entries) => Array.isArray(entries) && entries.some(
-              (e) => typeof e === "object" && e !== null && Array.isArray(e.hooks) && e.hooks.some(
-                (h) => typeof h.command === "string" && h.command.includes("# cleo-hook")
-              )
-            )
-          );
-          if (alreadyRegistered) {
-            return;
+        await this.updateSettings((settings) => {
+          const hooks = hookMap(settings);
+          if (Object.values(hooks).some((entries) => hasCleoHook(entries))) {
+            return false;
           }
-          if (!hooks.Stop) hooks.Stop = [];
-          hooks.Stop.push({
+          appendHookEntry(hooks, "Stop", {
             matcher: "",
-            hooks: [
-              {
-                type: "command",
-                command: `cleo session end --quiet # cleo-hook`
-              }
-            ]
+            hooks: [{ type: "command", command: `cleo session end --quiet # cleo-hook` }]
           });
-          if (!hooks.PostToolUse) hooks.PostToolUse = [];
-          hooks.PostToolUse.push({
+          appendHookEntry(hooks, "PostToolUse", {
             matcher: "Write|Edit",
             hooks: [
               {
@@ -43553,48 +43578,54 @@ var init_hooks = __esm({
               }
             ]
           });
-          settings.hooks = hooks;
-          mkdirSync(join5(home, ".claude"), { recursive: true });
-          writeFileSync2(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
-        } catch {
-        }
+          return true;
+        });
       }
       /**
        * Unregister native hooks.
        *
-       * Removes CLEO hook entries from `~/.claude/settings.json` by filtering out
-       * entries containing the `# cleo-hook` marker.
+       * Removes CLEO hook entries from Claude Code's `settings.json` by filtering
+       * out entries containing the `# cleo-hook` marker. Same locking, atomicity
+       * and parse-error rules as {@link registerNativeHooks}.
        *
        * @task T164 @task T555
        */
       async unregisterNativeHooks() {
         this.registered = false;
         this.projectDir = null;
+        if (!existsSync4(claudeSettingsPath())) return;
+        await this.updateSettings((settings) => {
+          if (settings.hooks === void 0) return false;
+          return removeCleoHookEntries(hookMap(settings));
+        });
+      }
+      /** The last settings.json failure, or `null` when the last update succeeded. */
+      settingsError = null;
+      /**
+       * Why the last settings.json update did not happen, or `null`.
+       *
+       * @remarks
+       * Hook registration stays non-fatal for adapter initialisation, so a
+       * refused write (malformed settings.json, lock timeout) is surfaced here and
+       * on stderr instead of being swallowed (T12385).
+       *
+       * @returns The failure message, or `null`
+       */
+      getSettingsError() {
+        return this.settingsError;
+      }
+      /** Apply `mutate` to settings.json via CAAMP's locked, atomic JSON writer. */
+      async updateSettings(mutate) {
+        const settingsPath = claudeSettingsPath();
         try {
-          const home = homedir5();
-          const settingsPath = join5(home, ".claude", "settings.json");
-          if (!existsSync4(settingsPath)) return;
-          const settings = JSON.parse(readFileSync4(settingsPath, "utf-8"));
-          const hooks = settings.hooks;
-          if (!hooks) return;
-          let changed = false;
-          for (const [event, entries] of Object.entries(hooks)) {
-            if (!Array.isArray(entries)) continue;
-            const filtered = entries.filter(
-              (e) => !(typeof e === "object" && e !== null && Array.isArray(e.hooks) && e.hooks.some(
-                (h) => typeof h.command === "string" && h.command.includes("# cleo-hook")
-              ))
-            );
-            if (filtered.length !== entries.length) {
-              hooks[event] = filtered;
-              changed = true;
-            }
-          }
-          if (changed) {
-            settings.hooks = hooks;
-            writeFileSync2(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
-          }
-        } catch {
+          await updateJsonConfigFile(settingsPath, mutate);
+          this.settingsError = null;
+        } catch (err) {
+          this.settingsError = err instanceof Error ? err.message : String(err);
+          process.stderr.write(
+            `[cleo:claude-code] hooks not written to ${settingsPath}: ${this.settingsError}
+`
+          );
         }
       }
       /**
@@ -43773,7 +43804,7 @@ var init_hooks = __esm({
 });
 
 // packages/adapters/src/providers/shared/hook-template-installer.ts
-import { copyFileSync, existsSync as existsSync5, mkdirSync as mkdirSync2, statSync } from "node:fs";
+import { copyFileSync, existsSync as existsSync5, mkdirSync, statSync } from "node:fs";
 import { dirname as dirname2, join as join6 } from "node:path";
 import { fileURLToPath } from "node:url";
 function resolveProviderCandidates() {
@@ -43807,7 +43838,7 @@ function copyTemplate(src, dest, force) {
       return { wrote: false };
     }
   }
-  mkdirSync2(dirname2(dest), { recursive: true });
+  mkdirSync(dirname2(dest), { recursive: true });
   copyFileSync(src, dest);
   return { wrote: true };
 }
@@ -43819,7 +43850,7 @@ function installProviderHookTemplates(options) {
     installedFiles: [],
     skipped: []
   };
-  mkdirSync2(targetDir, { recursive: true });
+  mkdirSync(targetDir, { recursive: true });
   const coreDest = join6(targetDir, SHARED_CORE_FILE);
   const coreOutcome = copyTemplate(sharedCoreSource(), coreDest, force);
   if (coreOutcome.wrote) result.installedFiles.push(coreDest);
@@ -43852,20 +43883,13 @@ var init_hook_template_installer = __esm({
 });
 
 // packages/adapters/src/providers/claude-code/install.ts
-import {
-  copyFileSync as copyFileSync2,
-  existsSync as existsSync6,
-  mkdirSync as mkdirSync3,
-  readdirSync as readdirSync2,
-  readFileSync as readFileSync5,
-  writeFileSync as writeFileSync3
-} from "node:fs";
-import { homedir as homedir6 } from "node:os";
+import { copyFileSync as copyFileSync2, existsSync as existsSync6, mkdirSync as mkdirSync2, readdirSync as readdirSync2, readFileSync as readFileSync4 } from "node:fs";
+import { homedir as homedir5 } from "node:os";
 import { dirname as dirname3, join as join7 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-import { ensureProviderInstructionFile } from "@cleocode/caamp";
+import { ensureProviderInstructionFile, updateJsonConfigFile as updateJsonConfigFile2 } from "@cleocode/caamp";
 function getClaudeConfigDir() {
-  return process.env["CLAUDE_HOME"] ?? join7(homedir6(), ".claude");
+  return process.env["CLAUDE_HOME"] ?? join7(homedir5(), ".claude");
 }
 function getAdapterCommandsDir() {
   const thisDir = dirname3(fileURLToPath2(import.meta.url));
@@ -43876,6 +43900,7 @@ var init_install = __esm({
   "packages/adapters/src/providers/claude-code/install.ts"() {
     "use strict";
     init_hook_template_installer();
+    init_paths();
     ClaudeCodeInstallProvider = class {
       /**
        * Install CLEO into a Claude Code project.
@@ -43897,16 +43922,28 @@ var init_install = __esm({
         if (commandsInstalled.length > 0) {
           details.commands = commandsInstalled;
         }
-        const pluginResult = this.registerPlugin();
-        if (pluginResult) {
-          details.plugin = pluginResult;
+        const settingsErrors = [];
+        try {
+          const pluginResult = await this.registerPlugin();
+          if (pluginResult) {
+            details.plugin = pluginResult;
+          }
+        } catch (err) {
+          settingsErrors.push(err instanceof Error ? err.message : String(err));
         }
-        const hookResult = this.installHookTemplates();
-        if (hookResult) {
-          details.hookTemplates = hookResult;
+        try {
+          const hookResult = await this.installHookTemplates();
+          if (hookResult) {
+            details.hookTemplates = hookResult;
+          }
+        } catch (err) {
+          settingsErrors.push(err instanceof Error ? err.message : String(err));
+        }
+        if (settingsErrors.length > 0) {
+          details.settingsErrors = settingsErrors;
         }
         return {
-          success: true,
+          success: settingsErrors.length === 0,
           installedAt,
           instructionFileUpdated,
           details
@@ -43925,10 +43962,10 @@ var init_install = __esm({
        * Checks for plugin enabled in ~/.claude/settings.json.
        */
       async isInstalled() {
-        const settingsPath = join7(getClaudeConfigDir(), "settings.json");
+        const settingsPath = claudeSettingsPath();
         if (existsSync6(settingsPath)) {
           try {
-            const settings = JSON.parse(readFileSync5(settingsPath, "utf-8"));
+            const settings = JSON.parse(readFileSync4(settingsPath, "utf-8"));
             const plugins = settings.enabledPlugins;
             if (plugins && plugins["cleo@cleocode"] === true) {
               return true;
@@ -43964,7 +44001,7 @@ var init_install = __esm({
           return [];
         }
         const targetDir = join7(projectDir, ".claude", "commands");
-        mkdirSync3(targetDir, { recursive: true });
+        mkdirSync2(targetDir, { recursive: true });
         const installed = [];
         const files = readdirSync2(adapterCommandsDir).filter((f) => f.endsWith(".md"));
         for (const file2 of files) {
@@ -43980,29 +44017,24 @@ var init_install = __esm({
        *
        * @returns Description of what was registered, or null if no change needed
        */
-      registerPlugin() {
-        const claudeDir = getClaudeConfigDir();
-        const settingsPath = join7(claudeDir, "settings.json");
-        let settings = {};
-        if (existsSync6(settingsPath)) {
-          try {
-            settings = JSON.parse(readFileSync5(settingsPath, "utf-8"));
-          } catch {
-          }
-        }
-        const enabledPlugins = settings.enabledPlugins ?? {};
+      async registerPlugin() {
         const pluginKey = "cleo@cleocode";
-        if (enabledPlugins[pluginKey] === true) {
-          return null;
-        }
-        if (enabledPlugins["claude-mem@thedotmack"] === true) {
-          enabledPlugins["claude-mem@thedotmack"] = false;
-        }
-        enabledPlugins[pluginKey] = true;
-        settings.enabledPlugins = enabledPlugins;
-        mkdirSync3(claudeDir, { recursive: true });
-        writeFileSync3(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
-        return `Enabled ${pluginKey} in ~/.claude/settings.json`;
+        const wrote = await updateJsonConfigFile2(claudeSettingsPath(), (settings) => {
+          const enabledPlugins = settings.enabledPlugins ?? {};
+          if (!isPlainObject2(enabledPlugins)) {
+            throw new Error('settings.json "enabledPlugins" is not an object; not modifying it');
+          }
+          if (enabledPlugins[pluginKey] === true) {
+            return false;
+          }
+          if (enabledPlugins["claude-mem@thedotmack"] === true) {
+            enabledPlugins["claude-mem@thedotmack"] = false;
+          }
+          enabledPlugins[pluginKey] = true;
+          settings.enabledPlugins = enabledPlugins;
+          return true;
+        });
+        return wrote ? `Enabled ${pluginKey} in ~/.claude/settings.json` : null;
       }
       /**
        * Install the CLEO PreCompact hook templates for Claude Code (T1013).
@@ -44024,7 +44056,7 @@ var init_install = __esm({
        *
        * @task T1013
        */
-      installHookTemplates() {
+      async installHookTemplates() {
         const claudeDir = getClaudeConfigDir();
         const hooksDir = join7(claudeDir, "hooks");
         let templates;
@@ -44036,7 +44068,7 @@ var init_install = __esm({
         } catch {
           return null;
         }
-        const settingsEntryAdded = this.registerPreCompactHook(
+        const settingsEntryAdded = await this.registerPreCompactHook(
           join7(hooksDir, "precompact-safestop.sh")
         );
         if (templates.installedFiles.length === 0 && !settingsEntryAdded) {
@@ -44058,41 +44090,24 @@ var init_install = __esm({
        *
        * @task T1013
        */
-      registerPreCompactHook(shimPath) {
-        const claudeDir = getClaudeConfigDir();
-        const settingsPath = join7(claudeDir, "settings.json");
-        let settings = {};
-        if (existsSync6(settingsPath)) {
-          try {
-            settings = JSON.parse(readFileSync5(settingsPath, "utf-8"));
-          } catch {
+      async registerPreCompactHook(shimPath) {
+        return updateJsonConfigFile2(claudeSettingsPath(), (settings) => {
+          const hooks = hookMap(settings);
+          if (hasCleoHook(hooks.PreCompact, "precompact-safestop.sh")) {
+            return false;
           }
-        }
-        const hooks = settings.hooks ?? {};
-        const preCompactEntries = hooks.PreCompact ?? [];
-        const alreadyWired = preCompactEntries.some(
-          (entry) => typeof entry === "object" && entry !== null && Array.isArray(entry.hooks) && entry.hooks.some(
-            (h) => typeof h.command === "string" && h.command.includes("# cleo-hook") && h.command.includes("precompact-safestop.sh")
-          )
-        );
-        if (alreadyWired) {
-          return false;
-        }
-        preCompactEntries.push({
-          matcher: "",
-          hooks: [
-            {
-              type: "command",
-              command: `"${shimPath}" # cleo-hook`,
-              timeout: 30
-            }
-          ]
+          appendHookEntry(hooks, "PreCompact", {
+            matcher: "",
+            hooks: [
+              {
+                type: "command",
+                command: `"${shimPath}" # cleo-hook`,
+                timeout: 30
+              }
+            ]
+          });
+          return true;
         });
-        hooks.PreCompact = preCompactEntries;
-        settings.hooks = hooks;
-        mkdirSync3(claudeDir, { recursive: true });
-        writeFileSync3(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
-        return true;
       }
     };
   }
@@ -44100,7 +44115,7 @@ var init_install = __esm({
 
 // packages/adapters/src/providers/shared/agent-spawn-wrapper.ts
 import { spawnSync } from "node:child_process";
-import { readFileSync as readFileSync6 } from "node:fs";
+import { readFileSync as readFileSync5 } from "node:fs";
 function hasSystemdRun() {
   if (_systemdRunAvailable !== void 0) return _systemdRunAvailable;
   if (process.platform !== "linux") {
@@ -44114,7 +44129,7 @@ function hasSystemdRun() {
 function readMemTotalBytes() {
   if (process.platform !== "linux") return 32 * 1024 * 1024 * 1024;
   try {
-    const raw = readFileSync6("/proc/meminfo", "utf8");
+    const raw = readFileSync5("/proc/meminfo", "utf8");
     const m = raw.match(/^MemTotal:\s+(\d+)\s+kB/m);
     if (m?.[1]) return parseInt(m[1], 10) * 1024;
   } catch {
@@ -44576,7 +44591,7 @@ var init_transport = __esm({
 // packages/adapters/src/providers/claude-code/adapter.ts
 import { exec as exec2 } from "node:child_process";
 import { existsSync as existsSync7 } from "node:fs";
-import { homedir as homedir7 } from "node:os";
+import { homedir as homedir6 } from "node:os";
 import { join as join9 } from "node:path";
 import { promisify as promisify3 } from "node:util";
 var execAsync2, ClaudeCodeAdapter;
@@ -44734,7 +44749,7 @@ var init_adapter = __esm({
         } catch {
           details.cliAvailable = false;
         }
-        const claudeConfigDir = join9(homedir7(), ".claude");
+        const claudeConfigDir = join9(homedir6(), ".claude");
         const configExists = existsSync7(claudeConfigDir);
         details.configDirExists = configExists;
         const entrypointSet = process.env.CLAUDE_CODE_ENTRYPOINT !== void 0;
@@ -44764,17 +44779,17 @@ var init_adapter = __esm({
 });
 
 // packages/adapters/src/providers/claude-code/statusline.ts
-import { existsSync as existsSync8, readFileSync as readFileSync7 } from "node:fs";
-import { homedir as homedir8 } from "node:os";
+import { existsSync as existsSync8, readFileSync as readFileSync6 } from "node:fs";
+import { homedir as homedir7 } from "node:os";
 import { join as join10 } from "node:path";
 function getClaudeSettingsPath() {
-  return process.env["CLAUDE_SETTINGS"] ?? join10(process.env["CLAUDE_HOME"] ?? join10(homedir8(), ".claude"), "settings.json");
+  return process.env["CLAUDE_SETTINGS"] ?? join10(process.env["CLAUDE_HOME"] ?? join10(homedir7(), ".claude"), "settings.json");
 }
 function checkStatuslineIntegration() {
   const settingsPath = getClaudeSettingsPath();
   if (!existsSync8(settingsPath)) return "no_settings";
   try {
-    const settings = JSON.parse(readFileSync7(settingsPath, "utf-8"));
+    const settings = JSON.parse(readFileSync6(settingsPath, "utf-8"));
     const statusLine = settings.statusLine;
     if (!statusLine?.type) return "not_configured";
     if (statusLine.type !== "command") return "custom_no_cleo";
@@ -44782,10 +44797,10 @@ function checkStatuslineIntegration() {
     if (cmd.includes("context-monitor.sh") || cmd.includes("cleo-statusline") || cmd.includes(".context-state.json") || cmd.includes("context-states")) {
       return "configured";
     }
-    const scriptPath = cmd.startsWith("~") ? cmd.replace("~", homedir8()) : cmd;
+    const scriptPath = cmd.startsWith("~") ? cmd.replace("~", homedir7()) : cmd;
     if (existsSync8(scriptPath)) {
       try {
-        const content = readFileSync7(scriptPath, "utf-8");
+        const content = readFileSync6(scriptPath, "utf-8");
         if (content.includes("context-state.json")) return "configured";
       } catch {
       }
@@ -45018,15 +45033,30 @@ var init_hooks2 = __esm({
 });
 
 // packages/adapters/src/providers/cursor/install.ts
-import { existsSync as existsSync11, mkdirSync as mkdirSync4, readFileSync as readFileSync8, writeFileSync as writeFileSync4 } from "node:fs";
+import { existsSync as existsSync11, readFileSync as readFileSync7 } from "node:fs";
 import { join as join16 } from "node:path";
-import { ensureProviderInstructionFile as ensureProviderInstructionFile3 } from "@cleocode/caamp";
-var CursorInstallProvider;
+import {
+  ensureProviderInstructionFile as ensureProviderInstructionFile3,
+  ensureProviderRuleFile,
+  updateJsonConfigFile as updateJsonConfigFile3
+} from "@cleocode/caamp";
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var CLEO_MDC_FRONTMATTER, CursorInstallProvider;
 var init_install2 = __esm({
   "packages/adapters/src/providers/cursor/install.ts"() {
     "use strict";
     init_hook_template_installer();
     init_paths2();
+    CLEO_MDC_FRONTMATTER = [
+      "---",
+      "description: CLEO task management protocol references",
+      'globs: "**/*"',
+      "alwaysApply: true",
+      "---",
+      ""
+    ].join("\n");
     CursorInstallProvider = class {
       /**
        * Install CLEO into a Cursor project.
@@ -45040,17 +45070,23 @@ var init_install2 = __esm({
         let instructionFileUpdated = false;
         const details = {};
         const instructionResult = await ensureProviderInstructionFile3("cursor", projectDir, {});
-        const cursorFilesUpdated = this.updateInstructionFiles(projectDir);
+        const cursorFilesUpdated = await this.updateInstructionFiles(projectDir);
         instructionFileUpdated = instructionResult.action !== "intact" || cursorFilesUpdated;
         if (instructionFileUpdated) {
           details.instructionFiles = this.getUpdatedFileList(projectDir);
         }
-        const hookResult = this.installHookTemplates(projectDir);
-        if (hookResult) {
-          details.hookTemplates = hookResult;
+        let hooksError = null;
+        try {
+          const hookResult = await this.installHookTemplates(projectDir);
+          if (hookResult) {
+            details.hookTemplates = hookResult;
+          }
+        } catch (err) {
+          hooksError = err instanceof Error ? err.message : String(err);
+          details.hooksError = hooksError;
         }
         return {
-          success: true,
+          success: hooksError === null,
           installedAt,
           instructionFileUpdated,
           details
@@ -45076,7 +45112,7 @@ var init_install2 = __esm({
         const rulesPath = join16(process.cwd(), ".cursorrules");
         if (existsSync11(rulesPath)) {
           try {
-            const content = readFileSync8(rulesPath, "utf-8");
+            const content = readFileSync7(rulesPath, "utf-8");
             const injectionRef = `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`;
             if (content.includes(injectionRef) || content.includes("@.cleo/memory-bridge.md")) {
               return true;
@@ -45096,88 +45132,36 @@ var init_install2 = __esm({
        */
       async ensureInstructionReferences(projectDir) {
         await ensureProviderInstructionFile3("cursor", projectDir, {});
-        this.updateInstructionFiles(projectDir);
+        await this.updateInstructionFiles(projectDir);
       }
       /**
-       * Update instruction files with CLEO @-references.
-       *
-       * Handles both legacy (.cursorrules) and modern (.cursor/rules/cleo.mdc) formats.
+       * Update Cursor's auxiliary rule files through the CAAMP writer.
        *
-       * @returns true if any file was created or modified
-       */
-      updateInstructionFiles(projectDir) {
-        let updated = false;
-        if (this.updateLegacyRules(projectDir)) {
-          updated = true;
-        }
-        if (this.updateModernRules(projectDir)) {
-          updated = true;
-        }
-        return updated;
-      }
-      /**
-       * Update legacy .cursorrules file with @-references.
+       * @remarks
+       * ADR-064 / T12385: both files are written by CAAMP's
+       * `ensureProviderRuleFile` — locked, atomic, with references taken from the
+       * provider registry — instead of raw `writeFileSync` with a local copy of
+       * the references.
        *
-       * References are sourced from the CAAMP provider registry (T1919) rather than
-       * a local constant, keeping this adapter in sync with the single source of truth.
-       * Only modifies the file if it already exists (does not create it).
+       * - Legacy `.cursorrules` is only updated when it already exists; CLEO's
+       *   references live in a CAAMP block and user text is preserved.
+       * - Modern `.cursor/rules/cleo.mdc` is CLEO-owned: MDC frontmatter followed
+       *   by the CAAMP block.
        *
-       * @returns true if the file was modified
-       */
-      updateLegacyRules(projectDir) {
-        const rulesPath = join16(projectDir, ".cursorrules");
-        if (!existsSync11(rulesPath)) {
-          return false;
-        }
-        let content = readFileSync8(rulesPath, "utf-8");
-        const cursorRefs = [
-          `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`,
-          "@.cleo/memory-bridge.md"
-        ];
-        const missingRefs = cursorRefs.filter((ref) => !content.includes(ref));
-        if (missingRefs.length === 0) {
-          return false;
-        }
-        const separator = content.endsWith("\n") ? "" : "\n";
-        content = content + separator + missingRefs.join("\n") + "\n";
-        writeFileSync4(rulesPath, content, "utf-8");
-        return true;
-      }
-      /**
-       * Create or update .cursor/rules/cleo.mdc with CLEO references.
-       *
-       * MDC (Markdown Component) format is Cursor's modern rule file format.
-       * Each .mdc file in .cursor/rules/ is loaded as a rule set.
-       * References are sourced from the CAAMP provider registry (T1919).
-       *
-       * @returns true if the file was created or modified
+       * @returns true if any file was created or modified
        */
-      updateModernRules(projectDir) {
-        const rulesDir = join16(projectDir, ".cursor", "rules");
-        const mdcPath = join16(rulesDir, "cleo.mdc");
-        const cursorRefs = [
-          `@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`,
-          "@.cleo/memory-bridge.md"
+      async updateInstructionFiles(projectDir) {
+        const results = [
+          await ensureProviderRuleFile("cursor", projectDir, {
+            relativePath: ".cursorrules",
+            onlyIfExists: true
+          }),
+          await ensureProviderRuleFile("cursor", projectDir, {
+            relativePath: join16(".cursor", "rules", "cleo.mdc"),
+            preamble: CLEO_MDC_FRONTMATTER
+          })
         ];
-        const expectedContent = [
-          "---",
-          "description: CLEO task management protocol references",
-          'globs: "**/*"',
-          "alwaysApply: true",
-          "---",
-          "",
-          ...cursorRefs,
-          ""
-        ].join("\n");
-        if (existsSync11(mdcPath)) {
-          const existing = readFileSync8(mdcPath, "utf-8");
-          if (existing === expectedContent) {
-            return false;
-          }
-        }
-        mkdirSync4(rulesDir, { recursive: true });
-        writeFileSync4(mdcPath, expectedContent, "utf-8");
-        return true;
+        return results.some((r) => r !== null && r.action !== "intact");
       }
       /**
        * Get list of instruction files that were updated.
@@ -45208,7 +45192,7 @@ var init_install2 = __esm({
        *
        * @task T1013
        */
-      installHookTemplates(projectDir) {
+      async installHookTemplates(projectDir) {
         const hooksDir = join16(projectDir, ".cursor", "hooks");
         let templates;
         try {
@@ -45219,7 +45203,7 @@ var init_install2 = __esm({
         } catch {
           return null;
         }
-        const hooksJsonEntryAdded = this.registerPreCompactHook(
+        const hooksJsonEntryAdded = await this.registerPreCompactHook(
           projectDir,
           join16(hooksDir, "precompact.sh")
         );
@@ -45241,33 +45225,30 @@ var init_install2 = __esm({
        *
        * @task T1013
        */
-      registerPreCompactHook(projectDir, shimPath) {
+      async registerPreCompactHook(projectDir, shimPath) {
         const hooksJsonPath = join16(projectDir, ".cursor", "hooks.json");
-        let config2 = {};
-        if (existsSync11(hooksJsonPath)) {
-          try {
-            config2 = JSON.parse(readFileSync8(hooksJsonPath, "utf-8"));
-          } catch {
+        return updateJsonConfigFile3(hooksJsonPath, (config2) => {
+          const hooks = config2.hooks ?? {};
+          if (!isRecord(hooks)) {
+            throw new Error('.cursor/hooks.json "hooks" is not an object; not modifying it');
           }
-        }
-        const hooks = config2.hooks ?? {};
-        const entries = hooks.preCompact ?? [];
-        const alreadyWired = entries.some(
-          (entry) => typeof entry === "object" && entry !== null && typeof entry.command === "string" && entry.command.includes("# cleo-hook") && entry.command.includes("precompact.sh")
-        );
-        if (alreadyWired) {
-          return false;
-        }
-        entries.push({
-          type: "command",
-          command: `"${shimPath}" # cleo-hook`,
-          timeout: 30
+          const entries = hooks.preCompact ?? [];
+          if (!Array.isArray(entries)) {
+            throw new Error('.cursor/hooks.json "hooks.preCompact" is not an array; not modifying it');
+          }
+          const alreadyWired = entries.some(
+            (entry) => isRecord(entry) && typeof entry.command === "string" && entry.command.includes("# cleo-hook") && entry.command.includes("precompact.sh")
+          );
+          if (alreadyWired) {
+            return false;
+          }
+          hooks.preCompact = [
+            ...entries,
+            { type: "command", command: `"${shimPath}" # cleo-hook`, timeout: 30 }
+          ];
+          config2.hooks = hooks;
+          return true;
         });
-        hooks.preCompact = entries;
-        config2.hooks = hooks;
-        mkdirSync4(join16(projectDir, ".cursor"), { recursive: true });
-        writeFileSync4(hooksJsonPath, JSON.stringify(config2, null, 2) + "\n", "utf-8");
-        return true;
       }
     };
   }
@@ -45580,7 +45561,7 @@ var init_hooks3 = __esm({
 });
 
 // packages/adapters/src/providers/opencode/install.ts
-import { existsSync as existsSync17, mkdirSync as mkdirSync5, readFileSync as readFileSync11, writeFileSync as writeFileSync5 } from "node:fs";
+import { existsSync as existsSync17, mkdirSync as mkdirSync3, readFileSync as readFileSync10, writeFileSync as writeFileSync2 } from "node:fs";
 import { join as join23 } from "node:path";
 import { ensureProviderInstructionFile as ensureProviderInstructionFile6 } from "@cleocode/caamp";
 var OpenCodeInstallProvider;
@@ -45744,14 +45725,14 @@ var init_install3 = __esm({
         ].join("\n");
         if (existsSync17(pluginPath)) {
           try {
-            if (readFileSync11(pluginPath, "utf-8") === generated) {
+            if (readFileSync10(pluginPath, "utf-8") === generated) {
               return false;
             }
           } catch {
           }
         }
-        mkdirSync5(pluginsDir, { recursive: true });
-        writeFileSync5(pluginPath, generated, "utf-8");
+        mkdirSync3(pluginsDir, { recursive: true });
+        writeFileSync2(pluginPath, generated, "utf-8");
         return true;
       }
     };
@@ -46526,21 +46507,21 @@ var init_spawn4 = __esm({
 // packages/adapters/src/providers/pi/adapter.ts
 import { exec as exec12 } from "node:child_process";
 import { existsSync as existsSync19 } from "node:fs";
-import { homedir as homedir14 } from "node:os";
+import { homedir as homedir13 } from "node:os";
 import { join as join27 } from "node:path";
 import { promisify as promisify13 } from "node:util";
 function getPiAgentDir() {
   const env = process.env["PI_CODING_AGENT_DIR"];
   if (env !== void 0 && env.length > 0) {
-    if (env === "~") return homedir14();
-    if (env.startsWith("~/")) return join27(homedir14(), env.slice(2));
+    if (env === "~") return homedir13();
+    if (env.startsWith("~/")) return join27(homedir13(), env.slice(2));
     return env;
   }
   const piHome = process.env["PI_HOME"];
   if (piHome !== void 0 && piHome.length > 0) {
     return join27(piHome, "agent");
   }
-  return join27(homedir14(), ".pi", "agent");
+  return join27(homedir13(), ".pi", "agent");
 }
 var execAsync12, PiAdapter;
 var init_adapter4 = __esm({
@@ -46876,12 +46857,12 @@ function createAdapter2() {
 // packages/adapters/src/providers/codex/adapter.ts
 import { exec as exec3 } from "node:child_process";
 import { existsSync as existsSync10 } from "node:fs";
-import { homedir as homedir10 } from "node:os";
+import { homedir as homedir9 } from "node:os";
 import { join as join15 } from "node:path";
 import { promisify as promisify4 } from "node:util";
 
 // packages/adapters/src/providers/codex/hooks.ts
-import { homedir as homedir9 } from "node:os";
+import { homedir as homedir8 } from "node:os";
 import { join as join13 } from "node:path";
 
 // packages/adapters/src/providers/shared/transcript-reader.ts
@@ -47001,7 +46982,7 @@ var CodexHookProvider = class {
    * @task T162 @epic T134
    */
   async getTranscript(_sessionId, _projectDir) {
-    return readLatestTranscript(join13(homedir9(), ".codex"));
+    return readLatestTranscript(join13(homedir8(), ".codex"));
   }
 };
 
@@ -47165,7 +47146,7 @@ var CodexAdapter = class {
     } catch {
       details.cliAvailable = false;
     }
-    const codexConfigDir = join15(homedir10(), ".codex");
+    const codexConfigDir = join15(homedir9(), ".codex");
     const configExists = existsSync10(codexConfigDir);
     details.configDirExists = configExists;
     const healthy = cliAvailable;
@@ -47209,12 +47190,12 @@ init_cursor();
 // packages/adapters/src/providers/gemini-cli/adapter.ts
 import { exec as exec5 } from "node:child_process";
 import { existsSync as existsSync14 } from "node:fs";
-import { homedir as homedir12 } from "node:os";
+import { homedir as homedir11 } from "node:os";
 import { join as join20 } from "node:path";
 import { promisify as promisify6 } from "node:util";
 
 // packages/adapters/src/providers/gemini-cli/hooks.ts
-import { homedir as homedir11 } from "node:os";
+import { homedir as homedir10 } from "node:os";
 import { join as join18 } from "node:path";
 var GEMINI_CLI_EVENT_MAP = {
   SessionStart: "SessionStart",
@@ -47293,13 +47274,13 @@ var GeminiCliHookProvider = class {
    * @task T161 @epic T134
    */
   async getTranscript(_sessionId, _projectDir) {
-    return readLatestTranscript(join18(homedir11(), ".gemini"));
+    return readLatestTranscript(join18(homedir10(), ".gemini"));
   }
 };
 
 // packages/adapters/src/providers/gemini-cli/install.ts
 init_paths2();
-import { existsSync as existsSync13, readFileSync as readFileSync9 } from "node:fs";
+import { existsSync as existsSync13, readFileSync as readFileSync8 } from "node:fs";
 import { join as join19 } from "node:path";
 import { ensureProviderInstructionFile as ensureProviderInstructionFile4 } from "@cleocode/caamp";
 var GeminiCliInstallProvider = class {
@@ -47348,7 +47329,7 @@ var GeminiCliInstallProvider = class {
     const geminiMdPath = join19(process.cwd(), "GEMINI.md");
     if (existsSync13(geminiMdPath)) {
       try {
-        const content = readFileSync9(geminiMdPath, "utf-8");
+        const content = readFileSync8(geminiMdPath, "utf-8");
         if (content.includes(instructionRef)) {
           return true;
         }
@@ -47469,7 +47450,7 @@ var GeminiCliAdapter = class {
     } catch {
       details.cliAvailable = false;
     }
-    const geminiConfigDir = join20(homedir12(), ".gemini");
+    const geminiConfigDir = join20(homedir11(), ".gemini");
     const configExists = existsSync14(geminiConfigDir);
     details.configDirExists = configExists;
     const healthy = cliAvailable;
@@ -47510,7 +47491,7 @@ function createAdapter5() {
 // packages/adapters/src/providers/kimi/adapter.ts
 import { exec as exec7 } from "node:child_process";
 import { existsSync as existsSync16 } from "node:fs";
-import { homedir as homedir13 } from "node:os";
+import { homedir as homedir12 } from "node:os";
 import { join as join22 } from "node:path";
 import { promisify as promisify8 } from "node:util";
 
@@ -47571,7 +47552,7 @@ var KimiHookProvider = class {
 
 // packages/adapters/src/providers/kimi/install.ts
 init_paths2();
-import { existsSync as existsSync15, readFileSync as readFileSync10 } from "node:fs";
+import { existsSync as existsSync15, readFileSync as readFileSync9 } from "node:fs";
 import { join as join21 } from "node:path";
 import { ensureProviderInstructionFile as ensureProviderInstructionFile5 } from "@cleocode/caamp";
 var KimiInstallProvider = class {
@@ -47620,7 +47601,7 @@ var KimiInstallProvider = class {
     const agentsMdPath = join21(process.cwd(), "AGENTS.md");
     if (existsSync15(agentsMdPath)) {
       try {
-        const content = readFileSync10(agentsMdPath, "utf-8");
+        const content = readFileSync9(agentsMdPath, "utf-8");
         if (content.includes(instructionRef)) {
           return true;
         }
@@ -47728,7 +47709,7 @@ var KimiAdapter = class {
     } catch {
       details.cliAvailable = false;
     }
-    const kimiConfigDir = join22(homedir13(), ".kimi");
+    const kimiConfigDir = join22(homedir12(), ".kimi");
     const configExists = existsSync16(kimiConfigDir);
     details.configDirExists = configExists;
     const healthy = cliAvailable;
@@ -47771,7 +47752,7 @@ init_opencode();
 init_hook_template_installer();
 
 // packages/adapters/src/registry.ts
-import { readFileSync as readFileSync12 } from "node:fs";
+import { readFileSync as readFileSync11 } from "node:fs";
 import { dirname as dirname4, join as join28, resolve as resolve2 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 var PROVIDER_IDS = ["claude-code", "opencode", "cursor", "pi"];
@@ -47781,7 +47762,7 @@ function getProviderManifests() {
   for (const providerId of PROVIDER_IDS) {
     try {
       const manifestPath = join28(baseDir, providerId, "manifest.json");
-      const raw = readFileSync12(manifestPath, "utf-8");
+      const raw = readFileSync11(manifestPath, "utf-8");
       manifests.push(JSON.parse(raw));
     } catch {
     }