@cleocode/adapters 2026.10.1 → 2026.10.3

package/dist/providers/claude-code/install.d.ts

@@ -4,10 +4,13 @@
  * Handles CLEO installation into Claude Code environments:
  * - Ensures CLAUDE.md has CLEO @-references
  * - Manages plugin registration in ~/.claude/settings.json
+ * - Installs the heavy-command `PreToolUse` hook in the PROJECT's
+ *   `.claude/settings.local.json` (T12983)
  *
  * Migrated from src/core/install/claude-plugin.ts
  *
  * @task T5240
+ * @task T12983
  */
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
 /**
@@ -17,6 +20,9 @@ import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cle
  * 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
+ * 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

package/dist/providers/claude-code/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/claude-code/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAyBjG;;;;;;;;;;;;;GAaG;AACH,qBAAa,yBAA0B,YAAW,sBAAsB;IACtE;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAwD9D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAkBrC;;;;;;;OAOG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE;;;;;;;;OAQG;IACH,OAAO,CAAC,eAAe;IAsBvB;;;;OAIG;YACW,cAAc;IAwB5B;;;;;;;;;;;;;;;;;;;OAmBG;YACW,oBAAoB;IAgClC;;;;;;;;;;;;;OAaG;YACW,sBAAsB;CAmBrC"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/claude-code/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AA6BjG;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,yBAA0B,YAAW,sBAAsB;IACtE;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IA0E9D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAkBrC;;;;;;;OAOG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE;;;;;;;;OAQG;IACH,OAAO,CAAC,eAAe;IAsBvB;;;;OAIG;YACW,cAAc;IAwB5B;;;;;;;;;;;;;;;;;;;OAmBG;YACW,oBAAoB;IAgClC;;;;;;;;;;;;;OAaG;YACW,sBAAsB;CAmBrC"}

package/dist/providers/claude-code/paths.d.ts

@@ -47,82 +47,5 @@ export declare class ClaudeCodePathProvider implements AdapterPathProvider {
  * ```
  */
 export declare function claudeSettingsPath(): string;
