@cleocode/adapters 2026.4.101 → 2026.4.103

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

@@ -22,6 +22,10 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
+import {
+  type InstallHookTemplatesResult,
+  installProviderHookTemplates,
+} from '../shared/hook-template-installer.js';
 import { getCleoTemplatesTildePath } from '../shared/paths.js';
 
 /**
@@ -86,6 +90,13 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
       details.plugin = pluginResult;
     }
 
+    // Step 4 (T1013): Install PreCompact hook templates + wire the handler
+    // command into ~/.claude/settings.json's `PreCompact` event.
+    const hookResult = this.installHookTemplates();
+    if (hookResult) {
+      details.hookTemplates = hookResult;
+    }
+
     return {
       success: true,
       installedAt,
@@ -240,4 +251,122 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
 
     return `Enabled ${pluginKey} in ~/.claude/settings.json`;
   }
+
+  /**
+   * Install the CLEO PreCompact hook templates for Claude Code (T1013).
+   *
+   * Writes two files to `~/.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).
+   *
+   * Idempotent: subsequent installs skip unchanged files and do not duplicate
+   * the settings.json hook entry.
+   *
+   * @returns Install summary (paths written + config change description), or
+   *   `null` when no change was required.
+   *
+   * @task T1013
+   */
+  private installHookTemplates(): {
+    templates: InstallHookTemplatesResult;
+    settingsEntryAdded: boolean;
+  } | null {
+    const home = homedir();
+    const hooksDir = join(home, '.claude', 'hooks');
+
+    // 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,
+    //    mocked `node:fs` in unit tests) don't fail the whole install.
+    let templates: InstallHookTemplatesResult;
+    try {
+      templates = installProviderHookTemplates({
+        provider: 'claude-code',
+        targetDir: hooksDir,
+      });
+    } catch {
+      return null;
+    }
+
+    // 2. Wire the PreCompact event in ~/.claude/settings.json.
+    const settingsEntryAdded = this.registerPreCompactHook(
+      join(hooksDir, 'precompact-safestop.sh'),
+    );
+
+    if (templates.installedFiles.length === 0 && !settingsEntryAdded) {
+      return null;
+    }
+
+    return { templates, settingsEntryAdded };
+  }
+
+  /**
+   * Register the PreCompact hook command in `~/.claude/settings.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 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 registerPreCompactHook(shimPath: string): boolean {
+    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 on corrupt settings — safer than aborting install.
+      }
+    }
+
+    const hooks = (settings.hooks as Record<string, unknown[]> | undefined) ?? {};
+    const preCompactEntries = (hooks.PreCompact as unknown[] | undefined) ?? [];
+
+    const alreadyWired = preCompactEntries.some(
+      (entry) =>
+        typeof entry === 'object' &&
+        entry !== null &&
+        Array.isArray((entry as Record<string, unknown>).hooks) &&
+        ((entry as Record<string, unknown>).hooks as Array<Record<string, unknown>>).some(
+          (h) =>
+            typeof h.command === 'string' &&
+            (h.command as string).includes('# cleo-hook') &&
+            (h.command as string).includes('precompact-safestop.sh'),
+        ),
+    );
+
+    if (alreadyWired) {
+      return false;
+    }
+
+    preCompactEntries.push({
+      matcher: '',
+      hooks: [
+        {
+          type: 'command',
+          command: `"${shimPath}" # cleo-hook`,
+          timeout: 30,
+        },
+      ],
+    });
+
+    hooks.PreCompact = preCompactEntries;
+    settings.hooks = hooks;
+
+    mkdirSync(join(home, '.claude'), { recursive: true });
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+    return true;
+  }
 }

package/src/providers/claude-code/templates/hooks/precompact-safestop.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# CLEO PreCompact Hook — Claude Code emergency safestop shim
+#
+# Triggers when Claude Code's auto-compact fires (at 95% context usage).
+# Claude Code is a config-based hook provider (~/.claude/settings.json)
+# whose canonical event `PreCompact` maps to the native event `PreCompact`.
+#
+# INSTALLATION (Claude Code):
+#   Copy to ~/.claude/hooks/ (alongside cleo-precompact-core.sh) or
+#   configure the installer to write this block to ~/.claude/settings.json:
+#
+#   {
+#     "hooks": {
+#       "PreCompact": [{
+#         "type": "command",
+#         "command": "~/.claude/hooks/precompact-safestop.sh",
+#         "timeout": 30
+#       }]
+#     }
+#   }
+#
+# This shim is the Claude-Code-specific banner wrapper around the universal
+# CLEO safestop sequence. The actual flush + safestop logic lives in the
+# shared helper at cleo-precompact-core.sh (provider-neutral).
+#
+# Provides emergency fallback when an agent does not self-stop at the
+# critical (90%) threshold. At 95% Claude Code triggers `PreCompact`, and
+# this hook ensures CLEO session state is properly captured.
+#
+# @task T1013
+# @provider claude-code
+
+set -euo pipefail
+
+# Source the shared CLEO core helper. Installed alongside this shim.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../../../shared/templates/hooks/cleo-precompact-core.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/cleo-precompact-core.sh"
+
+# Run the universal flush + safestop sequence.
+cleo_core_run_precompact "precompact-emergency"
+
+# Claude-Code-specific status banner (only when a session was actually saved).
+if [[ -n "${CLEO_PRECOMPACT_HANDOFF:-}" ]]; then
+    echo ""
+    echo "[CLEO] Emergency Safestop executed at PreCompact (Claude Code 95% context)."
+    echo "       Session ended. Handoff saved to: ${CLEO_PRECOMPACT_HANDOFF}"
+    if [[ -n "${CLEO_PRECOMPACT_SESSION_ID:-}" ]]; then
+        echo "       Resume with: cleo session resume ${CLEO_PRECOMPACT_SESSION_ID}"
+    fi
+fi

package/src/providers/cursor/__tests__/hooks-install.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Tests for the Cursor PreCompact hook-template installer (T1013).
+ *
+ * Validates that:
+ * - The Cursor adapter copies the shared helper + provider shim into
+ *   `<projectDir>/.cursor/hooks/`.
+ * - `<projectDir>/.cursor/hooks.json` gains a `preCompact` entry (CAAMP's
+ *   native event name for Cursor) tagged with the `# cleo-hook` sentinel.
+ * - Repeat invocations are idempotent.
+ *
+ * The test writes to a scoped tmp project directory so no user config is
+ * touched.
+ *
+ * @task T1013
+ * @epic T1000
+ */
+
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { CursorInstallProvider } from '../install.js';
+
+describe('CursorInstallProvider — PreCompact hook templates', () => {
+  let projectDir: string;
+
+  beforeEach(() => {
+    projectDir = mkdtempSync(join(tmpdir(), 'cleo-cursor-install-'));
+  });
+
+  afterEach(() => {
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it('installs both bash templates into <projectDir>/.cursor/hooks/', async () => {
+    const provider = new CursorInstallProvider();
+
+    const result = await provider.install({ projectDir });
+    expect(result.success).toBe(true);
+
+    const hookTemplates = (result.details?.hookTemplates ?? null) as {
+      templates: { installedFiles: string[]; targetDir: string };
+      hooksJsonEntryAdded: boolean;
+    } | null;
+
+    expect(hookTemplates).not.toBeNull();
+    expect(hookTemplates?.templates.targetDir).toBe(join(projectDir, '.cursor', 'hooks'));
+    const installed = hookTemplates?.templates.installedFiles ?? [];
+    expect(installed.some((p) => p.endsWith('cleo-precompact-core.sh'))).toBe(true);
+    expect(installed.some((p) => p.endsWith('precompact.sh'))).toBe(true);
+
+    // Provider shim sources the shared helper so the DRY contract holds.
+    const shim = readFileSync(join(projectDir, '.cursor', 'hooks', 'precompact.sh'), 'utf-8');
+    expect(shim).toContain('cleo-precompact-core.sh');
+    // Cursor's banner references its native event name for the canonical PreCompact.
+    expect(shim).toContain('preCompact');
+  });
+
+  it('writes a preCompact entry into <projectDir>/.cursor/hooks.json tagged # cleo-hook', async () => {
+    const provider = new CursorInstallProvider();
+    await provider.install({ projectDir });
+
+    const hooksJsonPath = join(projectDir, '.cursor', 'hooks.json');
+    const config = JSON.parse(readFileSync(hooksJsonPath, 'utf-8')) as {
+      hooks?: Record<string, Array<{ command?: string; type?: string }>>;
+    };
+
+    const entries = config.hooks?.preCompact ?? [];
+    expect(entries.length).toBeGreaterThan(0);
+    const entry = entries[0];
+    expect(entry).toBeDefined();
+    expect(entry?.type).toBe('command');
+    expect(entry?.command).toContain('precompact.sh');
+    expect(entry?.command).toContain('# cleo-hook');
+  });
+
+  it('is idempotent — re-running install does not duplicate the preCompact entry', async () => {
+    const provider = new CursorInstallProvider();
+    await provider.install({ projectDir });
+    await provider.install({ projectDir });
+
+    const hooksJsonPath = join(projectDir, '.cursor', 'hooks.json');
+    const config = JSON.parse(readFileSync(hooksJsonPath, 'utf-8')) as {
+      hooks?: { preCompact?: unknown[] };
+    };
+    expect((config.hooks?.preCompact ?? []).length).toBe(1);
+  });
+});

package/src/providers/cursor/install.ts

@@ -4,6 +4,7 @@
  * Handles CLEO installation into Cursor environments:
  * - Ensures .cursorrules has CLEO @-references (legacy format)
  * - Creates .cursor/rules/cleo.mdc with CLEO references (modern format)
+ * - Installs PreCompact hook shell shims + wires them into .cursor/hooks.json (T1013)
  *
  * Cursor supports two instruction file formats:
  * 1. Legacy: .cursorrules (flat file, project root)
@@ -12,11 +13,16 @@
  * This provider writes to both for maximum compatibility.
  *
  * @task T5240
+ * @task T1013
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
+import {
+  type InstallHookTemplatesResult,
+  installProviderHookTemplates,
+} from '../shared/hook-template-installer.js';
 import { getCleoTemplatesTildePath } from '../shared/paths.js';
 
 /**
@@ -35,6 +41,7 @@ const INSTRUCTION_REFERENCES = [
  * Manages CLEO's integration with Cursor by:
  * 1. Creating/updating .cursorrules with @-references (legacy)
  * 2. Creating .cursor/rules/cleo.mdc with @-references (modern)
+ * 3. Installing the PreCompact hook shim + registering it in .cursor/hooks.json (T1013)
  *
  * @remarks
  * Installation is idempotent and writes to both instruction file formats
@@ -61,6 +68,13 @@ export class CursorInstallProvider implements AdapterInstallProvider {
       details.instructionFiles = this.getUpdatedFileList(projectDir);
     }
 
+    // Step 2 (T1013): Install PreCompact hook templates + wire the handler
+    // command into .cursor/hooks.json's `preCompact` event.
+    const hookResult = this.installHookTemplates(projectDir);
+    if (hookResult) {
+      details.hookTemplates = hookResult;
+    }
+
     return {
       success: true,
       installedAt,
@@ -207,4 +221,107 @@ export class CursorInstallProvider implements AdapterInstallProvider {
     files.push(join(projectDir, '.cursor', 'rules', 'cleo.mdc'));
     return files;
   }
+
+  /**
+   * Install the CLEO PreCompact hook templates for Cursor (T1013).
+   *
+   * Writes two files to `<projectDir>/.cursor/hooks/`:
+   * 1. `cleo-precompact-core.sh` — universal CLEO safestop helper.
+   * 2. `precompact.sh` — Cursor-flavoured wrapper.
+   *
+   * Also registers a `preCompact` entry in `.cursor/hooks.json`. The native
+   * event name `preCompact` comes from CAAMP's `hook-mappings.json` SSoT.
+   *
+   * Idempotent: re-running install skips unchanged files and avoids
+   * duplicating the hooks.json entry.
+   *
+   * @param projectDir - Project root directory.
+   * @returns Install summary, or `null` when no change was required.
+   *
+   * @task T1013
+   */
+  private installHookTemplates(projectDir: string): {
+    templates: InstallHookTemplatesResult;
+    hooksJsonEntryAdded: boolean;
+  } | null {
+    const hooksDir = join(projectDir, '.cursor', 'hooks');
+
+    // Template copy is best-effort so missing/locked filesystems (CI sandboxes,
+    // mocked `node:fs` in unit tests) don't fail the whole install.
+    let templates: InstallHookTemplatesResult;
+    try {
+      templates = installProviderHookTemplates({
+        provider: 'cursor',
+        targetDir: hooksDir,
+      });
+    } catch {
+      return null;
+    }
+
+    const hooksJsonEntryAdded = this.registerPreCompactHook(
+      projectDir,
+      join(hooksDir, 'precompact.sh'),
+    );
+
+    if (templates.installedFiles.length === 0 && !hooksJsonEntryAdded) {
+      return null;
+    }
+
+    return { templates, hooksJsonEntryAdded };
+  }
+
+  /**
+   * Register the PreCompact hook command in `.cursor/hooks.json`.
+   *
+   * Cursor's native event name for the canonical `PreCompact` is `preCompact`
+   * (camelCase — see CAAMP `hook-mappings.json`). Entries are tagged with a
+   * `# cleo-hook` comment so they can be cleanly removed on uninstall.
+   *
+   * @param projectDir - Project root directory.
+   * @param shimPath - Absolute path to the installed `precompact.sh`.
+   * @returns `true` when a new entry was written, `false` when already wired.
+   *
+   * @task T1013
+   */
+  private registerPreCompactHook(projectDir: string, shimPath: string): boolean {
+    const hooksJsonPath = join(projectDir, '.cursor', 'hooks.json');
+
+    let config: Record<string, unknown> = {};
+    if (existsSync(hooksJsonPath)) {
+      try {
+        config = JSON.parse(readFileSync(hooksJsonPath, 'utf-8'));
+      } catch {
+        // Start fresh on corrupt config.
+      }
+    }
+
+    const hooks = (config.hooks as Record<string, unknown[]> | undefined) ?? {};
+    const entries = (hooks.preCompact as unknown[] | undefined) ?? [];
+
+    const alreadyWired = entries.some(
+      (entry) =>
+        typeof entry === 'object' &&
+        entry !== null &&
+        typeof (entry as Record<string, unknown>).command === 'string' &&
+        ((entry as Record<string, unknown>).command as string).includes('# cleo-hook') &&
+        ((entry as Record<string, unknown>).command as string).includes('precompact.sh'),
+    );
+
+    if (alreadyWired) {
+      return false;
+    }
+
+    entries.push({
+      type: 'command',
+      command: `"${shimPath}" # cleo-hook`,
+      timeout: 30,
+    });
+
+    hooks.preCompact = entries;
+    config.hooks = hooks;
+
+    mkdirSync(join(projectDir, '.cursor'), { recursive: true });
+    writeFileSync(hooksJsonPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    return true;
+  }
 }

package/src/providers/cursor/templates/hooks/precompact.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# CLEO PreCompact Hook — Cursor emergency safestop shim
+#
+# Cursor is a config-based hook provider (.cursor/hooks.json) whose canonical
+# event `PreCompact` maps to the native event `preCompact`. Handler types
+# supported: `command`, `prompt`. This file targets `command` handlers.
+#
+# INSTALLATION (Cursor):
+#   Copy to .cursor/hooks/precompact.sh (alongside cleo-precompact-core.sh)
+#   and add the following to .cursor/hooks.json:
+#
+#   {
+#     "hooks": {
+#       "preCompact": [{
+#         "type": "command",
+#         "command": "./.cursor/hooks/precompact.sh",
+#         "timeout": 30
+#       }]
+#     }
+#   }
+#
+# The universal flush + safestop sequence is implemented in the shared helper
+# cleo-precompact-core.sh. This shim only adds a Cursor-flavoured banner.
+#
+# @task T1013
+# @provider cursor
+
+set -euo pipefail
+
+# Source the shared CLEO core helper. Installed alongside this shim.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../../../shared/templates/hooks/cleo-precompact-core.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/cleo-precompact-core.sh"
+
+# Run the universal flush + safestop sequence.
+cleo_core_run_precompact "precompact-emergency"
+
+# Cursor-specific status banner (only when a session was actually saved).
+if [[ -n "${CLEO_PRECOMPACT_HANDOFF:-}" ]]; then
+    echo ""
+    echo "[CLEO] Emergency Safestop executed at Cursor preCompact event."
+    echo "       Session ended. Handoff saved to: ${CLEO_PRECOMPACT_HANDOFF}"
+    if [[ -n "${CLEO_PRECOMPACT_SESSION_ID:-}" ]]; then
+        echo "       Resume with: cleo session resume ${CLEO_PRECOMPACT_SESSION_ID}"
+    fi
+fi

package/src/providers/gemini-cli/templates/hooks/precompact.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# CLEO PreCompact Hook — Gemini CLI emergency safestop shim
+#
+# Gemini CLI is a config-based hook provider (~/.gemini/settings.json) whose
+# canonical event `PreCompact` maps to the native event `PreCompress`.
+# Handler type supported: `command`.
+#
+# INSTALLATION (Gemini CLI):
+#   Copy to ~/.gemini/hooks/precompact.sh (alongside cleo-precompact-core.sh)
+#   and add the following to ~/.gemini/settings.json:
+#
+#   {
+#     "hooks": {
+#       "PreCompress": [{
+#         "type": "command",
+#         "command": "~/.gemini/hooks/precompact.sh",
+#         "timeout": 30
+#       }]
+#     }
+#   }
+#
+# The universal flush + safestop sequence lives in cleo-precompact-core.sh.
+# This shim only adds a Gemini-flavoured banner.
+#
+# @task T1013
+# @provider gemini-cli
+
+set -euo pipefail
+
+# Source the shared CLEO core helper. Installed alongside this shim.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../../../shared/templates/hooks/cleo-precompact-core.sh
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/cleo-precompact-core.sh"
+
+# Run the universal flush + safestop sequence.
+cleo_core_run_precompact "precompact-emergency"
+
+# Gemini-CLI-specific status banner (only when a session was actually saved).
+if [[ -n "${CLEO_PRECOMPACT_HANDOFF:-}" ]]; then
+    echo ""
+    echo "[CLEO] Emergency Safestop executed at Gemini CLI PreCompress event."
+    echo "       Session ended. Handoff saved to: ${CLEO_PRECOMPACT_HANDOFF}"
+    if [[ -n "${CLEO_PRECOMPACT_SESSION_ID:-}" ]]; then
+        echo "       Resume with: cleo session resume ${CLEO_PRECOMPACT_SESSION_ID}"
+    fi
+fi

package/src/providers/opencode/__tests__/hooks-install.test.ts

@@ -0,0 +1,87 @@
+/**
+ * Tests for the OpenCode PreCompact hook-template installer (T1013).
+ *
+ * OpenCode does not have config-based hooks — it uses a JavaScript plugin
+ * system. The installer therefore produces:
+ *
+ * 1. `<projectDir>/.opencode/plugins/hooks/cleo-precompact-core.sh` (shared helper)
+ * 2. `<projectDir>/.opencode/plugins/hooks/precompact.sh` (OpenCode shim)
+ * 3. `<projectDir>/.opencode/plugins/cleo-precompact.js` (JS plugin that
+ *    spawns the shim on `experimental.session.compacting`).
+ *
+ * @task T1013
+ * @epic T1000
+ */
+
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { OpenCodeInstallProvider } from '../install.js';
+
+describe('OpenCodeInstallProvider — PreCompact hook templates', () => {
+  let projectDir: string;
+
+  beforeEach(() => {
+    projectDir = mkdtempSync(join(tmpdir(), 'cleo-opencode-install-'));
+  });
+
+  afterEach(() => {
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it('installs bash templates under <projectDir>/.opencode/plugins/hooks/', async () => {
+    const provider = new OpenCodeInstallProvider();
+    const result = await provider.install({ projectDir });
+    expect(result.success).toBe(true);
+
+    const hookTemplates = (result.details?.hookTemplates ?? null) as {
+      templates: { installedFiles: string[]; targetDir: string };
+      pluginWritten: boolean;
+    } | null;
+
+    expect(hookTemplates).not.toBeNull();
+    expect(hookTemplates?.templates.targetDir).toBe(
+      join(projectDir, '.opencode', 'plugins', 'hooks'),
+    );
+    const installed = hookTemplates?.templates.installedFiles ?? [];
+    expect(installed.some((p) => p.endsWith('cleo-precompact-core.sh'))).toBe(true);
+    expect(installed.some((p) => p.endsWith('precompact.sh'))).toBe(true);
+  });
+
+  it('generates a JS plugin wrapping the experimental.session.compacting event', async () => {
+    const provider = new OpenCodeInstallProvider();
+    await provider.install({ projectDir });
+
+    const pluginPath = join(projectDir, '.opencode', 'plugins', 'cleo-precompact.js');
+    const plugin = readFileSync(pluginPath, 'utf-8');
+
+    // Plugin subscribes to OpenCode's native PreCompact event
+    expect(plugin).toContain('experimental.session.compacting');
+    // Plugin spawns the bash shim (not core internals) — universal CLI surface.
+    expect(plugin).toContain('spawn');
+    expect(plugin).toContain('precompact.sh');
+  });
+
+  it('is idempotent — re-running install does not rewrite unchanged plugin files', async () => {
+    const provider = new OpenCodeInstallProvider();
+    const first = await provider.install({ projectDir });
+    const second = await provider.install({ projectDir });
+
+    const firstResult = (first.details?.hookTemplates ?? null) as {
+      pluginWritten: boolean;
+    } | null;
+    // The first install writes both the bash templates and the plugin.
+    expect(firstResult?.pluginWritten).toBe(true);
+
+    // On the second pass the generated plugin file matches the source exactly
+    // and both bash templates are byte-identical, so the install helper
+    // returns `null` (no change required).
+    expect(second.details?.hookTemplates ?? null).toBeNull();
+
+    // And the plugin file contents have not been clobbered between the two runs.
+    const pluginPath = join(projectDir, '.opencode', 'plugins', 'cleo-precompact.js');
+    const plugin = readFileSync(pluginPath, 'utf-8');
+    expect(plugin).toContain('experimental.session.compacting');
+  });
+});