@cleocode/adapters 2026.10.21 → 2026.10.22

package/src/providers/shared/heavy-command-hook-delivery.ts

@@ -52,14 +52,22 @@ import {
   heavyCommandHookObject,
   hookFileVisibleToGit,
   isHeavyHookObject,
+  isSessionEndHookObject,
+  isStopDispatchHookObject,
+  isSubagentStartHookObject,
   isUserHomeDir,
   nonDirectoryAncestor,
   OLDER_CLEO_MARKER_PREFIX,
   OPENCODE_PLUGIN_FILE,
   opencodeHeavyCommandPluginSource,
+  sessionEndHookObject,
+  stopDispatchHookObject,
+  subagentStartHookObject,
   syncClaudeCodeHeavyCommandHook,
   syncCodexHeavyCommandHook,
+  syncJsonSessionEndHook,
   syncJsonStopDispatchHook,
+  syncJsonSubagentStartHook,
   syncOpencodeHeavyCommandPlugin,
   trackedFileModified,
 } from './heavy-command-hook-install.js';
@@ -196,12 +204,15 @@ function errorText(err: unknown): string {
 
 /** Sync one provider; never throws. */
 /**
- * Install CLEO's one Stop hook (T13796): goal tick → ask-enforce (T13420) →
- * session end, folding the separate ask-enforce and session-end Stop hooks in
- * place. Claude Code always keeps it (its Stop hook ended the session before
- * the dispatcher); Codex's rides the heavy-command delivery and is removed
- * when that mode is `off`. Ask-enforce inside it honours `CLEO_ASK_ENFORCE` at
- * run time. Never fails the heavy-command outcome.
+ * Install CLEO's one Stop hook (T13796): goal tick → ask-enforce (T13420),
+ * folding the separate ask-enforce and old session-end Stop hooks in place.
+ * Claude Code always keeps it, with the SessionEnd hook that ends the CLEO
+ * session when the harness session really ends (T13913; a turn's Stop never
+ * does); Codex's rides the heavy-command delivery and is removed when that
+ * mode is `off`. Ask-enforce inside it honours `CLEO_ASK_ENFORCE` at run time.
+ * For Claude Code it also installs the SubagentStart lean hook (T13667),
+ * removed when the heavy-command mode is `off`. Never fails the heavy-command
+ * outcome.
  */
 async function syncStopDispatch(
   provider: 'claude-code' | 'codex',
@@ -213,6 +224,20 @@ async function syncStopDispatch(
   } catch {
     // Fail open: a config the Stop hook cannot be written to keeps the heavy-command result.
   }
+  if (provider !== 'claude-code') return;
+  try {
+    await syncJsonSessionEndHook(target, true);
+  } catch {
+    // Fail open, as above.
+  }
+  // T13667: the lean rules for harness-spawned subagents. The level (`off`
+  // included) is read at run time, so the hook is installed whenever the
+  // heavy-command hook is.
+  try {
+    await syncJsonSubagentStartHook(target, mode !== 'off');
+  } catch {
+    // Fail open, as above.
+  }
 }
 
 /**
@@ -249,8 +274,11 @@ export async function syncProjectStopDispatch(
       if (shared !== null) throw new HeavyHookSharedConfigError(target, shared);
     }
     const status = await syncJsonStopDispatchHook(target, provider, true);
-    if (provider === 'claude-code') excludeLocalSettingsFromGit(projectDir);
-    else excludeHookFileFromGit(projectDir, CODEX_HOOKS_FILE);
+    if (provider === 'claude-code') {
+      // T13913: the Stop no longer ends the session; SessionEnd does.
+      await syncJsonSessionEndHook(target, true);
+      excludeLocalSettingsFromGit(projectDir);
+    } else excludeHookFileFromGit(projectDir, CODEX_HOOKS_FILE);
     return { provider, status, target };
   } catch (err) {
     return {
@@ -364,9 +392,72 @@ export async function syncProjectHeavyCommandHooks(
 /** What a JSON hook config holds: CLEO's hook (current or not), or why it cannot say. */
 type JsonHookPresence =
   | { readonly kind: 'absent' }
-  | { readonly kind: 'present'; readonly current: boolean }
+  | {
+      readonly kind: 'present';
+      readonly current: boolean;
+      /** Why it is not current, when a companion hook is missing or stale (T13960). */
+      readonly stale?: string;
+    }
   | { readonly kind: 'unreadable'; readonly error: string };
 
+/**
+ * The hooks CLEO installs beside the heavy-command hook (T13960): the Stop
+ * dispatcher, and for Claude Code the SessionEnd and SubagentStart hooks. A
+ * binary updated without a hook re-sync keeps the old set, e.g. a Stop that
+ * still ends the session and no SessionEnd, so each is audited too. With the
+ * heavy-command mode `off`, Claude Code keeps only its Stop and SessionEnd
+ * hooks and Codex keeps none (what sync installs).
+ */
+function companionHooks(
+  provider: 'claude-code' | 'codex',
+  modeOff = false,
+): ReadonlyArray<readonly [string, Record<string, unknown>, (hook: unknown) => boolean]> {
+  const stop = ['Stop', stopDispatchHookObject(provider), isStopDispatchHookObject] as const;
+  if (provider === 'codex') return modeOff ? [] : [stop];
+  const end = ['SessionEnd', sessionEndHookObject(), isSessionEndHookObject] as const;
+  return modeOff
+    ? [stop, end]
+    : [stop, end, ['SubagentStart', subagentStartHookObject(), isSubagentStartHookObject]];
+}
+
+/** The first companion hook that is missing or differs from this build's, named, or null. */
+function staleCompanion(
+  hooks: Record<string, unknown>,
+  provider: 'claude-code' | 'codex',
+  modeOff = false,
+): string | null {
+  for (const [event, desired, isMine] of companionHooks(provider, modeOff)) {
+    const groups = hooks[event];
+    const mine = (Array.isArray(groups) ? groups : [])
+      .flatMap((g) => (isPlainObject(g) && Array.isArray(g.hooks) ? g.hooks : []))
+      .filter(isMine);
+    if (mine.length === 0) return `its ${event} hook is missing`;
+    if (!mine.some((h) => JSON.stringify(h) === JSON.stringify(desired))) {
+      return `its ${event} hook was written by another CLEO build`;
+    }
+  }
+  return null;
+}
+
+/**
+ * With the heavy-command mode `off`: the first of Claude Code's own Stop and
+ * SessionEnd hooks that is missing or stale in `file`, or null (also when the
+ * file cannot be read: that is reported elsewhere).
+ */
+function offCompanionStale(file: string): string | null {
+  let config: unknown = {};
+  try {
+    const raw = readFileSync(file, 'utf-8');
+    if (raw.trim() !== '') config = JSON.parse(raw);
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== 'ENOENT' && code !== 'ENOTDIR') return null;
+  }
+  if (!isPlainObject(config)) return null;
+  const hooks = isPlainObject(config.hooks) ? config.hooks : {};
+  return staleCompanion(hooks, 'claude-code', true);
+}
+
 /** Find CLEO's heavy-command hook in a JSON hook config (`hooks.PreToolUse[].hooks[]`). */
 function jsonHookPresence(file: string, provider: 'claude-code' | 'codex'): JsonHookPresence {
   let raw: string;
@@ -396,7 +487,12 @@ function jsonHookPresence(file: string, provider: 'claude-code' | 'codex'): Json
     if (!isPlainObject(group) || !Array.isArray(group.hooks)) continue;
     for (const hook of group.hooks) {
       if (!isHeavyHookObject(hook)) continue;
-      if (JSON.stringify(hook) === expected) return { kind: 'present', current: true };
+      if (JSON.stringify(hook) === expected) {
+        const stale = isPlainObject(hooks) ? staleCompanion(hooks, provider) : null;
+        return stale === null
+          ? { kind: 'present', current: true }
+          : { kind: 'present', current: false, stale };
+      }
       found = { kind: 'present', current: false };
     }
   }
