@cleocode/adapters 2026.9.19 → 2026.9.20

package/dist/providers/claude-code/hooks.d.ts

@@ -78,12 +78,28 @@ export declare class ClaudeCodeHookProvider implements AdapterHookProvider {
     /**
      * 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
      */
     unregisterNativeHooks(): Promise<void>;
+    /** The last settings.json failure, or `null` when the last update succeeded. */
+    private settingsError;
+    /**
+     * 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(): string | null;
+    /** Apply `mutate` to settings.json via CAAMP's locked, atomic JSON writer. */
+    private updateSettings;
     /**
      * Check whether hooks have been registered via `registerNativeHooks`.
      */

package/dist/providers/claude-code/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../src/providers/claude-code/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AA8C/D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,sBAAuB,YAAW,mBAAmB;IAChE,kEAAkE;IAClE,OAAO,CAAC,UAAU,CAAS;IAE3B;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAItD,+DAA+D;IAC/D,OAAO,CAAC,UAAU,CAAuB;IAEzC;;;;;;;;;;;;;;;;OAgBG;IACG,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6E5D;;;;;;;OAOG;IACG,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IA2C5C;;OAEG;IACH,YAAY,IAAI,OAAO;IAIvB;;;;OAIG;IACH,aAAa,IAAI,MAAM,GAAG,IAAI;IAI9B;;;;;;;;OAQG;IACH,WAAW,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAI/C;;;;;;;;;;OAUG;IACG,2BAA2B,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAStD;;;;;;;;;;OAUG;IACG,kBAAkB,IAAI,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IASnD;;;;;;;;;;OAUG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAW9D;;;;;;;;;;;;;;;;OAgBG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CA4FpF"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../src/providers/claude-code/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAqD/D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,sBAAuB,YAAW,mBAAmB;IAChE,kEAAkE;IAClE,OAAO,CAAC,UAAU,CAAS;IAE3B;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAItD,+DAA+D;IAC/D,OAAO,CAAC,UAAU,CAAuB;IAEzC;;;;;;;;;;;;;;;;OAgBG;IACG,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuC5D;;;;;;;;OAQG;IACG,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAW5C,gFAAgF;IAChF,OAAO,CAAC,aAAa,CAAuB;IAE5C;;;;;;;;;OASG;IACH,gBAAgB,IAAI,MAAM,GAAG,IAAI;IAIjC,8EAA8E;YAChE,cAAc;IAe5B;;OAEG;IACH,YAAY,IAAI,OAAO;IAIvB;;;;OAIG;IACH,aAAa,IAAI,MAAM,GAAG,IAAI;IAI9B;;;;;;;;OAQG;IACH,WAAW,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAI/C;;;;;;;;;;OAUG;IACG,2BAA2B,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAStD;;;;;;;;;;OAUG;IACG,kBAAkB,IAAI,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IASnD;;;;;;;;;;OAUG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAW9D;;;;;;;;;;;;;;;;OAgBG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CA4FpF"}

package/dist/providers/claude-code/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/claude-code/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAcH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAkBjG;;;;;;;;;;;;;GAaG;AACH,qBAAa,yBAA0B,YAAW,sBAAsB;IACtE;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAwC9D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAkBrC;;;;;;;OAOG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE;;;;;;;;OAQG;IACH,OAAO,CAAC,eAAe;IAsBvB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAkCtB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,oBAAoB;IAgC5B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,sBAAsB;CAmD/B"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/claude-code/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAyBjG;;;;;;;;;;;;;GAaG;AACH,qBAAa,yBAA0B,YAAW,sBAAsB;IACtE;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAwD9D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAkBrC;;;;;;;OAOG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE;;;;;;;;OAQG;IACH,OAAO,CAAC,eAAe;IAsBvB;;;;OAIG;YACW,cAAc;IAwB5B;;;;;;;;;;;;;;;;;;;OAmBG;YACW,oBAAoB;IAgClC;;;;;;;;;;;;;OAaG;YACW,sBAAsB;CAmBrC"}

package/dist/providers/claude-code/paths.d.ts

@@ -29,4 +29,100 @@ export declare class ClaudeCodePathProvider implements AdapterPathProvider {
     /** Get the path to the provider's memory database, or null if unsupported. */
     getMemoryDbPath(): string | null;
 }