-/**
- * 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 declare function isPlainObject(value: unknown): value is Record<string, unknown>;
-/**
- * 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 declare function isCleoHookEntry(entry: unknown, commandIncludes?: string): boolean;
-/**
- * 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 declare function hasCleoHook(entries: unknown, commandIncludes?: string): boolean;
-/**
- * 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 declare function hookMap(settings: Record<string, unknown>): Record<string, unknown>;
-/**
- * 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 declare function appendHookEntry(hooks: Record<string, unknown>, event: string, entry: Record<string, unknown>): void;
-/**
- * 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 declare function removeCleoHookEntries(hooks: Record<string, unknown>): boolean;
+export { appendHookEntry, CLEO_HOOK_MARKER, hasCleoHook, hookMap, isCleoHookEntry, isPlainObject, removeCleoHookEntries, } from '../shared/hook-config.js';
 //# sourceMappingURL=paths.d.ts.map

package/dist/providers/claude-code/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/providers/claude-code/paths.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,qBAAa,sBAAuB,YAAW,mBAAmB;IAChE,uDAAuD;IACvD,cAAc,IAAI,MAAM;IAIxB,4EAA4E;IAC5E,eAAe,IAAI,MAAM,GAAG,IAAI;IAIhC,4EAA4E;IAC5E,kBAAkB,IAAI,MAAM,GAAG,IAAI;IAInC,8EAA8E;IAC9E,eAAe,IAAI,MAAM,GAAG,IAAI;CAGjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAI3C;AAKD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,CASjF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,CAE/E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWlF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAMN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAW7E"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/providers/claude-code/paths.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,qBAAa,sBAAuB,YAAW,mBAAmB;IAChE,uDAAuD;IACvD,cAAc,IAAI,MAAM;IAIxB,4EAA4E;IAC5E,eAAe,IAAI,MAAM,GAAG,IAAI;IAIhC,4EAA4E;IAC5E,kBAAkB,IAAI,MAAM,GAAG,IAAI;IAInC,8EAA8E;IAC9E,eAAe,IAAI,MAAM,GAAG,IAAI;CAGjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAI3C;AAED,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,OAAO,EACP,eAAe,EACf,aAAa,EACb,qBAAqB,GACtB,MAAM,0BAA0B,CAAC"}

package/dist/providers/codex/install.d.ts

@@ -3,9 +3,12 @@
  *
  * 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 type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
@@ -15,11 +18,14 @@ import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cle
  * 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

package/dist/providers/codex/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/codex/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGjG;;;;;;;;;;;;;;GAcG;AACH,qBAAa,oBAAqB,YAAW,sBAAsB;IACjE;;;;;;OAMG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAwB9D;;;;;OAKG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAIhC;;;;;OAKG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAerC;;;;;;;OAOG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAMrE"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/codex/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIjG;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,oBAAqB,YAAW,sBAAsB;IACjE;;;;;;OAMG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAyC9D;;;;;OAKG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAIhC;;;;;OAKG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAerC;;;;;;;OAOG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAMrE"}

package/dist/providers/kimi/install.d.ts

@@ -21,6 +21,21 @@ import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cle
  * 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/dist/providers/kimi/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/kimi/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGjG;;;;;;;;;;;;;;GAcG;AACH,qBAAa,mBAAoB,YAAW,sBAAsB;IAChE;;;;;;OAMG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAuB9D;;;;;OAKG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAIhC;;;;;OAKG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAiBrC;;;;;;;OAOG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAMrE"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/kimi/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGjG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,mBAAoB,YAAW,sBAAsB;IAChE;;;;;;OAMG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAuB9D;;;;;OAKG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAIhC;;;;;OAKG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAiBrC;;;;;;;OAOG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAMrE"}

package/dist/providers/opencode/install.d.ts

@@ -4,10 +4,12 @@
  * 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 type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
 /**

package/dist/providers/opencode/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/opencode/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAOjG;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,uBAAwB,YAAW,sBAAsB;IACpE;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAgC9D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAerC;;;;;;OAMG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOpE;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,oBAAoB;IAiC5B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,qBAAqB;CA0C9B"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/providers/opencode/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAWjG;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,uBAAwB,YAAW,sBAAsB;IACpE;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAiD9D;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAerC;;;;;;OAMG;IACG,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOpE;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,oBAAoB;IAiC5B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,qBAAqB;CA0C9B"}

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

@@ -0,0 +1,173 @@
+/**
+ * Install CLEO's heavy-command hook into a project's provider configs (T12983).
+ *
+ * The hook (`cleo hook heavy-command`, in `@cleocode/cleo`) runs before every
+ * shell command an agent issues and routes heavy work (tests, builds,
+ * typechecks, installs) through `cleo run`, the machine-wide resource budget.
+ * Delivery per provider:
+ *
+ * - Claude Code: a `PreToolUse` / `Bash` hook in
+ *   `<project>/.claude/settings.local.json`: project-level but per machine,
+ *   which fits a per-machine budget. When git does not ignore that file yet,
+ *   a marked block in the repository's `info/exclude` keeps it out of git.
+ * - Codex: the same hook in `<project>/.codex/hooks.json` (Codex asks the
+ *   user to review and trust a new project hook in `/hooks` before it runs).
+ * - opencode: a `tool.execute.before` / `tool.execute.after` plugin at
+ *   `<project>/.opencode/plugins/cleo-heavy-command.js`.
+ * - Kimi: not installed. Kimi reads hooks only from the global
+ *   `~/.kimi/config.toml` and cannot rewrite input; `cleo hook heavy-command
+ *   --provider kimi` speaks its protocol for a manual `[[hooks]]` entry.
+ *
+ * Project-level only: CLEO never writes this hook into a user-global config,
+ * and never into the home directory's provider configs. The hook command
+ * decides cheaply before it starts `cleo` (a tool name must appear as a whole
+ * word), guards against a missing or older `cleo`, and always exits 0. Only
+ * CLEO's own hook object is ever added, replaced or removed: a user hook that
+ * shares its matcher group stays. Mode `off` removes it again.
+ *
+ * @task T12983
+ * @epic T12978
+ */
+import type { HeavyCommandHookMode } from '@cleocode/contracts';
+/** Identifies the heavy-command hook among CLEO's hook commands. */
+export declare const HEAVY_COMMAND_HOOK_ID = "cleo hook heavy-command";
+/** Seconds a harness waits for the hook before it runs the command unchanged. */
+export declare const HEAVY_COMMAND_HOOK_TIMEOUT_SEC = 20;
+/** File name of the generated opencode plugin. */
+export declare const OPENCODE_HEAVY_COMMAND_PLUGIN = "cleo-heavy-command.js";
+/**
+ * Tool names that send a shell call on to `cleo hook`: a superset of the
+ * command words `run-class` treats as heavy (test runners, compilers,
+ * bundlers, linters, package managers and their exec runners, cargo, go).
+ * Matched as whole words only, so `cat test-notes.md` never starts `cleo`;
+ * recognition proper stays in `run-class` inside `cleo hook`.
+ */
+export declare const HEAVY_TOOL_WORDS: readonly string[];
+/**
+ * What a sync did to one config file. `skipped`: the project is the user's
+ * home directory, whose provider configs are the user-global ones.
+ */
+export type HeavyHookSyncResult = 'installed' | 'updated' | 'removed' | 'unchanged' | 'skipped';
+/**
+ * Whether `projectDir` is the user's home directory. There,
+ * `<home>/.claude/settings.local.json`, `<home>/.codex/hooks.json` and
+ * `<home>/.opencode/` act as user-global configs, and CLEO installs this
+ * hook per project only, so the installers skip it.
+ *
+ * @param projectDir - the project root an installer was given.
+ * @param home - the home directory (injectable for tests).
+ */
+export declare function isUserHomeDir(projectDir: string, home?: string): boolean;
+/**
+ * The context line an older CLEO gets: its `cleo` has no `cleo hook` (and so
+ * no `cleo run`), so the command runs unchanged and ungoverned. A
+ * Claude-style `PreToolUse` answer; no single quotes (it is inlined into a
+ * single-quoted `sh` word).
+ */
+export declare const OLDER_CLEO_HOOK_ANSWER: string;
+/** File-name prefix of the "this cleo has no `cleo hook`" markers in `$TMPDIR`. */
+export declare const OLDER_CLEO_MARKER_PREFIX = "cleo-hook-unsupported-";
+/**
+ * Delete this user's older-CLEO markers, so a CLEO that has just installed the
+ * hook is asked again at once instead of after the marker lapses.
+ *
+ * @param dir - the directory the hook command keeps markers in
+ *   (`$XDG_RUNTIME_DIR`, else `$TMPDIR`).
+ * @returns how many markers were removed.
+ */
+export declare function clearOlderCleoMarkers(dir?: string): number;
+/**
+ * The hook command line for a JSON hook config, ending in the `# cleo-hook`
+ * marker. Claude Code runs hook commands through `sh -c`, so its line is the
+ * guard script itself. Codex runs them through the user's login shell
+ * (`$SHELL -lc`, which may be fish), so its line hands the script to
+ * `/bin/sh -c` as one quoted word.
+ *
+ * @param provider - the harness protocol to answer in.
+ * @returns the command line for the provider's config.
+ *
+ * @example
+ * ```ts
+ * heavyCommandHookCommand('claude-code');
+ * // command -v cleo >/dev/null 2>&1 || exit 0; in="$(cat)"; set -f; …; exit 0 # cleo-hook
+ * heavyCommandHookCommand('codex');
+ * // /bin/sh -c 'command -v cleo >/dev/null 2>&1 || exit 0; …' # cleo-hook
+ * ```
+ */
+export declare function heavyCommandHookCommand(provider: 'claude-code' | 'codex'): string;
+/**
+ * CLEO's hook object (one element of a matcher group's `hooks` array).
+ *
+ * @param provider - `claude-code` or `codex`.
+ */
+export declare function heavyCommandHookObject(provider: 'claude-code' | 'codex'): Record<string, unknown>;
+/**
+ * The `hooks.PreToolUse` matcher group CLEO adds when none of the user's
+ * groups holds its hook yet (Claude Code and Codex both match `Bash`).
+ *
+ * @param provider - `claude-code` or `codex`.
+ */
+export declare function heavyCommandHookEntry(provider: 'claude-code' | 'codex'): Record<string, unknown>;
+/**
+ * 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
+ * touched; a malformed file throws and is left as it is.
+ *
+ * @param configPath - the config file (created when missing, unless `off`).
+ * @param provider - `claude-code` or `codex`.
+ * @param mode - the resolved hook mode.
+ * @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). */
+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
+ * 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.
+ * @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.
+ *
+ * @param projectDir - the project root.
+ * @returns whether a block was removed.
+ */
+export declare function unexcludeLocalSettingsFromGit(projectDir: string): boolean;
+/**
+ * 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
+ * `<project>/.claude/settings.json`.
+ *
+ * @param projectDir - the project root.
+ * @param mode - the resolved hook mode.
+ * @returns what changed in `settings.local.json`.
+ */
+export declare function syncClaudeCodeHeavyCommandHook(projectDir: string, mode: HeavyCommandHookMode): Promise<HeavyHookSyncResult>;
+/**
+ * Source of the opencode plugin. opencode runs plugins in-process:
+ * `tool.execute.before` may replace `output.args`, and
+ * `tool.execute.after` may extend the tool's output. The plugin skips calls
+ * with no {@link HEAVY_TOOL_WORDS} word, asks
+ * `cleo hook heavy-command --provider opencode` for the rest, applies a
+ * rewrite and its longer timeout, and appends the hook's context line to the
+ * tool's output (opencode has no other channel back to the agent).
+ */
+export declare function opencodeHeavyCommandPluginSource(): string;
+/**
+ * Write (or, mode `off`, delete) the opencode plugin in
+ * `<projectDir>/.opencode/plugins/`. Rewritten only when its content changed.
+ *
+ * @param projectDir - the project root.
+ * @param mode - the resolved hook mode.
+ * @returns what changed.
+ */
+export declare function syncOpencodeHeavyCommandPlugin(projectDir: string, mode: HeavyCommandHookMode): HeavyHookSyncResult;
+//# sourceMappingURL=heavy-command-hook-install.d.ts.map

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