@@ -469,6 +565,17 @@ function inspectProvider(
     };
   }
   if (mode === 'off') {
+    // T13960: Claude Code keeps its Stop and SessionEnd hooks whatever the mode,
+    // so an update without a re-sync must not read as `disabled`.
+    const stale = provider === 'claude-code' && detected ? offCompanionStale(target) : null;
+    if (stale !== null) {
+      return {
+        ...base,
+        state: 'outdated',
+        detail: `resources.heavyCommandHook is off, but ${stale} in ${target}`,
+        remedy: `run: ${HEAVY_HOOK_FIX_COMMAND}`,
+      };
+    }
     return presence.kind === 'present'
       ? {
           ...base,
@@ -479,11 +586,22 @@ function inspectProvider(
       : { ...base, state: 'disabled', detail: 'resources.heavyCommandHook is off' };
   }
   if (presence.kind === 'present') {
-    if (!presence.current) {
+    // A project's own (committed) .codex/hooks.json is the team's: CLEO never
+    // writes its Stop entry there either, so a missing or stale companion is
+    // not CLEO's to flag (--fix would refuse it); the shared-config checks
+    // below still apply.
+    const companionOnly =
+      presence.stale !== undefined &&
+      provider === 'codex' &&
+      codexHooksSharedReason(projectDir, gitChecks) !== null;
+    if (!presence.current && !companionOnly) {
       return {
         ...base,
         state: 'outdated',
-        detail: `the hook in ${target} (or a legacy location) was written by another CLEO build`,
+        detail:
+          presence.stale !== undefined
+            ? `the hook in ${target} is current, but ${presence.stale}`
+            : `the hook in ${target} (or a legacy location) was written by another CLEO build`,
         remedy: `run: ${HEAVY_HOOK_FIX_COMMAND}`,
       };
     }

package/src/providers/shared/heavy-command-hook-install.ts

@@ -463,14 +463,15 @@ export function isAskEnforceHookObject(hook: unknown): boolean {
 /** The command CLEO's Stop dispatcher runs (T13796); also its marker. */
 export const STOP_DISPATCH_HOOK_ID = 'cleo hook stop';
 
-/** Seconds a Stop dispatch may take: the goal tick (30 s), ask-enforce and `cleo session end`. */
+/** Seconds a Stop dispatch may take: the goal tick (60 s at most) and ask-enforce. */
 export const STOP_DISPATCH_HOOK_TIMEOUT_SEC = 120;
 
 /** Claude Code's Stop command before T13796, which ended the session on its own. */
 export const LEGACY_SESSION_END_STOP_COMMAND = 'cleo session end --quiet # cleo-hook';
 
 /**
- * CLEO's one Stop hook object (T13796): goal tick → ask-enforce → session end.
+ * CLEO's one Stop hook object (T13796): goal tick → ask-enforce. It never ends
+ * the session (T13913); {@link sessionEndHookObject} does, on `SessionEnd`.
  * Like the ask-enforce script, it forwards only a JSON answer and always exits
  * 0, so a machine without `cleo` (or with an older one) is never blocked.
  *
@@ -561,6 +562,151 @@ export async function syncJsonStopDispatchHook(
   return result;
 }
 
+/** The command CLEO's SubagentStart lean hook runs (T13667); also its marker. */
+export const SUBAGENT_START_HOOK_ID = 'cleo hook subagent-start';
+
+/**
+ * CLEO's SubagentStart lean hook object (T13667), Claude Code only. Like the
+ * Stop dispatcher, it forwards only a JSON answer and always exits 0, so a
+ * machine without `cleo` (or with an older one) never breaks a subagent.
+ */
+export function subagentStartHookObject(): Record<string, unknown> {
+  const script = `command -v cleo >/dev/null 2>&1 || exit 0; out="$(${SUBAGENT_START_HOOK_ID} --provider claude-code 2>/dev/null)"; case "$out" in "{"*) printf '%s\\n' "$out";; esac; exit 0`;
+  return {
+    type: 'command',
+    command: `${script} ${CLEO_HOOK_MARKER}`,
+    timeout: HEAVY_COMMAND_HOOK_TIMEOUT_SEC,
+  };
+}
+
+/** Whether one hook object is CLEO's SubagentStart lean hook. */
+export function isSubagentStartHookObject(hook: unknown): boolean {
+  return (
+    isPlainObject(hook) &&
+    typeof hook.command === 'string' &&
+    hook.command.includes(CLEO_HOOK_MARKER) &&
+    hook.command.includes(`${SUBAGENT_START_HOOK_ID} `)
+  );
+}
+
+/**
+ * Add, refresh or (`install: false`) remove CLEO's SubagentStart lean hook
+ * (`hooks.SubagentStart`, T13667) through CAAMP's locked atomic writer. Claude
+ * Code only: Codex has no SubagentStart event, and CLEO-spawned agents get the
+ * rules from the spawn prompt. Only CLEO's own object is touched; a malformed
+ * file throws untouched.
+ *
+ * @param configPath - Claude Code's `.claude/settings.local.json`.
+ * @param install - `false` removes the hook.
+ * @returns what changed.
+ */
+export function syncJsonSubagentStartHook(
+  configPath: string,
+  install: boolean,
+): Promise<HeavyHookSyncResult> {
+  return syncJsonEventHook(
+    configPath,
+    'SubagentStart',
+    install ? subagentStartHookObject() : null,
+    isSubagentStartHookObject,
+  );
+}
+
+/** The command CLEO's SessionEnd hook runs (T13913); also its marker. */
+export const SESSION_END_HOOK_ID = 'cleo hook session-end';
+
+/** Seconds the SessionEnd hook may take: `cleo session end`, waited for at most 20 s, then detached. */
+export const SESSION_END_HOOK_TIMEOUT_SEC = 30;
+
+/**
+ * CLEO's SessionEnd hook object (T13913), Claude Code only: the harness
+ * session really ended, so the CLEO session ends. A turn's Stop no longer
+ * does. Prints nothing and always exits 0, so a machine without `cleo` (or
+ * with an older one) never breaks the exit.
+ */
+export function sessionEndHookObject(): Record<string, unknown> {
+  const script = `command -v cleo >/dev/null 2>&1 || exit 0; ${SESSION_END_HOOK_ID} --provider claude-code >/dev/null 2>&1; exit 0`;
+  return {
+    type: 'command',
+    command: `${script} ${CLEO_HOOK_MARKER}`,
+    timeout: SESSION_END_HOOK_TIMEOUT_SEC,
+  };
+}
+
+/** Whether one hook object is CLEO's SessionEnd hook. */
+export function isSessionEndHookObject(hook: unknown): boolean {
+  return (
+    isPlainObject(hook) &&
+    typeof hook.command === 'string' &&
+    hook.command.includes(CLEO_HOOK_MARKER) &&
+    hook.command.includes(`${SESSION_END_HOOK_ID} `)
+  );
+}
+
+/**
+ * Leave exactly one CLEO SessionEnd hook (T13913) in a `hooks` map, or
+ * (`install: false`) none; user hooks stay.
+ *
+ * @param hooks - The config's `hooks` map (edited in place).
+ * @param install - `false` removes it.
+ * @returns whether the map changed.
+ */
+export function applySessionEndHook(hooks: Record<string, unknown>, install: boolean): boolean {
+  const desired = install ? sessionEndHookObject() : null;
+  const placed = placeHeavyHook(hooks, desired, 'SessionEnd', isSessionEndHookObject);
+  if (desired === null || placed.found) return placed.changed;
+  appendHookEntry(hooks, 'SessionEnd', { hooks: [desired] });
+  return true;
+}
+
+/**
+ * Add, refresh or (`install: false`) remove CLEO's SessionEnd hook
+ * (`hooks.SessionEnd`, T13913) through CAAMP's locked atomic writer. Claude
+ * Code only: Codex has no session-end event. A malformed file throws
+ * untouched.
+ *
+ * @param configPath - Claude Code's `.claude/settings.local.json`.
+ * @param install - `false` removes the hook.
+ * @returns what changed.
+ */
+export function syncJsonSessionEndHook(
+  configPath: string,
+  install: boolean,
+): Promise<HeavyHookSyncResult> {
+  return syncJsonEventHook(
+    configPath,
+    'SessionEnd',
+    install ? sessionEndHookObject() : null,
+    isSessionEndHookObject,
+  );
+}
+
+/** Place one CLEO hook object on one event (null removes it), through CAAMP's locked writer. */
+async function syncJsonEventHook(
+  configPath: string,
+  event: string,
+  desired: Record<string, unknown> | null,
+  match: (hook: unknown) => boolean,
+): Promise<HeavyHookSyncResult> {
+  const install = desired !== null;
+  if (!install && !existsSync(configPath)) return 'unchanged';
+  if (install) ensureParentDir(configPath);
+  let result: HeavyHookSyncResult = 'unchanged';
+  await updateJsonConfigFile(configPath, (config) => {
+    if (!install && config.hooks === undefined) return false;
+    const hooks = hookMap(config);
+    const placed = placeHeavyHook(hooks, desired, event, match);
+    if (desired === null || placed.found) {
+      if (placed.changed) result = install ? 'updated' : 'removed';
+      return placed.changed;
+    }
+    appendHookEntry(hooks, event, { hooks: [desired] });
+    result = 'installed';
+    return true;
+  });
+  return result;
+}
+
 /** Claude Code's per-machine settings file, relative to the project. */
 export const CLAUDE_LOCAL_SETTINGS = '.claude/settings.local.json';