@cleocode/adapters 2026.10.4 → 2026.10.5

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

@@ -3,23 +3,32 @@
  *
  * Handles CLEO installation into Claude Code environments:
  * - Ensures CLAUDE.md has CLEO @-references
- * - Manages plugin registration in ~/.claude/settings.json
+ * - Manages plugin registration in the PROJECT's `.claude/settings.local.json`
+ * - Installs the PreCompact hook templates in the PROJECT's `.claude/hooks/`
  * - Installs the heavy-command `PreToolUse` hook in the PROJECT's
  *   `.claude/settings.local.json` (T12983)
  *
+ * Project-level only (T13227): CLEO never writes the user-global
+ * `~/.claude/settings.json` or `~/.claude/hooks/` (`CLAUDE_HOME`,
+ * `CLAUDE_SETTINGS`). A project that is the home directory, or whose
+ * `.claude/` resolves into the user-global Claude config, gets those steps
+ * reported as `skipped` and nothing is written there.
+ *
  * Migrated from src/core/install/claude-plugin.ts
  *
  * @task T5240
  * @task T12983
+ * @task T13227
  */
 
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { ensureProviderInstructionFile, updateJsonConfigFile } from '@cleocode/caamp';
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
 import {
+  excludeHookFileFromGit,
+  excludeLocalSettingsFromGit,
   isUserHomeDir,
   syncClaudeCodeHeavyCommandHook,
 } from '../shared/heavy-command-hook-install.js';
@@ -29,16 +38,25 @@ import {
 } from '../shared/hook-template-installer.js';
 import {
   appendHookEntry,
+  assertProjectInstructionScope,
   claudeSettingsPath,
   hasCleoHook,
   hookMap,
   isPlainObject,
+  projectClaudeCommandsDir,
+  projectClaudeHooksDir,
+  projectClaudeSettingsPath,
+  UserGlobalClaudeConfigError,
 } from './paths.js';
 