+/**
+ * Resolve Claude Code's `settings.json`, honouring `CLAUDE_SETTINGS` and
+ * `CLAUDE_HOME`.
+ *
+ * @remarks
+ * The single resolver for every adapter write to the settings file (T12385).
+ * Hook registration previously hard-coded `~/.claude/settings.json` while the
+ * installer honoured `CLAUDE_HOME`, so the two wrote different files whenever
+ * the override was set.
+ *
+ * @returns Absolute path of the settings file
+ *
+ * @example
+ * ```typescript
+ * const settingsPath = claudeSettingsPath();
+ * ```
+ */
+export declare function claudeSettingsPath(): string;
+/**
+ * Whether a parsed settings value is a plain JSON object.
+ *
+ * @param value - Any parsed JSON value
+ * @returns `true` for a non-null, non-array object
+ *
+ * @example
+ * ```typescript
+ * isPlainObject(settings.enabledPlugins);
+ * ```
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Whether a settings.json hook entry carries a CLEO-owned command.
+ *
+ * @param entry - One element of a `hooks.<Event>` array
+ * @param commandIncludes - Extra substring the CLEO command must contain
+ * @returns `true` when one of the entry's commands has the `# cleo-hook` marker
+ *
+ * @example
+ * ```typescript
+ * isCleoHookEntry({ hooks: [{ type: "command", command: "x # cleo-hook" }] }); // true
+ * ```
+ */
+export declare function isCleoHookEntry(entry: unknown, commandIncludes?: string): boolean;
+/**
+ * Whether a `hooks.<Event>` value holds a CLEO-owned entry.
+ *
+ * @param entries - The event's value (non-arrays hold none)
+ * @param commandIncludes - Extra substring the CLEO command must contain
+ * @returns `true` when a CLEO entry is present
+ *
+ * @example
+ * ```typescript
+ * hasCleoHook(hookMap(settings).Stop);
+ * ```
+ */
+export declare function hasCleoHook(entries: unknown, commandIncludes?: string): boolean;
+/**
+ * Return the settings object's `hooks` map, creating an empty one if absent.
+ *
+ * @param settings - Parsed settings.json
+ * @returns The live `hooks` object (mutations apply to `settings`)
+ * @throws Error when `hooks` exists but is not an object — the caller's write
+ *   is aborted and the file left untouched
+ *
+ * @example
+ * ```typescript
+ * const hooks = hookMap(settings);
+ * ```
+ */
+export declare function hookMap(settings: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Append a hook entry to `hooks[event]`, preserving existing entries.
+ *
+ * @param hooks - The settings `hooks` map
+ * @param event - Native event name (e.g. `Stop`, `PreCompact`)
+ * @param entry - Entry to append
+ * @throws Error when `hooks[event]` exists but is not an array
+ *
+ * @example
+ * ```typescript
+ * appendHookEntry(hookMap(settings), "Stop", { matcher: "", hooks: [] });
+ * ```
+ */
+export declare function appendHookEntry(hooks: Record<string, unknown>, event: string, entry: Record<string, unknown>): void;
+/**
+ * Remove every CLEO-owned entry from every event array in `hooks`.
+ *
+ * @param hooks - The settings `hooks` map
+ * @returns Whether anything was removed
+ *
+ * @example
+ * ```typescript
+ * const changed = removeCleoHookEntries(hookMap(settings));
+ * ```
+ */
+export declare function removeCleoHookEntries(hooks: Record<string, unknown>): boolean;
 //# sourceMappingURL=paths.d.ts.map

package/dist/providers/claude-code/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/providers/claude-code/paths.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,qBAAa,sBAAuB,YAAW,mBAAmB;IAChE,uDAAuD;IACvD,cAAc,IAAI,MAAM;IAIxB,4EAA4E;IAC5E,eAAe,IAAI,MAAM,GAAG,IAAI;IAIhC,4EAA4E;IAC5E,kBAAkB,IAAI,MAAM,GAAG,IAAI;IAInC,8EAA8E;IAC9E,eAAe,IAAI,MAAM,GAAG,IAAI;CAGjC"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/providers/claude-code/paths.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,qBAAa,sBAAuB,YAAW,mBAAmB;IAChE,uDAAuD;IACvD,cAAc,IAAI,MAAM;IAIxB,4EAA4E;IAC5E,eAAe,IAAI,MAAM,GAAG,IAAI;IAIhC,4EAA4E;IAC5E,kBAAkB,IAAI,MAAM,GAAG,IAAI;IAInC,8EAA8E;IAC9E,eAAe,IAAI,MAAM,GAAG,IAAI;CAGjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAI3C;AAKD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,CASjF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,CAE/E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWlF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAMN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAW7E"}

