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

package/src/providers/claude-code/__tests__/no-user-global-write.test.ts

@@ -0,0 +1,293 @@
+/**
+ * The Claude Code adapter never writes the user-global Claude config (T13227).
+ *
+ * `ClaudeCodeAdapter.initialize` (native hooks), the install provider (plugin
+ * + PreCompact hook templates) and `dispose` (hook removal) all write the
+ * PROJECT's `.claude/` only. Every case runs in a sandbox: `HOME`,
+ * `CLAUDE_HOME` and `CLAUDE_SETTINGS` point into a throwaway dir, and the
+ * user-global dir there is snapshotted (bytes + mtime of every file) before
+ * and compared after. The real `~/.claude` is never read.
+ *
+ * @task T13227
+ */
+
+import { execFileSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// initialize() asks the `cleo` binary for the spawn mode; never run a real one.
+vi.mock('node:child_process', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:child_process')>();
+  return {
+    ...actual,
+    execFile: (...args: unknown[]) => {
+      const callback = args[args.length - 1];
+      if (typeof callback === 'function') callback(new Error('cleo not available in test'));
+    },
+  };
+});
+
+import { ClaudeCodeAdapter } from '../adapter.js';
+import { ClaudeCodeHookProvider, NATIVE_STOP_HOOK_COMMAND } from '../hooks.js';
+import { ClaudeCodeInstallProvider } from '../install.js';
+
+/** Every file under `dir`, as path → bytes + mtime. */
+function snapshot(dir: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!existsSync(dir)) return out;
+  for (const name of readdirSync(dir, { recursive: true, encoding: 'utf-8' })) {
+    const path = join(dir, name);
+    const st = statSync(path);
+    out[name] = st.isDirectory()
+      ? `dir@${st.mtimeMs}`
+      : `${readFileSync(path, 'base64')}@${st.mtimeMs}`;
+  }
+  return out;
+}
+
+/** What a user's own global Claude config holds. */
+const USER_SETTINGS = JSON.stringify(
+  {
+    model: 'opus',
+    enabledPlugins: { 'other@market': true },
+    hooks: { Stop: [{ matcher: '', hooks: [{ type: 'command', command: 'my-stop.sh' }] }] },
+  },
+  null,
+  2,
+);
+
+const SAVED = ['HOME', 'USERPROFILE', 'CLAUDE_HOME', 'CLAUDE_SETTINGS'] as const;
+let saved: Record<string, string | undefined>;
+let root: string;
+let home: string;
+let claudeHome: string;
+let projectDir: string;
+
+beforeEach(() => {
+  saved = Object.fromEntries(SAVED.map((k) => [k, process.env[k]]));
+  root = mkdtempSync(join(tmpdir(), 'cleo-claude-global-'));
+  home = join(root, 'home');
+  claudeHome = join(home, '.claude');
+  projectDir = join(root, 'project');
+  mkdirSync(join(claudeHome, 'hooks'), { recursive: true });
+  mkdirSync(projectDir, { recursive: true });
+  writeFileSync(join(claudeHome, 'settings.json'), USER_SETTINGS);
+  writeFileSync(join(claudeHome, 'hooks', 'mine.sh'), '#!/bin/sh\n');
+  execFileSync('git', ['init', '-q', projectDir]);
+  process.env.HOME = home;
+  process.env.USERPROFILE = home;
+  process.env.CLAUDE_HOME = claudeHome;
+  delete process.env.CLAUDE_SETTINGS;
+  mkdirSync(join(home, '.cleo', 'templates'), { recursive: true });
+  writeFileSync(join(home, '.cleo', 'templates', 'CLEO-INJECTION.md'), 'Fixture protocol.');
+});
+
+afterEach(() => {
+  for (const k of SAVED) {
+    const v = saved[k];
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  }
+  rmSync(root, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+/** Run every adapter writer for `dir`: initialize, install, dispose. */
+async function runAllWriters(dir: string): Promise<{
+  adapter: ClaudeCodeAdapter;
+  install: Awaited<ReturnType<ClaudeCodeInstallProvider['install']>>;
+}> {
+  const adapter = new ClaudeCodeAdapter();
+  await adapter.initialize(dir);
+  const install = await new ClaudeCodeInstallProvider().install({ projectDir: dir });
+  await adapter.dispose();
+  return { adapter, install };
+}
+
+describe('Claude Code adapter never writes the user-global Claude config (T13227)', () => {
+  it('initialize + install + dispose leave CLAUDE_HOME byte-identical and write the project', async () => {
+    const before = snapshot(claudeHome);
+    const adapter = new ClaudeCodeAdapter();
+
+    await adapter.initialize(projectDir);
+    const local = join(projectDir, '.claude', 'settings.local.json');
+    const afterInit = JSON.parse(readFileSync(local, 'utf-8')) as {
+      hooks: Record<string, Array<{ hooks: Array<{ command: string }> }>>;
+    };
+    expect(afterInit.hooks.Stop?.[0]?.hooks[0]?.command).toBe(NATIVE_STOP_HOOK_COMMAND);
+    expect(afterInit.hooks.PostToolUse?.[0]?.hooks).toHaveLength(2);
+
+    const result = await new ClaudeCodeInstallProvider().install({ projectDir });
+    expect(result.success).toBe(true);
+    const afterInstall = JSON.parse(readFileSync(local, 'utf-8')) as {
+      enabledPlugins: Record<string, boolean>;
+      hooks: Record<string, unknown[]>;
+    };
+    expect(afterInstall.enabledPlugins['cleo@cleocode']).toBe(true);
+    expect(afterInstall.hooks.PreCompact).toHaveLength(1);
+    expect(existsSync(join(projectDir, '.claude', 'hooks', 'precompact-safestop.sh'))).toBe(true);
+
+    await adapter.dispose();
+
+    expect(snapshot(claudeHome)).toEqual(before);
+    expect(readFileSync(join(claudeHome, 'settings.json'), 'utf-8')).toBe(USER_SETTINGS);
+    // The per-machine files are kept out of git.
+    const exclude = readFileSync(join(projectDir, '.git', 'info', 'exclude'), 'utf-8');
+    expect(exclude).toContain('/.claude/settings.local.json');
+    expect(exclude).toContain('/.claude/hooks/precompact-safestop.sh');
+  });
+
+  it('a project that is the home directory is refused: nothing written, steps skipped', async () => {
+    const before = snapshot(claudeHome);
+    const stderr = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+
+    const hooks = new ClaudeCodeHookProvider();
+    await hooks.registerNativeHooks(home);
+    const { install } = await runAllWriters(home);
+
+    expect(snapshot(claudeHome)).toEqual(before);
+    expect(hooks.getSettingsError()).toMatch(
+      /refusing to write .*the project is the home directory/,
+    );
+    expect(install.details?.plugin).toBe('skipped');
+    expect(install.details?.hookTemplates).toBe('skipped');
+    // ~/CLAUDE.md is loaded into every session under $HOME (#1898 review MED).
+    expect(install.details?.instructionFile).toBe('skipped');
+    expect(existsSync(join(home, 'CLAUDE.md'))).toBe(false);
+    await expect(new ClaudeCodeInstallProvider().ensureInstructionReferences(home)).rejects.toThrow(
+      /the project is the home directory/,
+    );
+    expect(existsSync(join(home, 'CLAUDE.md'))).toBe(false);
+    expect(stderr).toHaveBeenCalled();
+  });
+
+  it('the home directory is refused even when CLAUDE_HOME points elsewhere', async () => {
+    process.env.CLAUDE_HOME = join(root, 'elsewhere', '.claude');
+    vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    const before = snapshot(join(home, '.claude'));
+
+    const { install } = await runAllWriters(home);
+
+    expect(snapshot(join(home, '.claude'))).toEqual(before);
+    expect(install.details?.instructionFile).toBe('skipped');
+    expect(existsSync(join(home, 'CLAUDE.md'))).toBe(false);
+    expect(install.details?.plugin).toBe('skipped');
+    expect(install.details?.commands).toBe('skipped');
+  });
+
+  it('CLAUDE_HOME pointing at the project .claude is refused: nothing written', async () => {
+    const projectClaude = join(projectDir, '.claude');
+    mkdirSync(projectClaude, { recursive: true });
+    writeFileSync(join(projectClaude, 'settings.json'), USER_SETTINGS);
+    process.env.CLAUDE_HOME = projectClaude;
+    vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    const before = snapshot(projectClaude);
+
+    const { install } = await runAllWriters(projectDir);
+
+    expect(snapshot(projectClaude)).toEqual(before);
+    expect(install.details?.plugin).toBe('skipped');
+    expect(install.details?.hookTemplates).toBe('skipped');
+  });
+
+  it('the Claude dir itself as the project is refused, CLAUDE.md included', async () => {
+    vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    const before = snapshot(claudeHome);
+
+    const { install } = await runAllWriters(claudeHome);
+
+    expect(snapshot(claudeHome)).toEqual(before);
+    expect(install.details?.instructionFile).toBe('skipped');
+    expect(install.details?.commands).toBe('skipped');
+    await expect(
+      new ClaudeCodeInstallProvider().ensureInstructionReferences(claudeHome),
+    ).rejects.toThrow(/inside the user-global Claude config dir/);
+    expect(existsSync(join(claudeHome, 'CLAUDE.md'))).toBe(false);
+  });
+
+  it('a differently cased spelling of the Claude dir is refused on a case-insensitive volume', async (ctx) => {
+    const variant = join(home, '.CLAUDE');
+    // Only meaningful where the volume folds case (default APFS / NTFS).
+    if (!existsSync(variant)) ctx.skip();
+    vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    const before = snapshot(claudeHome);
+
+    const hooks = new ClaudeCodeHookProvider();
+    await hooks.registerNativeHooks(variant);
+    const { install } = await runAllWriters(variant);
+
+    expect(snapshot(claudeHome)).toEqual(before);
+    expect(hooks.getSettingsError()).toMatch(/inside the user-global Claude config dir/);
+    expect(install.details?.instructionFile).toBe('skipped');
+    expect(install.details?.plugin).toBe('skipped');
+    expect(install.details?.hookTemplates).toBe('skipped');
+    expect(install.details?.commands).toBe('skipped');
+  });
+
+  it('a differently cased spelling of the home directory is refused on a case-insensitive volume', async (ctx) => {
+    const variant = home.replace(/home$/, 'HOME');
+    if (!existsSync(variant)) ctx.skip();
+    process.env.CLAUDE_HOME = join(root, 'elsewhere', '.claude');
+    vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    const before = snapshot(claudeHome);
+
+    const { install } = await runAllWriters(variant);
+
+    expect(snapshot(claudeHome)).toEqual(before);
+    expect(install.details?.plugin).toBe('skipped');
+  });
+
+  it('CLAUDE_SETTINGS naming the project settings.local.json is refused: nothing written', async () => {
+    const local = join(projectDir, '.claude', 'settings.local.json');
+    process.env.CLAUDE_SETTINGS = local;
+    vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    const before = snapshot(claudeHome);
+
+    const { install } = await runAllWriters(projectDir);
+
+    expect(existsSync(local)).toBe(false);
+    expect(snapshot(claudeHome)).toEqual(before);
+    expect(install.details?.plugin).toBe('skipped');
+  });
+
+  it('dispose removes only the native hook objects; the heavy-command and user hooks stay', async () => {
+    const local = join(projectDir, '.claude', 'settings.local.json');
+    mkdirSync(join(projectDir, '.claude'), { recursive: true });
+    const heavy = {
+      matcher: 'Bash',
+      hooks: [{ type: 'command', command: 'cleo hook heavy-command # cleo-hook', timeout: 20 }],
+    };
+    writeFileSync(
+      local,
+      JSON.stringify({
+        hooks: {
+          PreToolUse: [heavy],
+          Stop: [{ matcher: '', hooks: [{ type: 'command', command: 'my-stop.sh' }] }],
+        },
+      }),
+    );
+    const adapter = new ClaudeCodeAdapter();
+
+    await adapter.initialize(projectDir);
+    // Wired beside the heavy-command hook (which is not a native hook).
+    expect(readFileSync(local, 'utf-8')).toContain(JSON.stringify(NATIVE_STOP_HOOK_COMMAND));
+    await adapter.dispose();
+
+    const after = JSON.parse(readFileSync(local, 'utf-8')) as { hooks: Record<string, unknown> };
+    expect(after.hooks).toEqual({
+      PreToolUse: [heavy],
+      Stop: [{ matcher: '', hooks: [{ type: 'command', command: 'my-stop.sh' }] }],
+    });
+  });
+});

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

@@ -159,7 +159,9 @@ export class ClaudeCodeAdapter implements CLEOProviderAdapter {
     }
 
     // Activate CLEO hook bridge for this project — connects Claude Code
-    // native events to CLEO's internal hook dispatch (T555).
+    // native events to CLEO's internal hook dispatch (T555). Written to the
+    // project's .claude/settings.local.json only, never the user-global
+    // ~/.claude/settings.json (T13227).
     await this.hooks.registerNativeHooks(projectDir);
   }
 

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

@@ -21,13 +21,85 @@ import { readdir, readFile } from 'node:fs/promises';
 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';
+import { excludeLocalSettingsFromGit } from '../shared/heavy-command-hook-install.js';
+import { appendHookEntry, hookMap, isPlainObject, projectClaudeSettingsPath } from './paths.js';
+
+/** The `Stop` hook command: end the CLEO session when Claude Code stops. */
+export const NATIVE_STOP_HOOK_COMMAND = 'cleo session end --quiet # cleo-hook';
+
+/** The `PostToolUse` (`Write|Edit`) hook command: a brain observation per file write. */
+export const NATIVE_OBSERVE_HOOK_COMMAND =
+  'cleo observe "File modified via $TOOL_NAME" --title "tool-use" --quiet # cleo-hook';
+
+/**
+ * The `PostToolUse` (`Write|Edit`) NEXUS post-check: re-index changed files and
+ * flag regressions. `$TOOL_INPUT_file_path` is populated by Claude Code for
+ * Write/Edit events.
+ */
+export const NATIVE_NEXUS_HOOK_COMMAND =
+  'cleo nexus analyze --incremental --json > /dev/null 2>&1 && cleo observe "NEXUS re-indexed after $TOOL_NAME on $TOOL_INPUT_file_path" --title "nexus-post-check" --quiet # cleo-hook';
+
+/** Every command {@link ClaudeCodeHookProvider.registerNativeHooks} writes, and alone may remove. */
+const NATIVE_HOOK_COMMANDS: ReadonlySet<string> = new Set([
+  NATIVE_STOP_HOOK_COMMAND,
+  NATIVE_OBSERVE_HOOK_COMMAND,
+  NATIVE_NEXUS_HOOK_COMMAND,
+]);
+
+/** Whether a hook object is one of the adapter's native hooks (never the heavy-command hook or a user's). */
+function isNativeHookObject(hook: unknown): boolean {
+  return (
+    isPlainObject(hook) &&
+    typeof hook.command === 'string' &&
+    NATIVE_HOOK_COMMANDS.has(hook.command)
+  );
+}
+
+/** Whether any event of a `hooks` map already holds a native hook. */
+function hasNativeHooks(hooks: Record<string, unknown>): boolean {
+  return Object.values(hooks).some(
+    (entries) =>
+      Array.isArray(entries) &&
+      entries.some(
+        (entry) =>
+          isPlainObject(entry) &&
+          Array.isArray(entry.hooks) &&
+          entry.hooks.some(isNativeHookObject),
+      ),
+  );
+}
+
+/**
+ * Remove the native hook objects from every event, then any entry left with
+ * no hooks and any event left with no entries. Other hooks sharing an entry
+ * (the heavy-command hook, the user's own) stay.
+ */
+function removeNativeHooks(hooks: Record<string, unknown>): boolean {
+  let changed = false;
+  for (const [event, entries] of Object.entries(hooks)) {
+    if (!Array.isArray(entries)) continue;
+    const kept: unknown[] = [];
+    let eventChanged = false;
+    for (const entry of entries) {
+      if (
+        !isPlainObject(entry) ||
+        !Array.isArray(entry.hooks) ||
+        !entry.hooks.some(isNativeHookObject)
+      ) {
+        kept.push(entry);
+        continue;
+      }
+      eventChanged = true;
+      const rest = entry.hooks.filter((hook) => !isNativeHookObject(hook));
+      if (rest.length > 0) kept.push({ ...entry, hooks: rest });
+    }
+    if (!eventChanged) continue;
+    changed = true;
+    if (kept.length === 0) delete hooks[event];
+    else hooks[event] = kept;
+  }
+  return changed;
+}
 
 /** CAAMP provider identifier for Claude Code. */
 const PROVIDER_ID = 'claude-code' as const;
@@ -76,8 +148,10 @@ const CLAUDE_CODE_EVENT_MAP: Record<string, string> = {
 /**
  * Hook provider for Claude Code.
  *
- * Claude Code registers hooks via its global config at `~/.claude/settings.json`.
- * Supported handler types: command, http, prompt, agent.
+ * CLEO registers its Claude Code hooks in the project's per-machine
+ * `<project>/.claude/settings.local.json`, never in the user-global
+ * `~/.claude/settings.json` (T13227). Supported handler types: command, http,
+ * prompt, agent.
  *
  * Event mapping is based on `getProviderHookProfile('claude-code')` from
  * CAAMP 1.9.1. Async accessors (`getSupportedCanonicalEvents`,
@@ -122,76 +196,79 @@ export class ClaudeCodeHookProvider implements AdapterHookProvider {
   /**
    * Register native hooks for a project.
    *
-   * Writes CLEO hook entries to `~/.claude/settings.json` so that Claude Code's
-   * native event system calls cleo CLI commands when events fire. This bridges
-   * Claude Code's event loop to CLEO's internal hook dispatch.
+   * Writes CLEO hook entries to the project's per-machine
+   * `<project>/.claude/settings.local.json` so that Claude Code's native event
+   * system calls cleo CLI commands when events fire in this project. This
+   * bridges Claude Code's event loop to CLEO's internal hook dispatch.
+   * CLEO never writes the user-global `~/.claude/settings.json` (T13227): a
+   * project that is the home directory, or whose settings file resolves into
+   * the user-global Claude config, is refused and nothing is written. When
+   * git does not ignore `settings.local.json` yet, a marked `info/exclude`
+   * block keeps it out of git (the T12983 heavy-command rule).
    *
-   * Idempotent: skips writing if CLEO hooks already exist in settings.json.
+   * Idempotent: skips writing if the native hooks are already present.
    *
    * Hook entries registered:
    * - `Stop` → `cleo session end --quiet` (triggers LLM extraction, reflector, consolidation)
    * - `PostToolUse` (Write|Edit) → brain observation for file modifications
-   * - `SubagentStop` → brain observation for agent completion
+   *   and the NEXUS post-check
    *
-   * @param projectDir - Project directory for context-scoped hook commands
-   * @task T164 @task T555
+   * @param projectDir - Project whose Claude Code settings receive the hooks
+   * @task T164 @task T555 @task T13227
    */
   async registerNativeHooks(projectDir: string): Promise<void> {
     this.projectDir = projectDir;
     this.registered = true;
 
-    // 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) => {
+    // T12385: locked, atomic, and a malformed file is reported and left
+    // untouched — never replaced with an object holding only CLEO's entries.
+    const wrote = await this.updateSettings(projectDir, (settings) => {
       const hooks = hookMap(settings);
-      if (Object.values(hooks).some((entries) => hasCleoHook(entries))) {
-        return false; // Already wired — idempotent
-      }
+      if (hasNativeHooks(hooks)) return false; // Already wired — idempotent
 
-      // Register Stop hook → triggers cleo session end (LLM extraction, reflector, consolidation)
       appendHookEntry(hooks, 'Stop', {
         matcher: '',
-        hooks: [{ type: 'command', command: `cleo session end --quiet # cleo-hook` }],
+        hooks: [{ type: 'command', command: NATIVE_STOP_HOOK_COMMAND }],
       });
-
-      // Register PostToolUse hook → brain observation for file writes + NEXUS post-check (T625)
       appendHookEntry(hooks, 'PostToolUse', {
         matcher: 'Write|Edit',
         hooks: [
-          {
-            type: 'command',
-            command: `cleo observe "File modified via $TOOL_NAME" --title "tool-use" --quiet # cleo-hook`,
-          },
-          {
-            // NEXUS post-modification check: re-index changed files and flag regressions.
-            // $TOOL_INPUT_file_path is populated by Claude Code for Write/Edit events.
-            type: 'command',
-            command: `cleo nexus analyze --incremental --json > /dev/null 2>&1 && cleo observe "NEXUS re-indexed after $TOOL_NAME on $TOOL_INPUT_file_path" --title "nexus-post-check" --quiet # cleo-hook`,
-          },
+          { type: 'command', command: NATIVE_OBSERVE_HOOK_COMMAND },
+          { type: 'command', command: NATIVE_NEXUS_HOOK_COMMAND },
         ],
       });
       return true;
     });
+    if (wrote) excludeLocalSettingsFromGit(projectDir);
   }
 
   /**
    * Unregister native hooks.
    *
-   * 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}.
+   * Removes the hook objects {@link registerNativeHooks} wrote from the
+   * project's `settings.local.json`, and nothing else: the heavy-command hook
+   * and the user's own hooks stay, and an entry or event is dropped only when
+   * left empty. Same locking, atomicity, parse-error and project-scope rules
+   * as {@link registerNativeHooks}.
    *
-   * @task T164 @task T555
+   * @task T164 @task T555 @task T13227
    */
   async unregisterNativeHooks(): Promise<void> {
+    const projectDir = this.projectDir;
     this.registered = false;
     this.projectDir = null;
+    if (projectDir === null) return;
 
-    if (!existsSync(claudeSettingsPath())) return;
-    await this.updateSettings((settings) => {
+    let settingsPath: string;
+    try {
+      settingsPath = projectClaudeSettingsPath(projectDir);
+    } catch {
+      return; // Never written there, so nothing to remove.
+    }
+    if (!existsSync(settingsPath)) return;
+    await this.updateSettings(projectDir, (settings) => {
       if (settings.hooks === undefined) return false;
-      return removeCleoHookEntries(hookMap(settings));
+      return removeNativeHooks(hookMap(settings));
     });
   }
 
@@ -199,12 +276,13 @@ export class ClaudeCodeHookProvider implements AdapterHookProvider {
   private settingsError: string | null = null;
 
   /**
-   * Why the last settings.json update did not happen, or `null`.
+   * Why the last settings 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).
+   * refused write (malformed settings file, lock timeout, a user-global
+   * target) is surfaced here and on stderr instead of being swallowed
+   * (T12385, T13227).
    *
    * @returns The failure message, or `null`
    */
@@ -212,19 +290,28 @@ export class ClaudeCodeHookProvider implements AdapterHookProvider {
     return this.settingsError;
   }
 
-  /** Apply `mutate` to settings.json via CAAMP's locked, atomic JSON writer. */
+  /**
+   * Apply `mutate` to the project's `settings.local.json` via CAAMP's locked,
+   * atomic JSON writer.
+   *
+   * @returns whether the file was written.
+   */
   private async updateSettings(
+    projectDir: string,
     mutate: (settings: Record<string, unknown>) => boolean,
-  ): Promise<void> {
-    const settingsPath = claudeSettingsPath();
+  ): Promise<boolean> {
+    let settingsPath = `${projectDir}/.claude/settings.local.json`;
     try {
-      await updateJsonConfigFile(settingsPath, mutate);
+      settingsPath = projectClaudeSettingsPath(projectDir);
+      const wrote = await updateJsonConfigFile(settingsPath, mutate);
       this.settingsError = null;
+      return wrote;
     } 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`,
       );
+      return false;
     }
   }