@cleocode/adapters 2026.10.1 → 2026.10.3

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

@@ -68,134 +68,12 @@ export function claudeSettingsPath(): string {
   );
 }
 
-/** Marker CLEO puts in every hook command it owns. */
-const CLEO_HOOK_MARKER = '# cleo-hook';
-
-/**
- * Whether a parsed settings value is a plain JSON object.
- *
- * @param value - Any parsed JSON value
- * @returns `true` for a non-null, non-array object
- *
- * @example
- * ```typescript
- * isPlainObject(settings.enabledPlugins);
- * ```
- */
-export function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-/**
- * Whether a settings.json hook entry carries a CLEO-owned command.
- *
- * @param entry - One element of a `hooks.<Event>` array
- * @param commandIncludes - Extra substring the CLEO command must contain
- * @returns `true` when one of the entry's commands has the `# cleo-hook` marker
- *
- * @example
- * ```typescript
- * isCleoHookEntry({ hooks: [{ type: "command", command: "x # cleo-hook" }] }); // true
- * ```
- */
-export function isCleoHookEntry(entry: unknown, commandIncludes?: string): boolean {
-  if (!isPlainObject(entry) || !Array.isArray(entry.hooks)) return false;
-  return entry.hooks.some(
-    (hook) =>
-      isPlainObject(hook) &&
-      typeof hook.command === 'string' &&
-      hook.command.includes(CLEO_HOOK_MARKER) &&
-      (commandIncludes === undefined || hook.command.includes(commandIncludes)),
-  );
-}
-
-/**
- * Whether a `hooks.<Event>` value holds a CLEO-owned entry.
- *
- * @param entries - The event's value (non-arrays hold none)
- * @param commandIncludes - Extra substring the CLEO command must contain
- * @returns `true` when a CLEO entry is present
- *
- * @example
- * ```typescript
- * hasCleoHook(hookMap(settings).Stop);
- * ```
- */
-export function hasCleoHook(entries: unknown, commandIncludes?: string): boolean {
-  return Array.isArray(entries) && entries.some((e) => isCleoHookEntry(e, commandIncludes));
-}
-
-/**
- * Return the settings object's `hooks` map, creating an empty one if absent.
- *
- * @param settings - Parsed settings.json
- * @returns The live `hooks` object (mutations apply to `settings`)
- * @throws Error when `hooks` exists but is not an object — the caller's write
- *   is aborted and the file left untouched
- *
- * @example
- * ```typescript
- * const hooks = hookMap(settings);
- * ```
- */
-export function hookMap(settings: Record<string, unknown>): Record<string, unknown> {
-  const existing = settings.hooks;
-  if (existing === undefined) {
-    const created: Record<string, unknown> = {};
-    settings.hooks = created;
-    return created;
-  }
-  if (!isPlainObject(existing)) {
-    throw new Error('settings.json "hooks" is not an object; not modifying it');
-  }
-  return existing;
-}
-
-/**
- * Append a hook entry to `hooks[event]`, preserving existing entries.
- *
- * @param hooks - The settings `hooks` map
- * @param event - Native event name (e.g. `Stop`, `PreCompact`)
- * @param entry - Entry to append
- * @throws Error when `hooks[event]` exists but is not an array
- *
- * @example
- * ```typescript
- * appendHookEntry(hookMap(settings), "Stop", { matcher: "", hooks: [] });
- * ```
- */
-export function appendHookEntry(
-  hooks: Record<string, unknown>,
-  event: string,
-  entry: Record<string, unknown>,
-): void {
-  const existing = hooks[event];
-  if (existing !== undefined && !Array.isArray(existing)) {
-    throw new Error(`settings.json "hooks.${event}" is not an array; not modifying it`);
-  }
-  hooks[event] = [...(existing ?? []), entry];
-}
-
-/**
- * Remove every CLEO-owned entry from every event array in `hooks`.
- *
- * @param hooks - The settings `hooks` map
- * @returns Whether anything was removed
- *
- * @example
- * ```typescript
- * const changed = removeCleoHookEntries(hookMap(settings));
- * ```
- */
-export function removeCleoHookEntries(hooks: Record<string, unknown>): boolean {
-  let changed = false;
-  for (const [event, entries] of Object.entries(hooks)) {
-    if (!Array.isArray(entries)) continue;
-    const kept = entries.filter((e) => !isCleoHookEntry(e));
-    if (kept.length !== entries.length) {
-      hooks[event] = kept;
-      changed = true;
-    }
-  }
-  return changed;
-}
+export {
+  appendHookEntry,
+  CLEO_HOOK_MARKER,
+  hasCleoHook,
+  hookMap,
+  isCleoHookEntry,
+  isPlainObject,
+  removeCleoHookEntries,
+} from '../shared/hook-config.js';

package/src/providers/codex/install.ts

@@ -3,15 +3,19 @@
  *
  * Handles CLEO installation into Codex CLI environments:
  * - Ensures AGENTS.md has CLEO @-references via CAAMP