package/dist/providers/cursor/install.d.ts

@@ -60,33 +60,22 @@ export declare class CursorInstallProvider implements AdapterInstallProvider {
      */
     ensureInstructionReferences(projectDir: string): Promise<void>;
     /**
-     * Update instruction files with CLEO @-references.
+     * Update Cursor's auxiliary rule files through the CAAMP writer.
      *
-     * Handles both legacy (.cursorrules) and modern (.cursor/rules/cleo.mdc) formats.
+     * @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.
+     *
+     * - 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 any file was created or modified
      */
     private updateInstructionFiles;
-    /**
-     * Update legacy .cursorrules file with @-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).
-     *
-     * @returns true if the file was modified
-     */
-    private updateLegacyRules;
-    /**
-     * 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
-     */
-    private updateModernRules;
     /**
      * Get list of instruction files that were updated.
      */

package/dist/providers/cursor/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/cursor/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAOjG;;;;;;;;;;;;;GAaG;AACH,qBAAa,qBAAsB,YAAW,sBAAsB;IAClE;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IA+B9D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IA2BrC;;;;;;;OAOG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpE;;;;;;OAMG;IACH,OAAO,CAAC,sBAAsB;IAgB9B;;;;;;;;OAQG;IACH,OAAO,CAAC,iBAAiB;IAuBzB;;;;;;;;OAQG;IACH,OAAO,CAAC,iBAAiB;IA+BzB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,oBAAoB;IA8B5B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,sBAAsB;CAyC/B"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/cursor/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAUH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAsBjG;;;;;;;;;;;;;GAaG;AACH,qBAAa,qBAAsB,YAAW,sBAAsB;IAClE;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAuC9D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IA2BrC;;;;;;;OAOG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpE;;;;;;;;;;;;;;;OAeG;YACW,sBAAsB;IAcpC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;;;;;;;;;;;;;;;;OAiBG;YACW,oBAAoB;IA8BlC;;;;;;;;;;;;OAYG;YACW,sBAAsB;CA+BrC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/adapters",
-  "version": "2026.9.19",
+  "version": "2026.9.20",
   "description": "Unified provider adapters for CLEO (Claude Code, OpenCode, Cursor)",
   "type": "module",
   "main": "dist/index.js",
@@ -15,9 +15,9 @@
     "@ai-sdk/anthropic": "^3.0.69",
     "@ai-sdk/openai": "^2.0.53",
     "ai": "^6.0.168",
-    "@cleocode/caamp": "2026.9.19",
-    "@cleocode/paths": "2026.9.19",
-    "@cleocode/contracts": "2026.9.19"
+    "@cleocode/caamp": "2026.9.20",
+    "@cleocode/contracts": "2026.9.20",
+    "@cleocode/paths": "2026.9.20"
   },
   "license": "MIT",
   "engines": {
@@ -30,7 +30,7 @@
   "devDependencies": {
     "@types/node": "^24.3.0",
     "vitest": "^4.1.4",
-    "@cleocode/playbooks": "2026.9.19"
+    "@cleocode/playbooks": "2026.9.20"
   },
   "repository": {
     "type": "git",

package/src/providers/claude-code/__tests__/adapter.test.ts

@@ -62,6 +62,7 @@ vi.mock('@cleocode/caamp', () => ({
     action: 'added',
     providerId: 'claude-code',
   }),
+  updateJsonConfigFile: vi.fn().mockResolvedValue(false),
 }));
 
 describe('ClaudeCodeAdapter', () => {

package/src/providers/claude-code/__tests__/hooks-install.test.ts

@@ -17,10 +17,11 @@
  * @epic T1000
  */
 
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ClaudeCodeHookProvider } from '../hooks.js';
 import { ClaudeCodeInstallProvider } from '../install.js';
 
 describe('ClaudeCodeInstallProvider — PreCompact hook templates', () => {
@@ -129,4 +130,64 @@ describe('ClaudeCodeInstallProvider — PreCompact hook templates', () => {
     };
     expect((settings.hooks?.PreCompact ?? []).length).toBe(1);
   });
+
+  // T12385 — a malformed settings.json used to be replaced with an object
+  // holding only CLEO's entries (the parse error was caught and the writer
+  // "started fresh"). It must now be reported and left byte-identical.
+  describe('T12385 — malformed settings.json is never rewritten', () => {
+    const malformed = '{\n  "permissions": { "allow": ["Bash(ls)"] },\n  "model": "opus",\n';
+
+    it('install reports the parse error and leaves the file byte-identical', async () => {
+      const settingsPath = join(fakeHome, '.claude', 'settings.json');
+      mkdirSync(join(fakeHome, '.claude'), { recursive: true });
+      writeFileSync(settingsPath, malformed, 'utf-8');
+
+      const result = await new ClaudeCodeInstallProvider().install({ projectDir });
+
+      expect(readFileSync(settingsPath, 'utf-8')).toBe(malformed);
+      expect(result.success).toBe(false);
+      const errors = (result.details?.settingsErrors ?? []) as string[];
+      expect(errors.length).toBeGreaterThan(0);
+      expect(errors[0]).toMatch(/not a valid JSON object/);
+      expect(existsSync(`${settingsPath}.lock`)).toBe(false);
+    });
+
+    it('hook registration reports the parse error and leaves the file byte-identical', async () => {
+      const settingsPath = join(fakeHome, '.claude', 'settings.json');
+      mkdirSync(join(fakeHome, '.claude'), { recursive: true });
+      writeFileSync(settingsPath, malformed, 'utf-8');
+      const stderr = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+
+      const hooks = new ClaudeCodeHookProvider();
+      await hooks.registerNativeHooks(projectDir);
+      await hooks.unregisterNativeHooks();
+
+      stderr.mockRestore();
+      expect(readFileSync(settingsPath, 'utf-8')).toBe(malformed);
+      expect(hooks.getSettingsError()).toMatch(/not a valid JSON object/);
+    });
+
+    it('preserves unrelated user settings when it does write', async () => {
+      const settingsPath = join(fakeHome, '.claude', 'settings.json');
+      mkdirSync(join(fakeHome, '.claude'), { recursive: true });
+      writeFileSync(
+        settingsPath,
+        JSON.stringify({ model: 'opus', hooks: { Stop: [{ matcher: 'x', hooks: [] }] } }),
+        'utf-8',
+      );
+
+      await new ClaudeCodeHookProvider().registerNativeHooks(projectDir);
+      await new ClaudeCodeInstallProvider().install({ projectDir });
+
+      const settings = JSON.parse(readFileSync(settingsPath, 'utf-8')) as {
+        model?: string;
+        enabledPlugins?: Record<string, boolean>;
+        hooks?: Record<string, unknown[]>;
+      };
+      expect(settings.model).toBe('opus');
+      expect(settings.enabledPlugins?.['cleo@cleocode']).toBe(true);
+      expect(settings.hooks?.Stop).toHaveLength(2);
+      expect(settings.hooks?.PreCompact).toHaveLength(1);
+    });
+  });
 });

