@cleocode/adapters 2026.10.3 → 2026.10.5-rc.ci.672

package/dist/providers/shared/heavy-command-hook-install.d.ts

@@ -48,6 +48,30 @@ export declare const HEAVY_TOOL_WORDS: readonly string[];
  * home directory, whose provider configs are the user-global ones.
  */
 export type HeavyHookSyncResult = 'installed' | 'updated' | 'removed' | 'unchanged' | 'skipped';
+/**
+ * A config path cannot be created because something on the way to it exists
+ * but is not a directory (T13124: a stray empty `<project>/.codex` file made
+ * `mkdirSync` throw `EEXIST` and aborted the Codex install). Nothing is
+ * written; the delivery reports the provider as `blocked`.
+ */
+export declare class HeavyHookPathBlockedError extends Error {
+    /** The existing path that is not a directory. */
+    readonly path: string;
+    /**
+     * @param path - the existing non-directory path.
+     * @param target - the config file that would have lived under it.
+     */
+    constructor(path: string, target: string);
+}
+/**
+ * The nearest existing path at or above `dir` when it is NOT a directory, or
+ * `null` when the nearest existing one is a directory (so `mkdir -p dir`
+ * can succeed). Errors other than "does not exist" return `null` and are left
+ * to the write that follows.
+ *
+ * @param dir - the directory a config file needs.
+ */
+export declare function nonDirectoryAncestor(dir: string): string | null;
 /**
  * Whether `projectDir` is the user's home directory. There,
  * `<home>/.claude/settings.local.json`, `<home>/.codex/hooks.json` and
@@ -108,6 +132,8 @@ export declare function heavyCommandHookObject(provider: 'claude-code' | 'codex'
  * @param provider - `claude-code` or `codex`.
  */
 export declare function heavyCommandHookEntry(provider: 'claude-code' | 'codex'): Record<string, unknown>;
+/** Whether one hook object is CLEO's heavy-command hook. */
+export declare function isHeavyHookObject(hook: unknown): boolean;
 /**
  * Add, refresh or (mode `off`) remove CLEO's heavy-command hook in a JSON hook
  * config, through CAAMP's locked atomic writer. Only CLEO's own hook object is
@@ -119,28 +145,147 @@ export declare function heavyCommandHookEntry(provider: 'claude-code' | 'codex')
  * @returns what changed.
  */
 export declare function syncJsonHeavyCommandHook(configPath: string, provider: 'claude-code' | 'codex', mode: HeavyCommandHookMode): Promise<HeavyHookSyncResult>;