-/** Resolve Claude Code's config directory, honoring the documented CI override. */
-function getClaudeConfigDir(): string {
-  return process.env['CLAUDE_HOME'] ?? join(homedir(), '.claude');
-}
+/** The plugin the install enables in the project's Claude settings. */
+const CLEO_PLUGIN_KEY = 'cleo@cleocode';
+
+/** The PreCompact hook scripts the install copies, relative to the project. */
+const PROJECT_HOOK_FILES = [
+  '.claude/hooks/precompact-safestop.sh',
+  '.claude/hooks/cleo-precompact-core.sh',
+] as const;
 
 /** Resolve the commands directory bundled with this adapter. */
 function getAdapterCommandsDir(): string {
@@ -52,19 +70,25 @@ function getAdapterCommandsDir(): string {
  *
  * Manages CLEO's integration with Claude Code by:
  * 1. Ensuring CLAUDE.md contains @-references to CLEO instruction files
- * 2. Installing adapter-provided commands to .claude/commands/
- * 3. Registering the brain observation plugin in ~/.claude/settings.json
- * 4. Installing PreCompact hook templates
+ * 2. Installing adapter-provided commands to the project's .claude/commands/
+ * 3. Registering the brain observation plugin in the project's
+ *    `.claude/settings.local.json`
+ * 4. Installing PreCompact hook templates in the project's `.claude/hooks/`
+ *    and wiring them into the project's `.claude/settings.local.json`
  * 5. Installing the heavy-command `PreToolUse` hook in the project's
  *    `.claude/settings.local.json`, when `options.heavyCommandHook` is set
  *
  * @remarks
  * Installation is idempotent -- running install multiple times on the same
  * project produces the same result. The provider disables the legacy
- * `claude-mem\@thedotmack` plugin if present and enables the unified
- * `cleo\@cleocode` plugin instead.
+ * `claude-mem\@thedotmack` plugin for the project if present and enables the
+ * unified `cleo\@cleocode` plugin instead. Nothing is written to the
+ * user-global Claude config (T13227).
  */
 export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
+  /** The project the last {@link install} ran for; {@link isInstalled} reads its settings. */
+  private projectDir: string | null = null;
+
   /**
    * Install CLEO into a Claude Code project.
    *
@@ -73,46 +97,64 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
    */
   async install(options: InstallOptions): Promise<InstallResult> {
     const { projectDir } = options;
+    this.projectDir = projectDir;
     const installedAt = new Date().toISOString();
     let instructionFileUpdated = false;
     const details: Record<string, unknown> = {};
 
-    // Step 1: Ensure CLAUDE.md has @-references via CAAMP canonical API (T1919)
-    const instructionResult = await ensureProviderInstructionFile('claude-code', projectDir, {});
-    instructionFileUpdated = instructionResult.action !== 'intact';
-    if (instructionFileUpdated) {
-      details.instructionFile = instructionResult.filePath;
+    // Step 1: Ensure CLAUDE.md has @-references via CAAMP canonical API (T1919).
+    // Never the user-global ~/.claude/CLAUDE.md (T13227).
+    try {
+      assertProjectInstructionScope(projectDir);
+      const instructionResult = await ensureProviderInstructionFile('claude-code', projectDir, {});
+      instructionFileUpdated = instructionResult.action !== 'intact';
+      if (instructionFileUpdated) {
+        details.instructionFile = instructionResult.filePath;
+      }
+    } catch (err) {
+      if (!(err instanceof UserGlobalClaudeConfigError)) throw err;
+      details.instructionFile = 'skipped';
     }
 
-    // Step 2: Install adapter-provided commands to .claude/commands/
-    const commandsInstalled = this.installCommands(projectDir);
-    if (commandsInstalled.length > 0) {
-      details.commands = commandsInstalled;
+    // Step 2: Install adapter-provided commands to .claude/commands/ — never
+    // into the user-global Claude dir (T13227).
+    try {
+      const commandsInstalled = this.installCommands(projectDir);
+      if (commandsInstalled.length > 0) {
+        details.commands = commandsInstalled;
+      }
+    } catch (err) {
+      if (!(err instanceof UserGlobalClaudeConfigError)) throw err;
+      details.commands = 'skipped';
     }
 
     // T12385: settings.json writes are locked + atomic, and a malformed file
     // aborts the write and is reported here — it is never reset to `{}`.
     const settingsErrors: string[] = [];
 
-    // Step 3: Register plugin in ~/.claude/settings.json
+    // Step 3: Register plugin in the project's .claude/settings.local.json.
+    // A user-global target (T13227) is skipped, never written.
     try {
-      const pluginResult = await this.registerPlugin();
+      const pluginResult = await this.registerPlugin(projectDir);
       if (pluginResult) {
         details.plugin = pluginResult;
       }
     } catch (err) {
-      settingsErrors.push(err instanceof Error ? err.message : String(err));
+      if (err instanceof UserGlobalClaudeConfigError) details.plugin = 'skipped';
+      else settingsErrors.push(err instanceof Error ? err.message : String(err));
     }
 
-    // Step 4 (T1013): Install PreCompact hook templates + wire the handler
-    // command into ~/.claude/settings.json's `PreCompact` event.
+    // Step 4 (T1013): Install PreCompact hook templates into the project's
+    // .claude/hooks/ + wire the handler command into the project's
+    // .claude/settings.local.json `PreCompact` event (T13227).
     try {
-      const hookResult = await this.installHookTemplates();
+      const hookResult = await this.installHookTemplates(projectDir);
       if (hookResult) {
         details.hookTemplates = hookResult;
       }
     } catch (err) {
-      settingsErrors.push(err instanceof Error ? err.message : String(err));
+      if (err instanceof UserGlobalClaudeConfigError) details.hookTemplates = 'skipped';
+      else settingsErrors.push(err instanceof Error ? err.message : String(err));
     }
 
     // Step 5 (T12983): route heavy shell commands through `cleo run`.
@@ -155,17 +197,25 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
   /**
    * Check whether CLEO is installed in the current environment.
    *
-   * Checks for plugin enabled in ~/.claude/settings.json.
+   * Checks for the plugin enabled in the project's
+   * `.claude/settings.local.json` — the project of the last {@link install},
+   * else the working directory (T13227).
    */
   async isInstalled(): Promise<boolean> {
-    // Check ~/.claude/settings.json for plugin registration
-    const settingsPath = claudeSettingsPath();
+    let settingsPath: string;
+    try {
+      settingsPath = projectClaudeSettingsPath(this.projectDir ?? process.cwd());
+    } catch {
+      return false;
+    }
     if (existsSync(settingsPath)) {
       try {
-        const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
-        const plugins = settings.enabledPlugins as Record<string, boolean> | undefined;
-        if (plugins && plugins['cleo@cleocode'] === true) {
-          return true;
+        const settings: unknown = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+        if (isPlainObject(settings)) {
+          const plugins = settings.enabledPlugins;
+          if (isPlainObject(plugins) && plugins[CLEO_PLUGIN_KEY] === true) {
+            return true;
+          }
         }
       } catch {
         // Fall through
@@ -182,8 +232,11 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
    * and default references from the provider registry (T1919).
    *
    * @param projectDir - Project root directory
+   * @throws {@link UserGlobalClaudeConfigError} when the project root is inside
+   *   the user-global Claude config dir (T13227); nothing is written.
    */
   async ensureInstructionReferences(projectDir: string): Promise<void> {
+    assertProjectInstructionScope(projectDir);
     await ensureProviderInstructionFile('claude-code', projectDir, {});
   }
 
@@ -195,6 +248,7 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
    *
    * @param projectDir - Project root directory
    * @returns Array of installed command filenames
+   * @throws {@link UserGlobalClaudeConfigError} when the target is user-global
    */
   private installCommands(projectDir: string): string[] {
     const adapterCommandsDir = getAdapterCommandsDir();
@@ -202,7 +256,7 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
       return [];
     }
 
-    const targetDir = join(projectDir, '.claude', 'commands');
+    const targetDir = projectClaudeCommandsDir(projectDir);
     mkdirSync(targetDir, { recursive: true });
 
     const installed: string[] = [];
@@ -219,13 +273,17 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
   }
 
   /**
-   * Register the CLEO brain plugin in ~/.claude/settings.json.
+   * Register the CLEO brain plugin in the project's
+   * `.claude/settings.local.json` (T13227: never the user-global settings).
    *
+   * @param projectDir - Project root directory
    * @returns Description of what was registered, or null if no change needed
+   * @throws {@link UserGlobalClaudeConfigError} when the target is user-global
    */
-  private async registerPlugin(): Promise<string | null> {
-    const pluginKey = 'cleo@cleocode';
-    const wrote = await updateJsonConfigFile(claudeSettingsPath(), (settings) => {
+  private async registerPlugin(projectDir: string): Promise<string | null> {
+    const pluginKey = CLEO_PLUGIN_KEY;
+    const settingsPath = projectClaudeSettingsPath(projectDir);
+    const wrote = await updateJsonConfigFile(settingsPath, (settings) => {
       const enabledPlugins = settings.enabledPlugins ?? {};
       if (!isPlainObject(enabledPlugins)) {
         throw new Error('settings.json "enabledPlugins" is not an object; not modifying it');
@@ -244,35 +302,42 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
       return true;
     });
 
-    return wrote ? `Enabled ${pluginKey} in ~/.claude/settings.json` : null;
+    if (!wrote) return null;
+    excludeLocalSettingsFromGit(projectDir);
+    return `Enabled ${pluginKey} in ${settingsPath}`;
   }
 
   /**
    * Install the CLEO PreCompact hook templates for Claude Code (T1013).
    *
-   * Writes two files to `~/.claude/hooks/`:
+   * Writes two files to the project's `.claude/hooks/`:
    * 1. `cleo-precompact-core.sh` — universal CLEO safestop helper (shared
    *    across all providers; sourced by the provider-specific shim).
    * 2. `precompact-safestop.sh` — Claude-Code-flavoured wrapper that invokes
    *    `cleo memory precompact-flush` and `cleo safestop`.
    *
-   * Also registers a `PreCompact` entry in `~/.claude/settings.json` so Claude
-   * Code runs the hook when auto-compact fires (at 95% context).
+   * Also registers a `PreCompact` entry in the project's
+   * `.claude/settings.local.json` so Claude Code runs the hook when
+   * auto-compact fires (at 95% context). Files git does not ignore yet are
+   * kept out of it with a marked `info/exclude` block. Nothing is written to
+   * the user-global Claude config (T13227).
    *
    * Idempotent: subsequent installs skip unchanged files and do not duplicate
-   * the settings.json hook entry.
+   * the settings hook entry.
    *
+   * @param projectDir - Project root directory
    * @returns Install summary (paths written + config change description), or
    *   `null` when no change was required.
+   * @throws {@link UserGlobalClaudeConfigError} when the target is user-global
    *
-   * @task T1013
+   * @task T1013 @task T13227
    */
-  private async installHookTemplates(): Promise<{
+  private async installHookTemplates(projectDir: string): Promise<{
     templates: InstallHookTemplatesResult;
     settingsEntryAdded: boolean;
   } | null> {
-    const claudeDir = getClaudeConfigDir();
-    const hooksDir = join(claudeDir, 'hooks');
+    const hooksDir = projectClaudeHooksDir(projectDir);
+    const settingsPath = projectClaudeSettingsPath(projectDir);
 
     // 1. Copy the bash templates next to each other so `source $SCRIPT_DIR/...` works.
     //    Template copy is best-effort so missing/locked filesystems (CI sandboxes,
@@ -287,10 +352,14 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
       return null;
     }
 
-    // 2. Wire the PreCompact event in ~/.claude/settings.json.
+    for (const file of PROJECT_HOOK_FILES) excludeHookFileFromGit(projectDir, file);
+
+    // 2. Wire the PreCompact event in the project's settings.local.json.
     const settingsEntryAdded = await this.registerPreCompactHook(
+      settingsPath,
       join(hooksDir, 'precompact-safestop.sh'),
     );
+    if (settingsEntryAdded) excludeLocalSettingsFromGit(projectDir);
 
     if (templates.installedFiles.length === 0 && !settingsEntryAdded) {
       return null;
@@ -300,21 +369,23 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
   }
 
   /**
-   * Register the PreCompact hook command in `~/.claude/settings.json`.
+   * Register the PreCompact hook command in the project's
+   * `.claude/settings.local.json`.
    *
    * The Claude Code native event name for the canonical `PreCompact` event is
    * `PreCompact` (identity mapping — see `hook-mappings.json`). The entry is
    * tagged with `# cleo-hook` so the uninstall flow can identify and remove
    * our additions without touching user-authored hooks.
    *
+   * @param settingsPath - The project settings file (already scope-checked).
    * @param shimPath - Absolute path to the installed `precompact-safestop.sh`.
    * @returns `true` when a new hook entry was written, `false` when an
    *   equivalent entry was already present.
    *
    * @task T1013
    */
-  private async registerPreCompactHook(shimPath: string): Promise<boolean> {
-    return updateJsonConfigFile(claudeSettingsPath(), (settings) => {
+  private async registerPreCompactHook(settingsPath: string, shimPath: string): Promise<boolean> {
+    return updateJsonConfigFile(settingsPath, (settings) => {
       const hooks = hookMap(settings);
       if (hasCleoHook(hooks.PreCompact, 'precompact-safestop.sh')) {
         return false;

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

@@ -6,9 +6,11 @@
  * @task T5240
  */
 
+import { realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import type { AdapterPathProvider } from '@cleocode/contracts';
+import { CLAUDE_LOCAL_SETTINGS, isUserHomeDir } from '../shared/heavy-command-hook-install.js';
 
 /**
  * Path provider for Anthropic Claude Code CLI.
@@ -68,6 +70,162 @@ export function claudeSettingsPath(): string {
   );
 }
 
+/** Volumes on these platforms are case-insensitive by default (APFS, NTFS). */
+const CASE_INSENSITIVE_DEFAULT = process.platform === 'darwin' || process.platform === 'win32';
+
+/**
+ * `path` with every existing leading part resolved through symlinks, so two
+ * spellings of one location compare equal even before the leaf exists. Uses
+ * the native realpath, which returns the case stored on disk, so `~/.Claude`
+ * on a case-insensitive volume canonicalizes to `~/.claude` (T13227 review).
+ */
+function canonicalPath(path: string): string {
+  const abs = resolve(path);
+  try {
+    return realpathSync.native(abs);
+  } catch {
+    const parent = dirname(abs);
+    return parent === abs ? abs : join(canonicalPath(parent), basename(abs));
+  }
+}
+
+/**
+ * Fold case where volumes are case-insensitive by default, for the parts of
+ * a path that do not exist yet (the native realpath cannot fix their case).
+ * On a case-sensitive volume there this only refuses more, never less.
+ */
+function comparable(path: string): string {
+  return CASE_INSENSITIVE_DEFAULT ? path.toLowerCase() : path;
+}
+
+/** Whether `path` is `dir` or lies inside it (both canonical). */
+function isAtOrInside(path: string, dir: string): boolean {
+  const rel = relative(comparable(dir), comparable(path));
+  return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+
+/**
+ * The adapter was asked to write somewhere that is, or lies inside, the
+ * user-global Claude Code config (T13227). CLEO never writes there — adding
+ * and removing entries alike — so nothing is written and the caller reports
+ * the step as skipped.
+ */
+export class UserGlobalClaudeConfigError extends Error {
+  /** The path that was refused. */
+  readonly path: string;
+
+  /**
+   * @param path - the refused target.
+   * @param why - which user-global location it hits.
+   */
+  constructor(path: string, why: string) {
+    super(`refusing to write ${path}: ${why}; CLEO only writes project-level Claude Code config`);
+    this.name = 'UserGlobalClaudeConfigError';
+    this.path = path;
+  }
+}
+
+/**
+ * Refuse `target` when it is user-global Claude Code config: the settings
+ * file {@link claudeSettingsPath} resolves (`CLAUDE_SETTINGS`), anything in
+ * the Claude config dir (`CLAUDE_HOME`, else `~/.claude`), or anything when
+ * the project is the home directory (its `.claude/` IS the user-global dir,
+ * and its `CLAUDE.md` is loaded into every session under it).
+ *
+ * @param projectDir - the project root the write is for.
+ * @param target - the file or directory about to be written.
+ * @returns `target`, absolute, when it is project-level.
+ * @throws {@link UserGlobalClaudeConfigError} otherwise; nothing is written.
+ */
+function assertProjectScoped(projectDir: string, target: string): string {
+  const abs = resolve(target);
+  if (isUserHomeDir(projectDir)) {
+    throw new UserGlobalClaudeConfigError(abs, 'the project is the home directory');
+  }
+  const canonical = canonicalPath(abs);
+  if (comparable(canonical) === comparable(canonicalPath(claudeSettingsPath()))) {
+    throw new UserGlobalClaudeConfigError(abs, 'it is the user-global Claude settings file');
+  }
+  if (isAtOrInside(canonical, canonicalPath(new ClaudeCodePathProvider().getProviderDir()))) {
+    throw new UserGlobalClaudeConfigError(abs, 'it is inside the user-global Claude config dir');
+  }
+  return abs;
+}
+
+/**
+ * The project's per-machine Claude Code settings file,
+ * `<project>/.claude/settings.local.json` — the only settings file the
+ * adapter's hook and plugin writers touch (T13227, the T12983/T13124 rule:
+ * project-level only, never the user-global `~/.claude/settings.json`).
+ *
+ * @param projectDir - the project root.
+ * @returns the absolute settings path.
+ * @throws {@link UserGlobalClaudeConfigError} when it would be user-global.
+ *
+ * @example
+ * ```typescript
+ * const target = projectClaudeSettingsPath('/repo'); // /repo/.claude/settings.local.json
+ * ```
+ */
+export function projectClaudeSettingsPath(projectDir: string): string {
+  return assertProjectScoped(projectDir, join(projectDir, CLAUDE_LOCAL_SETTINGS));
+}
+
+/**
+ * The project's Claude Code hook-script dir, `<project>/.claude/hooks`, where
+ * the PreCompact templates are copied (T13227).
+ *
+ * @param projectDir - the project root.
+ * @returns the absolute hooks dir.
+ * @throws {@link UserGlobalClaudeConfigError} when it would be user-global.
+ *
+ * @example
+ * ```typescript
+ * const dir = projectClaudeHooksDir('/repo'); // /repo/.claude/hooks
+ * ```
+ */
+export function projectClaudeHooksDir(projectDir: string): string {
+  return assertProjectScoped(projectDir, join(projectDir, '.claude', 'hooks'));
+}
+
+/**
+ * Refuse a project whose `CLAUDE.md` would be user-global in effect (T13227
+ * review): a root inside the user-global Claude config dir (in any spelling),
+ * where it is Claude Code's user-global memory file `~/.claude/CLAUDE.md`, or
+ * the home directory itself — Claude Code loads `CLAUDE.md` from the working
+ * directory up through every ancestor, so `~/CLAUDE.md` reaches every session
+ * under `$HOME`.
+ *
+ * @param projectDir - the project root.
+ * @throws {@link UserGlobalClaudeConfigError} when the project root is the
+ *   home directory or inside the user-global Claude config dir.
+ *
+ * @example
+ * ```typescript
+ * assertProjectInstructionScope('/repo'); // ok
+ * ```
+ */
+export function assertProjectInstructionScope(projectDir: string): void {
+  assertProjectScoped(projectDir, join(projectDir, 'CLAUDE.md'));
+}
+
+/**
+ * The project's Claude Code commands dir, `<project>/.claude/commands`, where
+ * the adapter's slash commands are copied (T13227).
+ *
+ * @param projectDir - the project root.
+ * @returns the absolute commands dir.
+ * @throws {@link UserGlobalClaudeConfigError} when it would be user-global.
+ *
+ * @example
+ * ```typescript
+ * const dir = projectClaudeCommandsDir('/repo'); // /repo/.claude/commands
+ * ```
+ */
+export function projectClaudeCommandsDir(projectDir: string): string {
+  return assertProjectScoped(projectDir, join(projectDir, '.claude', 'commands'));
+}
+
 export {
   appendHookEntry,
   CLEO_HOOK_MARKER,

package/src/providers/codex/install.ts

@@ -17,6 +17,7 @@ import { ensureProviderInstructionFile } from '@cleocode/caamp';
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
 import { isUserHomeDir, syncCodexHeavyCommandHook } from '../shared/heavy-command-hook-install.js';
 import { getCleoTemplatesTildePath } from '../shared/paths.js';
+import { ensureProjectInstructionFile } from '../shared/project-instruction-file.js';
 
 /**
  * Install provider for Codex CLI.
@@ -50,15 +51,16 @@ export class CodexInstallProvider implements AdapterInstallProvider {
     const details: Record<string, unknown> = {};
 
     // Ensure AGENTS.md has CLEO @-references via CAAMP canonical API.
-    const result = await ensureProviderInstructionFile('codex', projectDir, {
+    const result = await ensureProjectInstructionFile('codex', projectDir, {
       scope: 'project',
       references: [`@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`, '@.cleo/memory-bridge.md'],
     });
 
-    const instructionFileUpdated = result.action !== 'intact';
+    const instructionFileUpdated = result !== null && result.action !== 'intact';
     if (instructionFileUpdated) {
       details.instructionFile = join(projectDir, result.instructFile);
     }
+    if (result === null) details.instructionFile = 'skipped'; // T13227: $HOME project
 
     // T12983: route heavy shell commands through `cleo run`.
     let success = true;

package/src/providers/cursor/install.ts

@@ -25,11 +25,13 @@ import {
   updateJsonConfigFile,
 } from '@cleocode/caamp';
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
+import { isUserHomeDir } from '../shared/heavy-command-hook-install.js';
 import {
   type InstallHookTemplatesResult,
   installProviderHookTemplates,
 } from '../shared/hook-template-installer.js';
 import { getCleoTemplatesTildePath } from '../shared/paths.js';
+import { ensureProjectInstructionFile } from '../shared/project-instruction-file.js';
 
 /** MDC frontmatter for the CLEO-owned `.cursor/rules/cleo.mdc` rule file. */
 const CLEO_MDC_FRONTMATTER = [
@@ -76,11 +78,17 @@ export class CursorInstallProvider implements AdapterInstallProvider {
     // Step 1: Ensure instruction files have @-references via CAAMP canonical API (T1919).
     // ensureProviderInstructionFile handles the primary AGENTS.md (registry instructFile);
     // updateInstructionFiles also manages cursor-specific MDC + legacy .cursorrules formats.
-    const instructionResult = await ensureProviderInstructionFile('cursor', projectDir, {});
-    const cursorFilesUpdated = await this.updateInstructionFiles(projectDir);
-    instructionFileUpdated = instructionResult.action !== 'intact' || cursorFilesUpdated;
-    if (instructionFileUpdated) {
-      details.instructionFiles = this.getUpdatedFileList(projectDir);
+    const instructionResult = await ensureProjectInstructionFile('cursor', projectDir, {});
+    if (instructionResult === null) {
+      // T13227: a $HOME project gets no instruction files (loaded by every
+      // session under it); the Cursor rule files are skipped with it.
+      details.instructionFiles = 'skipped';
+    } else {
+      const cursorFilesUpdated = await this.updateInstructionFiles(projectDir);
+      instructionFileUpdated = instructionResult.action !== 'intact' || cursorFilesUpdated;
+      if (instructionFileUpdated) {
+        details.instructionFiles = this.getUpdatedFileList(projectDir);
+      }
     }
 
     // Step 2 (T1013): Install PreCompact hook templates + wire the handler
@@ -88,14 +96,20 @@ export class CursorInstallProvider implements AdapterInstallProvider {
     // T12385: a malformed hooks.json aborts the write and is reported; it is
     // never reset to `{}`.
     let hooksError: string | null = null;
-    try {
-      const hookResult = await this.installHookTemplates(projectDir);
-      if (hookResult) {
-        details.hookTemplates = hookResult;
+    if (isUserHomeDir(projectDir)) {
+      // T13257: at $HOME, .cursor/hooks.json and .cursor/hooks/ ARE Cursor's
+      // user-global hooks; CLEO installs them per project only.
+      details.hookTemplates = 'skipped';
+    } else {
+      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;
       }
-    } catch (err) {
-      hooksError = err instanceof Error ? err.message : String(err);
-      details.hooksError = hooksError;
     }
 
     return {

package/src/providers/gemini-cli/install.ts

@@ -14,6 +14,7 @@ import { join } from 'node:path';
 import { ensureProviderInstructionFile } from '@cleocode/caamp';
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
 import { getCleoTemplatesTildePath } from '../shared/paths.js';
+import { ensureProjectInstructionFile } from '../shared/project-instruction-file.js';
 
 /**
  * Install provider for Gemini CLI.
@@ -43,15 +44,16 @@ export class GeminiCliInstallProvider implements AdapterInstallProvider {
     const installedAt = new Date().toISOString();
     const details: Record<string, unknown> = {};
 
-    const result = await ensureProviderInstructionFile('gemini-cli', projectDir, {
+    const result = await ensureProjectInstructionFile('gemini-cli', projectDir, {
       references: [`@${getCleoTemplatesTildePath()}/CLEO-INJECTION.md`, '@.cleo/memory-bridge.md'],
       scope: 'project',
     });
 
-    const instructionFileUpdated = result.action !== 'intact';
+    const instructionFileUpdated = result !== null && result.action !== 'intact';
     if (instructionFileUpdated) {
       details.instructionFile = result.filePath;
     }
+    if (result === null) details.instructionFile = 'skipped'; // T13227: $HOME project
 
     return {
       success: true,