package/src/providers/claude-code/hooks.ts

@@ -16,11 +16,18 @@
  * @epic T134
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { readdir, readFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { updateJsonConfigFile } from '@cleocode/caamp';
 import type { AdapterHookProvider } from '@cleocode/contracts';
+import {
+  appendHookEntry,
+  claudeSettingsPath,
+  hasCleoHook,
+  hookMap,
+  removeCleoHookEntries,
+} from './paths.js';
 
 /** CAAMP provider identifier for Claude Code. */
 const PROVIDER_ID = 'claude-code' as const;
@@ -133,56 +140,23 @@ export class ClaudeCodeHookProvider implements AdapterHookProvider {
     this.projectDir = projectDir;
     this.registered = true;
 
-    // Write CLEO hook entries to ~/.claude/settings.json (idempotent)
-    try {
-      const home = homedir();
-      const settingsPath = join(home, '.claude', 'settings.json');
-
-      let settings: Record<string, unknown> = {};
-      if (existsSync(settingsPath)) {
-        try {
-          settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
-        } catch {
-          // Start fresh if settings.json is corrupt
-        }
-      }
-
-      const hooks = (settings.hooks ?? {}) as Record<string, unknown[]>;
-
-      // Check if CLEO hooks already registered (look for our marker comment in commands)
-      const alreadyRegistered = Object.values(hooks).some(
-        (entries) =>
-          Array.isArray(entries) &&
-          entries.some(
-            (e) =>
-              typeof e === 'object' &&
-              e !== null &&
-              Array.isArray((e as Record<string, unknown>).hooks) &&
-              ((e as Record<string, unknown>).hooks as Array<Record<string, string>>).some(
-                (h) => typeof h.command === 'string' && h.command.includes('# cleo-hook'),
-              ),
-          ),
-      );
-
-      if (alreadyRegistered) {
-        return; // Already wired — idempotent
+    // Write CLEO hook entries to settings.json (idempotent). T12385: locked,
+    // atomic, and a malformed file is reported and left untouched — never
+    // replaced with an object holding only CLEO's entries.
+    await this.updateSettings((settings) => {
+      const hooks = hookMap(settings);
+      if (Object.values(hooks).some((entries) => hasCleoHook(entries))) {
+        return false; // Already wired — idempotent
       }
 
       // Register Stop hook → triggers cleo session end (LLM extraction, reflector, consolidation)
-      if (!hooks.Stop) hooks.Stop = [];
-      (hooks.Stop as unknown[]).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` }],
       });
 
       // Register PostToolUse hook → brain observation for file writes + NEXUS post-check (T625)
-      if (!hooks.PostToolUse) hooks.PostToolUse = [];
-      (hooks.PostToolUse as unknown[]).push({
+      appendHookEntry(hooks, 'PostToolUse', {
         matcher: 'Write|Edit',
         hooks: [
           {
@@ -197,20 +171,16 @@ export class ClaudeCodeHookProvider implements AdapterHookProvider {
           },
         ],
       });
-
-      settings.hooks = hooks;
-      mkdirSync(join(home, '.claude'), { recursive: true });
-      writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
-    } catch {
-      // Settings write failure is non-fatal — hooks can be registered manually
-    }
+      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
    */
@@ -218,42 +188,43 @@ export class ClaudeCodeHookProvider implements AdapterHookProvider {
     this.registered = false;
     this.projectDir = null;
 
-    try {
-      const home = homedir();
-      const settingsPath = join(home, '.claude', 'settings.json');
-      if (!existsSync(settingsPath)) return;
-
-      const settings = JSON.parse(readFileSync(settingsPath, 'utf-8')) as Record<string, unknown>;
-      const hooks = settings.hooks as Record<string, unknown[]> | undefined;
-      if (!hooks) return;
-
-      // Filter out entries with the cleo-hook marker
-      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 as Record<string, unknown>).hooks) &&
-              ((e as Record<string, unknown>).hooks as Array<Record<string, string>>).some(
-                (h) => typeof h.command === 'string' && h.command.includes('# cleo-hook'),
-              )
-            ),
-        );
-        if (filtered.length !== entries.length) {
-          hooks[event] = filtered;
-          changed = true;
-        }
-      }
+    if (!existsSync(claudeSettingsPath())) return;
+    await this.updateSettings((settings) => {
+      if (settings.hooks === undefined) return false;
+      return removeCleoHookEntries(hookMap(settings));
+    });
+  }
 
-      if (changed) {
-        settings.hooks = hooks;
-        writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
-      }
-    } catch {
-      // Cleanup failure is non-fatal
+  /** The last settings.json failure, or `null` when the last update succeeded. */
+  private settingsError: string | null = 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(): string | null {
+    return this.settingsError;
+  }
+
+  /** Apply `mutate` to settings.json via CAAMP's locked, atomic JSON writer. */
+  private async updateSettings(
+    mutate: (settings: Record<string, unknown>) => boolean,
+  ): Promise<void> {
+    const settingsPath = claudeSettingsPath();
+    try {
+      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}\n`,
+      );
     }
   }