-/** First line of the `info/exclude` block CLEO adds (and alone may remove). */
+/** Claude Code's per-machine settings file, relative to the project. */
+export declare const CLAUDE_LOCAL_SETTINGS = ".claude/settings.local.json";
+/** First line of the `info/exclude` block CLEO adds for `settings.local.json` (and alone may remove). */
 export declare const LOCAL_SETTINGS_EXCLUDE_MARKER = "# cleo-hook: keep the per-machine heavy-command hook settings out of git (T12983)";
 /**
- * Keep `.claude/settings.local.json` out of git when nothing ignores it yet
- * (Claude Code ignores the file only when it creates it itself). Adds a marked
- * block naming this project's file to the repository's `info/exclude`, never
- * to a tracked `.gitignore`. Keyed on the exact path line, so a second CLEO
+ * First line of the `info/exclude` block CLEO adds for any other hook file it
+ * writes: Codex's `.codex/hooks.json` and the opencode plugin (T13124, gh#1805:
+ * an untracked plugin file widened `cleo verify`'s evidence scope).
+ */
+export declare const HOOK_FILE_EXCLUDE_MARKER = "# cleo-hook: keep a per-machine heavy-command hook file out of git (T13124)";
+/** Codex's project hook config, relative to the project. */
+export declare const CODEX_HOOKS_FILE = ".codex/hooks.json";
+/** The opencode plugin, relative to the project. */
+export declare const OPENCODE_PLUGIN_FILE = ".opencode/plugins/cleo-heavy-command.js";
+/**
+ * Keep a hook file CLEO wrote out of git when nothing ignores it yet: add a
+ * marked block naming this project's file to the repository's `info/exclude`,
+ * never to a tracked `.gitignore`. A file git already tracks is left alone (an
+ * exclude cannot untrack it). Keyed on the exact path line, so a second CLEO
  * project in a subdirectory of the same repository gets its own line.
  * Idempotent; does nothing outside a git work tree.
  *
  * @param projectDir - the project root.
+ * @param relPath - the file, relative to the project (forward slashes).
+ * @param marker - the block's first line.
+ * @returns whether a block was added.
+ */
+export declare function excludeHookFileFromGit(projectDir: string, relPath: string, marker?: string): boolean;
+/**
+ * Remove the block {@link excludeHookFileFromGit} added for this project's
+ * file, and only that: the exact path line and the CLEO marker right above it.
+ *
+ * @param projectDir - the project root.
+ * @param relPath - the file, relative to the project (forward slashes).
+ * @returns whether a block was removed.
+ */
+export declare function unexcludeHookFileFromGit(projectDir: string, relPath: string): boolean;
+/**
+ * Whether git sees a hook file as an untracked change: inside a work tree,
+ * not ignored and not tracked. Such a file shows up in `git status` and
+ * widens `cleo verify`'s evidence scope (gh#1805).
+ *
+ * @param projectDir - the project root.
+ * @param relPath - the file, relative to the project (forward slashes).
+ */
+export declare function hookFileVisibleToGit(projectDir: string, relPath: string): boolean;
+/**
+ * Keep `.claude/settings.local.json` out of git when nothing ignores it yet
+ * (Claude Code ignores the file only when it creates it itself). See
+ * {@link excludeHookFileFromGit}.
+ *
+ * @param projectDir - the project root.
  * @returns whether a block was added.
  */
 export declare function excludeLocalSettingsFromGit(projectDir: string): boolean;
 /**
  * Remove the block {@link excludeLocalSettingsFromGit} added for this
- * project, and only that: the exact path line and the marker right above it.
+ * project, and only that.
  *
  * @param projectDir - the project root.
  * @returns whether a block was removed.
  */
 export declare function unexcludeLocalSettingsFromGit(projectDir: string): boolean;