+ * - Installs the heavy-command `PreToolUse` hook in the project's
+ *   `.codex/hooks.json` (T12983)
  *
  * @task T162
  * @task T9019
+ * @task T12983
  * @epic T134
  */
 
 import { join } from 'node:path';
 import { ensureProviderInstructionFile } from '@cleocode/caamp';
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
+import { isUserHomeDir, syncJsonHeavyCommandHook } from '../shared/heavy-command-hook-install.js';
 import { getCleoTemplatesTildePath } from '../shared/paths.js';
 
 /**
@@ -20,11 +24,14 @@ import { getCleoTemplatesTildePath } from '../shared/paths.js';
  * Manages CLEO's integration with Codex CLI by:
  * 1. Ensuring AGENTS.md contains @-references to CLEO instruction files
  *    (delegated to CAAMP's canonical {@link ensureProviderInstructionFile}).
+ * 2. Installing the heavy-command `PreToolUse` hook (matcher `Bash`) in the
+ *    project's `.codex/hooks.json`, when `options.heavyCommandHook` is set.
+ *    Codex asks the user to review and trust a new project hook (`/hooks`)
+ *    before it runs it.
  *
  * @remarks
  * Installation is idempotent — running install multiple times on the same
- * project produces the same result. Only AGENTS.md is managed; Codex CLI
- * does not have an MCP or plugin registration mechanism.
+ * project produces the same result.
  *
  * @task T162
  * @epic T134
@@ -53,8 +60,25 @@ export class CodexInstallProvider implements AdapterInstallProvider {
       details.instructionFile = join(projectDir, result.instructFile);
     }
 
+    // T12983: route heavy shell commands through `cleo run`.
+    let success = true;
+    if (options.heavyCommandHook !== undefined && isUserHomeDir(projectDir)) {
+      details.heavyCommandHook = 'skipped';
+    } else if (options.heavyCommandHook !== undefined) {
+      try {
+        details.heavyCommandHook = await syncJsonHeavyCommandHook(
+          join(projectDir, '.codex', 'hooks.json'),
+          'codex',
+          options.heavyCommandHook,
+        );
+      } catch (err) {
+        details.settingsErrors = [err instanceof Error ? err.message : String(err)];
+        success = false;
+      }
+    }
+
     return {
-      success: true,
+      success,
       installedAt,
       instructionFileUpdated,
       details,

package/src/providers/kimi/install.ts

@@ -27,6 +27,21 @@ import { getCleoTemplatesTildePath } from '../shared/paths.js';
  * project produces the same result. Only AGENTS.md is managed; Kimi does
  * not have an MCP or plugin registration mechanism.
  *
+ * The heavy-command hook (T12983) is NOT installed for Kimi: Kimi reads
+ * `[[hooks]]` only from the user-global `~/.kimi/config.toml` (no project
+ * config, and CLEO installs this hook per project only), and its
+ * `PreToolUse` answer cannot rewrite the command. `cleo hook heavy-command
+ * --provider kimi` speaks Kimi's protocol (deny with the governed command as
+ * the reason) for a manual entry:
+ *
+ * ```toml
+ * [[hooks]]
+ * event = "PreToolUse"
+ * matcher = "Shell"
+ * command = "cleo hook heavy-command --provider kimi"
+ * timeout = 20
+ * ```
+ *
  * @task T163
  * @epic T134
  */

package/src/providers/opencode/install.ts

@@ -4,16 +4,22 @@
  * Handles CLEO installation into OpenCode environments:
  * - Ensures AGENTS.md has CLEO @-references via CAAMP
  * - Installs PreCompact hook shell shims + a JS plugin wrapper (T1013)
+ * - Installs the heavy-command `tool.execute.before` plugin (T12983)
  *
  * @task T5240
  * @task T1013
  * @task T9019
+ * @task T12983
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ensureProviderInstructionFile } from '@cleocode/caamp';
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
+import {
+  isUserHomeDir,
+  syncOpencodeHeavyCommandPlugin,
+} from '../shared/heavy-command-hook-install.js';
 import {
   type InstallHookTemplatesResult,
   installProviderHookTemplates,
@@ -69,8 +75,25 @@ export class OpenCodeInstallProvider implements AdapterInstallProvider {
       details.hookTemplates = hookResult;
     }
 
+    // Step 3 (T12983): `.opencode/plugins/cleo-heavy-command.js` routes heavy
+    // shell commands through `cleo run`.
+    let success = true;
+    if (options.heavyCommandHook !== undefined && isUserHomeDir(projectDir)) {
+      details.heavyCommandHook = 'skipped';
+    } else if (options.heavyCommandHook !== undefined) {
+      try {
+        details.heavyCommandHook = syncOpencodeHeavyCommandPlugin(
+          projectDir,
+          options.heavyCommandHook,
+        );
+      } catch (err) {
+        details.settingsErrors = [err instanceof Error ? err.message : String(err)];
+        success = false;
+      }
+    }
+
     return {
-      success: true,
+      success,
       installedAt,
       instructionFileUpdated,
       details,