@@ -0,0 +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"}

package/dist/providers/shared/hook-config.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Helpers for JSON hook configs shaped like Claude Code's `settings.json`
+ * `hooks` map: `{ "<Event>": [{ "matcher": "...", "hooks": [{ "type":
+ * "command", "command": "..." }] }] }`. Codex's `hooks.json` uses the same
+ * shape. Every command CLEO owns carries the `# cleo-hook` marker so CLEO can
+ * find (and remove) its own entries without touching user-authored ones.
+ *
+ * Moved from `claude-code/paths.ts` (T12385) so the Codex installer can share
+ * them (T12983); `claude-code/paths.ts` re-exports them.
+ *
+ * @task T12385
+ * @task T12983
+ */
+/** Marker CLEO puts in every hook command it owns. */
+export declare 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 declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * 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 declare function isCleoHookEntry(entry: unknown, commandIncludes?: string): boolean;
+/**
+ * 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 declare function hasCleoHook(entries: unknown, commandIncludes?: string): boolean;
+/**
+ * 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 declare function hookMap(settings: Record<string, unknown>): Record<string, unknown>;
+/**
+ * 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 declare function appendHookEntry(hooks: Record<string, unknown>, event: string, entry: Record<string, unknown>): void;
+/**
+ * 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 declare function removeCleoHookEntries(hooks: Record<string, unknown>): boolean;
+//# sourceMappingURL=hook-config.d.ts.map

package/dist/providers/shared/hook-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-config.d.ts","sourceRoot":"","sources":["../../../src/providers/shared/hook-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,gBAAgB,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,CASjF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,CAE/E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWlF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAMN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAW7E"}

package/package.json

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

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

@@ -4,18 +4,25 @@
  * Handles CLEO installation into Claude Code environments:
  * - Ensures CLAUDE.md has CLEO @-references
  * - Manages plugin registration in ~/.claude/settings.json
+ * - Installs the heavy-command `PreToolUse` hook in the PROJECT's
+ *   `.claude/settings.local.json` (T12983)
  *
  * Migrated from src/core/install/claude-plugin.ts
  *
  * @task T5240
+ * @task T12983
  */
 
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+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 {
+  isUserHomeDir,
+  syncClaudeCodeHeavyCommandHook,
+} from '../shared/heavy-command-hook-install.js';
 import {
   type InstallHookTemplatesResult,
   installProviderHookTemplates,
@@ -47,6 +54,9 @@ function getAdapterCommandsDir(): string {
  * 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
+ * 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
@@ -105,6 +115,24 @@ export class ClaudeCodeInstallProvider implements AdapterInstallProvider {
       settingsErrors.push(err instanceof Error ? err.message : String(err));
     }
 
+    // Step 5 (T12983): route heavy shell commands through `cleo run`.
+    // Project-level settings only; the user's ~/.claude is never touched.
+    if (options.heavyCommandHook !== undefined) {
+      const projectSettings = join(projectDir, '.claude', 'settings.json');
+      if (isUserHomeDir(projectDir) || resolve(projectSettings) === resolve(claudeSettingsPath())) {
+        details.heavyCommandHook = 'skipped';
+      } else {
+        try {
+          details.heavyCommandHook = await syncClaudeCodeHeavyCommandHook(
+            projectDir,
+            options.heavyCommandHook,
+          );
+        } catch (err) {
+          settingsErrors.push(err instanceof Error ? err.message : String(err));
+        }
+      }
+    }
+
     if (settingsErrors.length > 0) {
       details.settingsErrors = settingsErrors;
     }