+/**
+ * A hook config CLEO will not add its per-machine hook to, because it is the
+ * project's own: Codex's `.codex/hooks.json` is committable, unlike Claude
+ * Code's `settings.local.json`. Writing there would put a per-machine hook
+ * into a team file, and excluding it would hide the team's file from git.
+ * Nothing is written; the delivery reports `needs-consent` with the entry to
+ * add by hand.
+ */
+export declare class HeavyHookSharedConfigError extends Error {
+    /** The project's own config file. */
+    readonly path: string;
+    /**
+     * @param path - the config file.
+     * @param why - what makes it the project's own.
+     */
+    constructor(path: string, why: string);
+}
+/**
+ * Why Codex's `.codex/hooks.json` in `projectDir` is the project's own config
+ * that CLEO must not write or hide, or `null` when CLEO may: the file is
+ * absent, or is one CLEO created and git does not track (review MED-3). An
+ * unreadable file is left to the sync, which refuses it.
+ *
+ * @param projectDir - the project root.
+ * @param checkGit - also ask git whether the file is tracked (one spawn);
+ *   `false` reads the file only (the session briefing).
+ */
+export declare function codexHooksSharedReason(projectDir: string, checkGit?: boolean): string | null;
+/**
+ * Whether the committed (`HEAD`) version of Codex's `.codex/hooks.json` holds
+ * CLEO's hook: the team adopted it, so mode `off` on one machine must not
+ * remove it from the tracked file (review MED-3b).
+ *
+ * @param projectDir - the project root.
+ */
+export declare function committedCodexHookHoldsCleo(projectDir: string): boolean;
+/**
+ * Mode `off` on a TRACKED `hooks.json` whose only change from `HEAD` is
+ * CLEO's hook: write `HEAD`'s exact bytes back, so the file returns to its
+ * committed state instead of being re-serialised with CLEO's formatting
+ * (review LOW-3). Returns whether it did.
+ *
+ * @param projectDir - the project root.
+ */
+export declare function restoreCommittedCodexHooks(projectDir: string): boolean;
+/**
+ * Whether CLEO's own marked `info/exclude` block names this project file
+ * (it hides the file from git).
+ *
+ * @param projectDir - the project root.
+ * @param relPath - the file, relative to the project (forward slashes).
+ */
+export declare function excludedByCleo(projectDir: string, relPath: string): boolean;
+/**
+ * The exact `PreToolUse` entry to add to Codex's `.codex/hooks.json` by hand,
+ * for a project whose own config CLEO does not write (`needs-consent`).
+ */
+export declare function codexHookSnippet(): string;
+/**
+ * Whether git tracks a project file and it has uncommitted changes.
+ *
+ * @param projectDir - the project root.
+ * @param relPath - the file, relative to the project (forward slashes).
+ */
+export declare function trackedFileModified(projectDir: string, relPath: string): boolean;
+/**
+ * Codex: sync the hook in `<project>/.codex/hooks.json` and keep that file out
+ * of git (T13124), as {@link syncClaudeCodeHeavyCommandHook} does for Claude
+ * Code's settings. A shared `hooks.json` (tracked, or holding hooks that are
+ * not CLEO's) is never written: {@link HeavyHookSharedConfigError}. Mode `off`
+ * still removes CLEO's own hook object from it.
+ *
+ * @param projectDir - the project root.
+ * @param mode - the resolved hook mode.
+ * @returns what changed in `hooks.json`.
+ * @throws {HeavyHookSharedConfigError} when `hooks.json` is shared.
+ */
+export declare function syncCodexHeavyCommandHook(projectDir: string, mode: HeavyCommandHookMode): Promise<HeavyHookSyncResult>;
 /**
  * Claude Code: sync the hook in `<project>/.claude/settings.local.json`, keep
  * that file out of git, and remove a hook an earlier build put in the shared
@@ -163,7 +308,8 @@ export declare function syncClaudeCodeHeavyCommandHook(projectDir: string, mode:
 export declare function opencodeHeavyCommandPluginSource(): string;
 /**
  * Write (or, mode `off`, delete) the opencode plugin in
- * `<projectDir>/.opencode/plugins/`. Rewritten only when its content changed.
+ * `<projectDir>/.opencode/plugins/`, and keep it out of git (T13124).
+ * Rewritten only when its content changed.
  *
  * @param projectDir - the project root.
  * @param mode - the resolved hook mode.

package/dist/providers/shared/heavy-command-hook-install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"heavy-command-hook-install.d.ts","sourceRoot":"","sources":["../../../src/providers/shared/heavy-command-hook-install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAeH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAGhE,oEAAoE;AACpE,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAE/D,iFAAiF;AACjF,eAAO,MAAM,8BAA8B,KAAK,CAAC;AAEjD,kDAAkD;AAClD,eAAO,MAAM,6BAA6B,0BAA0B,CAAC;AAErE;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EA+B5C,CAAC;AAEH;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;AAUhG;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,MAAkB,GAAG,OAAO,CAEnF;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,QAOjC,CAAC;AAEH,mFAAmF;AACnF,eAAO,MAAM,wBAAwB,2BAA2B,CAAC;AAEjE;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,GAAE,MAAgD,GACpD,MAAM,CAkBR;AAqDD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,GAAG,MAAM,CAIjF;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMjG;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEhG;AA4DD;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,aAAa,GAAG,OAAO,EACjC,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,mBAAmB,CAAC,CA4B9B;AAKD,+EAA+E;AAC/E,eAAO,MAAM,6BAA6B,sFAC2C,CAAC;AA6BtF;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAWvE;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CASzE;AAED;;;;;;;;GAQG;AACH,wBAAsB,8BAA8B,CAClD,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,mBAAmB,CAAC,CAc9B;AAED;;;;;;;;GAQG;AACH,wBAAgB,gCAAgC,IAAI,MAAM,CAmDzD;AAED;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,oBAAoB,GACzB,mBAAmB,CAarB"}
+{"version":3,"file":"heavy-command-hook-install.d.ts","sourceRoot":"","sources":["../../../src/providers/shared/heavy-command-hook-install.ts"],"names":[],"mappings":"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"}

package/dist/providers/shared/project-instruction-file.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A provider's PROJECT instruction file, skipped (not failed) at a project
+ * rooted at the home directory (T13227).
+ *
+ * Providers load CLAUDE.md / AGENTS.md / GEMINI.md from the working directory
+ * up through every ancestor, so a file at `$HOME` reaches every session under
+ * it: CAAMP refuses it with `HomeInstructionFileError`. An adapter's install
+ * reports that step as `skipped` and carries on with the rest, the way the
+ * heavy-command hook already skips the home directory (T12983).
+ *
+ * @task T13227
+ */
+import { type EnsureProviderInstructionFileOptions, type EnsureProviderInstructionFileResult } from '@cleocode/caamp';
+/**
+ * Ensure a provider's project instruction file, or `null` when the project is
+ * the home directory and the file was refused (nothing written).
+ *
+ * @param providerId - CAAMP provider id.
+ * @param projectDir - the project root.
+ * @param options - references, content, scope.
+ * @returns the CAAMP result, or `null` when skipped at `$HOME`.
+ *
+ * @example
+ * ```typescript
+ * const r = await ensureProjectInstructionFile('codex', projectDir, { scope: 'project' });
+ * if (r === null) details.instructionFile = 'skipped';
+ * ```
+ */
+export declare function ensureProjectInstructionFile(providerId: string, projectDir: string, options: EnsureProviderInstructionFileOptions): Promise<EnsureProviderInstructionFileResult | null>;
+//# sourceMappingURL=project-instruction-file.d.ts.map

package/dist/providers/shared/project-instruction-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-instruction-file.d.ts","sourceRoot":"","sources":["../../../src/providers/shared/project-instruction-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,KAAK,oCAAoC,EACzC,KAAK,mCAAmC,EAGzC,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,4BAA4B,CAChD,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,oCAAoC,GAC5C,OAAO,CAAC,mCAAmC,GAAG,IAAI,CAAC,CAOrD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/adapters",
-  "version": "2026.10.3",
+  "version": "2026.10.5-rc.ci.672",
   "description": "Unified provider adapters for CLEO (Claude Code, OpenCode, Cursor)",
   "type": "module",
   "main": "dist/index.js",
@@ -9,15 +9,19 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./heavy-command-hook": {
+      "types": "./dist/heavy-command-hook.d.ts",
+      "import": "./dist/heavy-command-hook.js"
     }
   },
   "dependencies": {
     "@ai-sdk/anthropic": "^3.0.69",
     "@ai-sdk/openai": "^2.0.53",
     "ai": "^6.0.168",
-    "@cleocode/caamp": "2026.10.3",
-    "@cleocode/contracts": "2026.10.3",
-    "@cleocode/paths": "2026.10.3"
+    "@cleocode/caamp": "2026.10.5-rc.ci.672",
+    "@cleocode/contracts": "2026.10.5-rc.ci.672",
+    "@cleocode/paths": "2026.10.5-rc.ci.672"
   },
   "license": "MIT",
   "engines": {
@@ -30,7 +34,7 @@
   "devDependencies": {
     "@types/node": "^24.3.0",
     "vitest": "^4.1.4",
-    "@cleocode/playbooks": "2026.10.3"
+    "@cleocode/playbooks": "2026.10.5-rc.ci.672"
   },
   "repository": {
     "type": "git",

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

@@ -7,7 +7,7 @@
  * @task T5240
  */
 
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import {
@@ -108,11 +108,16 @@ describe('ClaudeCodeHookProvider — integration', () => {
   });
 
   it('tracks registration state', async () => {
-    expect(hooks.isRegistered()).toBe(false);
-    await hooks.registerNativeHooks('/tmp/test');
-    expect(hooks.isRegistered()).toBe(true);
-    await hooks.unregisterNativeHooks();
-    expect(hooks.isRegistered()).toBe(false);
+    const projectDir = mkdtempSync(join(tmpdir(), 'cleo-claude-hooks-'));
+    try {
+      expect(hooks.isRegistered()).toBe(false);
+      await hooks.registerNativeHooks(projectDir);
+      expect(hooks.isRegistered()).toBe(true);
+      await hooks.unregisterNativeHooks();
+      expect(hooks.isRegistered()).toBe(false);
+    } finally {
+      rmSync(projectDir, { recursive: true, force: true });
+    }
   });
 
   it('exposes event map for introspection', () => {

package/src/heavy-command-hook.ts

@@ -0,0 +1,21 @@
+/**
+ * `@cleocode/adapters/heavy-command-hook`: project-level delivery of CLEO's
+ * heavy-command hook (T13124). A light entry point: `@cleocode/core` loads it
+ * at run time for `cleo init`, `cleo upgrade`, `cleo doctor` and the session
+ * briefing without pulling in every provider adapter.
+ *
+ * @packageDocumentation
+ * @task T13124
+ */
+
+export type { HeavyHookDetection } from './providers/shared/heavy-command-hook-delivery.js';
+export {
+  detectHeavyHookProvider,
+  HEAVY_HOOK_DELIVERY_PROVIDERS,
+  HEAVY_HOOK_FIX_COMMAND,
+  heavyHookDeliveryApi,
+  heavyHookTarget,
+  inspectProjectHeavyCommandHooks,
+  probeHeavyHookCli,
+  syncProjectHeavyCommandHooks,
+} from './providers/shared/heavy-command-hook-delivery.js';

package/src/index.ts

@@ -87,6 +87,18 @@ export {
   OpenCodeInstallProvider,
   OpenCodeSpawnProvider,
 } from './providers/opencode/index.js';
+// T13124 — project-level heavy-command hook delivery (also `@cleocode/adapters/heavy-command-hook`).
+export type { HeavyHookDetection } from './providers/shared/heavy-command-hook-delivery.js';
+export {
+  detectHeavyHookProvider,
+  HEAVY_HOOK_DELIVERY_PROVIDERS,
+  HEAVY_HOOK_FIX_COMMAND,
+  heavyHookDeliveryApi,
+  heavyHookTarget,
+  inspectProjectHeavyCommandHooks,
+  probeHeavyHookCli,
+  syncProjectHeavyCommandHooks,
+} from './providers/shared/heavy-command-hook-delivery.js';
 export type {
   HookTemplateProviderId,
   InstallHookTemplatesOptions,

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

@@ -3,9 +3,10 @@
  *
  * Validates that:
  * - Shared `cleo-precompact-core.sh` and provider-specific
- *   `precompact-safestop.sh` are copied into `~/.claude/hooks/`.
- * - `~/.claude/settings.json` gains a `PreCompact` entry pointing at the
- *   installed shim, tagged with the `# cleo-hook` sentinel for clean uninstall.
+ *   `precompact-safestop.sh` are copied into the PROJECT's `.claude/hooks/`.
+ * - The project's `.claude/settings.local.json` gains a `PreCompact` entry
+ *   pointing at the installed shim, tagged with the `# cleo-hook` sentinel.
+ * - The user-global `$CLAUDE_HOME` is never written (T13227).
  * - Repeat invocations are idempotent (no duplicate settings entries).
  * - The source templates contain the universal CLEO CLI invocations so the
  *   bash contract remains DRY across providers.
@@ -14,6 +15,7 @@
  * impersonates `$HOME` via the `HOME` env var, so no user config is touched.
  *
  * @task T1013
+ * @task T13227
  * @epic T1000
  */
 
@@ -67,7 +69,7 @@ describe('ClaudeCodeInstallProvider — PreCompact hook templates', () => {
     rmSync(projectDir, { recursive: true, force: true });
   });
 
-  it('installs both bash templates into $HOME/.claude/hooks/', async () => {
+  it('installs both bash templates into the project .claude/hooks/', async () => {
     const provider = new ClaudeCodeInstallProvider();
 
     const result = await provider.install({ projectDir });
@@ -79,20 +81,21 @@ describe('ClaudeCodeInstallProvider — PreCompact hook templates', () => {
     } | null;
 
     expect(hookTemplates).not.toBeNull();
-    expect(hookTemplates?.templates.targetDir).toBe(join(fakeHome, '.claude', 'hooks'));
+    expect(hookTemplates?.templates.targetDir).toBe(join(projectDir, '.claude', 'hooks'));
+    expect(existsSync(join(fakeHome, '.claude'))).toBe(false);
     const installed = hookTemplates?.templates.installedFiles ?? [];
     expect(installed.some((p) => p.endsWith('cleo-precompact-core.sh'))).toBe(true);
     expect(installed.some((p) => p.endsWith('precompact-safestop.sh'))).toBe(true);
 
     // Installed shim sources the shared helper.
     const shim = readFileSync(
-      join(fakeHome, '.claude', 'hooks', 'precompact-safestop.sh'),
+      join(projectDir, '.claude', 'hooks', 'precompact-safestop.sh'),
       'utf-8',
     );
     expect(shim).toContain('cleo-precompact-core.sh');
     // Shared helper invokes the universal CLEO CLI.
     const core = readFileSync(
-      join(fakeHome, '.claude', 'hooks', 'cleo-precompact-core.sh'),
+      join(projectDir, '.claude', 'hooks', 'cleo-precompact-core.sh'),
       'utf-8',
     );
     expect(core).toContain('cleo memory precompact-flush');
@@ -100,11 +103,11 @@ describe('ClaudeCodeInstallProvider — PreCompact hook templates', () => {
     expect(core).toMatch(/cleo_cmd.*safestop/);
   });
 
-  it('writes a PreCompact entry into $HOME/.claude/settings.json tagged # cleo-hook', async () => {
+  it('writes a PreCompact entry into the project settings.local.json tagged # cleo-hook', async () => {
     const provider = new ClaudeCodeInstallProvider();
     await provider.install({ projectDir });
 
-    const settingsPath = join(fakeHome, '.claude', 'settings.json');
+    const settingsPath = join(projectDir, '.claude', 'settings.local.json');
     const settings = JSON.parse(readFileSync(settingsPath, 'utf-8')) as {
       hooks?: Record<string, Array<{ hooks?: Array<{ command?: string; type?: string }> }>>;
     };
@@ -124,7 +127,7 @@ describe('ClaudeCodeInstallProvider — PreCompact hook templates', () => {
     await provider.install({ projectDir });
     await provider.install({ projectDir });
 
-    const settingsPath = join(fakeHome, '.claude', 'settings.json');
+    const settingsPath = join(projectDir, '.claude', 'settings.local.json');
     const settings = JSON.parse(readFileSync(settingsPath, 'utf-8')) as {
       hooks?: { PreCompact?: unknown[] };
     };
@@ -134,12 +137,12 @@ describe('ClaudeCodeInstallProvider — PreCompact hook templates', () => {
   // 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', () => {
+  describe('T12385 — malformed settings file 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 });
+      const settingsPath = join(projectDir, '.claude', 'settings.local.json');
+      mkdirSync(join(projectDir, '.claude'), { recursive: true });
       writeFileSync(settingsPath, malformed, 'utf-8');
 
       const result = await new ClaudeCodeInstallProvider().install({ projectDir });
@@ -153,8 +156,8 @@ describe('ClaudeCodeInstallProvider — PreCompact hook templates', () => {
     });
 
     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 });
+      const settingsPath = join(projectDir, '.claude', 'settings.local.json');
+      mkdirSync(join(projectDir, '.claude'), { recursive: true });
       writeFileSync(settingsPath, malformed, 'utf-8');
       const stderr = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
 
@@ -168,8 +171,8 @@ describe('ClaudeCodeInstallProvider — PreCompact hook templates', () => {
     });
 
     it('preserves unrelated user settings when it does write', async () => {
-      const settingsPath = join(fakeHome, '.claude', 'settings.json');
-      mkdirSync(join(fakeHome, '.claude'), { recursive: true });
+      const settingsPath = join(projectDir, '.claude', 'settings.local.json');
+      mkdirSync(join(projectDir, '.claude'), { recursive: true });
       writeFileSync(
         settingsPath,
         JSON.stringify({ model: 'opus', hooks: { Stop: [{ matcher: 'x', hooks: [] }] } }),