@cleocode/adapters 2026.10.17 → 2026.10.18

package/src/project-hook-delivery.ts

@@ -2,7 +2,7 @@
 import { execFileSync, spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
-import { lstat, realpath, rmdir, unlink } from 'node:fs/promises';
+import { lstat, mkdir, realpath, rmdir, unlink } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import {
@@ -580,6 +580,128 @@ async function validateStateDirectory(options: ProjectHookDeliveryOptions): Prom
     throw new Error('HOOK_STATE_DIRECTORY_INVALID');
 }
 
+/**
+ * Providers that read a linked worktree's project hooks from the root checkout. Codex replaces a
+ * worktree layer's hooks with the matching root-checkout `.codex` folder, and discovers that layer
+ * only when the worktree has its own `.codex` directory (codex-rs `merge_root_checkout_project_hooks`).
+ */
+const ROOT_CHECKOUT_HOOK_PROVIDERS = new Set(['codex']);
+
+/** Root-checkout delivery options when `projectRoot` is a linked worktree, mirroring Codex's root check. */
+async function rootCheckoutOptions(
+  options: ProjectHookDeliveryOptions,
+): Promise<ProjectHookDeliveryOptions | undefined> {
+  const git = (cwd: string, ...args: string[]): string | undefined => {
+    try {
+      return execFileSync('git', ['-C', cwd, 'rev-parse', ...args], {
+        encoding: 'utf8',
+        timeout: 2000,
+        maxBuffer: 16384,
+        stdio: ['ignore', 'pipe', 'ignore'],
+        env: options.services.gitEnvironment,
+      }).trim();
+    } catch {
+      return undefined;
+    }
+  };
+  const common = git(options.projectRoot, '--path-format=absolute', '--git-common-dir');
+  const gitDir = git(options.projectRoot, '--path-format=absolute', '--git-dir');
+  if (!common || !gitDir || (await realpath(common)) === (await realpath(gitDir))) return undefined;
+  // Like Codex, only a root whose own .git resolves to the shared common directory counts.
+  const rootGitDir = git(dirname(common), '--path-format=absolute', '--git-dir');
+  const root = git(dirname(common), '--show-toplevel');
+  const stateDir = git(
+    dirname(common),
+    '--path-format=absolute',
+    '--git-path',
+    'cleo-project-hooks',
+  );
+  if (
+    !rootGitDir ||
+    !root ||
+    !stateDir ||
+    (await realpath(rootGitDir)) !== (await realpath(common))
+  )
+    return undefined;
+  return { ...options, projectRoot: root, stateDir: resolve(root, stateDir) };
+}
+
+/** Run one provider delivery under its receipt lock (dry runs write no lock file). */
+function deliverLocked(
+  options: ProjectHookDeliveryOptions,
+  provider: string,
+): Promise<ProjectHookDeliveryResult> {
+  return options.dryRun
+    ? deliverProvider(options, provider)
+    : withFileLock(join(options.stateDir, 'provider-' + provider + '.json'), () =>
+        deliverProvider(options, provider),
+      );
+}
+
+/** Deliver into the root checkout the provider reads, keeping the worktree discoverable (T13772). */
+async function deliverFromLinkedWorktree(
+  worktree: ProjectHookDeliveryOptions,
+  root: ProjectHookDeliveryOptions,
+  provider: string,
+): Promise<ProjectHookDeliveryResult> {
+  const configPath = GENERATED_PROVIDER_HOOK_PROFILES[provider]?.projectDelivery?.configPath;
+  if (!configPath) return deliverLocked(worktree, provider);
+  // Earlier releases wrote worktree-local entries the provider never reads; undo them by receipt.
+  if (!worktree.dryRun && existsSync(join(worktree.stateDir, 'provider-' + provider + '.json')))
+    await deliverLocked({ ...worktree, rollback: true }, provider);
+  const folder = await localTarget(worktree.projectRoot, dirname(configPath));
+  if (worktree.rollback) {
+    // The root entry also serves the root checkout and sibling worktrees, so it stays; this
+    // worktree's disabled activation already makes it a no-op here. rmdir keeps foreign files.
+    if (!worktree.dryRun) await rmdir(folder).catch(() => undefined);
+    return {
+      provider,
+      state: 'disabled',
+      capability: 'unverified',
+      nativeTrust: 'unverified',
+      provenance: 'unknown',
+      diagnostics: ['HOOK_ROOT_CHECKOUT_ENTRY_RETAINED'],
+    };
+  }
+  // The root entry serves the root checkout and every sibling, so a worktree only grows it;
+  // shrinking stays with a root sync or root disable. Extra events are inert in a checkout
+  // whose own activation does not bind them.
+  if (worktree.events.length === 0)
+    return {
+      provider,
+      state: 'unsupported',
+      capability: 'unverified',
+      nativeTrust: 'unverified',
+      provenance: 'unknown',
+      diagnostics: ['HOOK_NO_AGENT_BINDINGS', 'HOOK_ROOT_CHECKOUT_ENTRY_RETAINED'],
+    };
+  const receiptPath = join(root.stateDir, 'provider-' + provider + '.json');
+  const deliver = async (): Promise<ProjectHookDeliveryResult> => {
+    const prior = await receiptAt(receiptPath, root.services);
+    const delivered = (prior?.entries ?? []).flatMap(
+      (item) => /--event ([A-Za-z][A-Za-z0-9]*)/.exec(item.command)?.[1] ?? [],
+    );
+    return deliverProvider(
+      {
+        ...root,
+        events: [...new Set([...delivered, ...worktree.events])],
+        enabled: worktree.enabled,
+        dryRun: worktree.dryRun,
+      },
+      provider,
+    );
+  };
+  const result = worktree.dryRun ? await deliver() : await withFileLock(receiptPath, deliver);
+  result.diagnostics.push('HOOK_ROOT_CHECKOUT_DELIVERY');
+  if (
+    !worktree.dryRun &&
+    (result.state === 'installed' || result.state === 'current') &&
+    !existsSync(folder)
+  )
+    await mkdir(folder);
+  return result;
+}
+
 /** Inspect or sync only project-local entries; no provider trust settings are written. */
 export async function syncProjectHookProviders(
   options: ProjectHookDeliveryOptions,
@@ -606,12 +728,14 @@ export async function syncProjectHookProviders(
       )
         throw new Error('HOOK_PROVIDER_INVALID');
       await validateStateDirectory(options);
+      const root = ROOT_CHECKOUT_HOOK_PROVIDERS.has(provider)
+        ? await rootCheckoutOptions(options)
+        : undefined;
+      if (root) await validateStateDirectory(root);
       outcomes.push(
-        options.dryRun
-          ? await deliverProvider(options, provider)
-          : await withFileLock(join(options.stateDir, 'provider-' + provider + '.json'), () =>
-              deliverProvider(options, provider),
-            ),
+        root
+          ? await deliverFromLinkedWorktree(options, root, provider)
+          : await deliverLocked(options, provider),
       );
     } catch (error) {
       outcomes.push({

package/src/providers/claude-code/__tests__/stop-dispatch-hook.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Claude Code's native Stop hook is the one Stop dispatcher (T13796): a fresh
+ * project gets `cleo hook stop`, and a project carrying the pre-dispatcher
+ * `cleo session end --quiet` Stop entry has it replaced in place, the user's
+ * own hooks untouched.
+ *
+ * @task T13796
+ */
+
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { askEnforceHookObject } from '../../shared/heavy-command-hook-install.js';
+import {
+  ClaudeCodeHookProvider,
+  LEGACY_NATIVE_STOP_HOOK_COMMAND,
+  NATIVE_NEXUS_HOOK_COMMAND,
+  NATIVE_OBSERVE_HOOK_COMMAND,
+  NATIVE_STOP_HOOK_COMMAND,
+} from '../hooks.js';
+
+let root: string;
+let projectDir: string;
+let savedHome: string | undefined;
+
+beforeEach(() => {
+  savedHome = process.env.HOME;
+  root = mkdtempSync(join(tmpdir(), 'cleo-stop-dispatch-'));
+  projectDir = join(root, 'project');
+  mkdirSync(join(projectDir, '.claude'), { recursive: true });
+  execFileSync('git', ['init', '-q', projectDir]);
+  process.env.HOME = join(root, 'home');
+});
+
+afterEach(() => {
+  if (savedHome === undefined) delete process.env.HOME;
+  else process.env.HOME = savedHome;
+  rmSync(root, { recursive: true, force: true });
+});
+
+type Settings = { hooks: Record<string, Array<{ hooks: Array<{ command: string }> }>> };
+const read = (): Settings =>
+  JSON.parse(readFileSync(join(projectDir, '.claude', 'settings.local.json'), 'utf-8'));
+const stopCommands = (s: Settings) =>
+  (s.hooks.Stop ?? []).flatMap((e) => e.hooks.map((h) => h.command));
+
+describe('Claude Code Stop dispatcher hook (T13796)', () => {
+  it('registers cleo hook stop as the Stop command', async () => {
+    expect(NATIVE_STOP_HOOK_COMMAND).toContain('cleo hook stop --provider claude-code 2>/dev/null');
+    expect(NATIVE_STOP_HOOK_COMMAND.endsWith('exit 0 # cleo-hook')).toBe(true);
+    await new ClaudeCodeHookProvider().registerNativeHooks(projectDir);
+    expect(stopCommands(read())).toEqual([NATIVE_STOP_HOOK_COMMAND]);
+  });
+
+  it('folds the old session-end and ask-enforce Stop entries into one dispatcher, keeping user hooks', async () => {
+    writeFileSync(
+      join(projectDir, '.claude', 'settings.local.json'),
+      JSON.stringify({
+        hooks: {
+          Stop: [
+            { matcher: '', hooks: [{ type: 'command', command: LEGACY_NATIVE_STOP_HOOK_COMMAND }] },
+            { matcher: '', hooks: [{ type: 'command', command: 'my-stop.sh' }] },
+            { hooks: [askEnforceHookObject('claude-code')] },
+          ],
+          PostToolUse: [
+            {
+              matcher: 'Write|Edit',
+              hooks: [
+                { type: 'command', command: NATIVE_OBSERVE_HOOK_COMMAND },
+                { type: 'command', command: NATIVE_NEXUS_HOOK_COMMAND },
+              ],
+            },
+          ],
+        },
+      }),
+    );
+    const provider = new ClaudeCodeHookProvider();
+    await provider.registerNativeHooks(projectDir);
+    const after = read();
+    expect(stopCommands(after).sort()).toEqual([NATIVE_STOP_HOOK_COMMAND, 'my-stop.sh'].sort());
+    expect(JSON.stringify(after)).not.toContain(LEGACY_NATIVE_STOP_HOOK_COMMAND);
+    expect(JSON.stringify(after)).not.toContain('cleo hook ask-enforce');
+    expect(after.hooks.PostToolUse?.flatMap((e) => e.hooks.map((h) => h.command))).toEqual([
+      NATIVE_OBSERVE_HOOK_COMMAND,
+      NATIVE_NEXUS_HOOK_COMMAND,
+    ]);
+    // Idempotent once migrated.
+    const bytes = readFileSync(join(projectDir, '.claude', 'settings.local.json'), 'utf-8');
+    await provider.registerNativeHooks(projectDir);
+    expect(readFileSync(join(projectDir, '.claude', 'settings.local.json'), 'utf-8')).toBe(bytes);
+  });
+});

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

@@ -22,11 +22,25 @@ import { join } from 'node:path';
 import { updateJsonConfigFile } from '@cleocode/caamp';
 import { PROVIDER_NATIVE_EVENT_MAPS } from '@cleocode/caamp/hooks';
 import type { AdapterHookProvider } from '@cleocode/contracts';
-import { excludeLocalSettingsFromGit } from '../shared/heavy-command-hook-install.js';
+import {
+  applyStopDispatch,
+  excludeLocalSettingsFromGit,
+  isStopDispatchHookObject,
+  LEGACY_SESSION_END_STOP_COMMAND,
+  stopDispatchHookObject,
+} from '../shared/heavy-command-hook-install.js';
 import { appendHookEntry, hookMap, isPlainObject, projectClaudeSettingsPath } from './paths.js';
 
-/** The `Stop` hook command: end the CLEO session when Claude Code stops. */
-export const NATIVE_STOP_HOOK_COMMAND = 'cleo session end --quiet # cleo-hook';
+/**
+ * The `Stop` hook command: the one Stop dispatcher (T13796). It asks a live
+ * goal runtime first and ends the CLEO session only when the goal says the
+ * turn is final or no goal is live, so a goal hook and the session end never
+ * fight over the event.
+ */
+export const NATIVE_STOP_HOOK_COMMAND = String(stopDispatchHookObject('claude-code').command);
+
+/** The `Stop` command before T13796; recognised so registration replaces it. */
+export const LEGACY_NATIVE_STOP_HOOK_COMMAND = LEGACY_SESSION_END_STOP_COMMAND;
 
 /** The `PostToolUse` (`Write|Edit`) hook command: a brain observation per file write. */
 export const NATIVE_OBSERVE_HOOK_COMMAND =
@@ -43,6 +57,7 @@ export const NATIVE_NEXUS_HOOK_COMMAND =
 /** Every command {@link ClaudeCodeHookProvider.registerNativeHooks} writes, and alone may remove. */
 const NATIVE_HOOK_COMMANDS: ReadonlySet<string> = new Set([
   NATIVE_STOP_HOOK_COMMAND,
+  LEGACY_NATIVE_STOP_HOOK_COMMAND,
   NATIVE_OBSERVE_HOOK_COMMAND,
   NATIVE_NEXUS_HOOK_COMMAND,
 ]);
@@ -56,20 +71,22 @@ function isNativeHookObject(hook: unknown): boolean {
   );
 }
 
-/** Whether any event of a `hooks` map already holds a native hook. */
-function hasNativeHooks(hooks: Record<string, unknown>): boolean {
+/** Whether any event of a `hooks` map holds a hook object `match` accepts. */
+function holdsHook(hooks: Record<string, unknown>, match: (hook: unknown) => boolean): boolean {
   return Object.values(hooks).some(
     (entries) =>
       Array.isArray(entries) &&
       entries.some(
-        (entry) =>
-          isPlainObject(entry) &&
-          Array.isArray(entry.hooks) &&
-          entry.hooks.some(isNativeHookObject),
+        (entry) => isPlainObject(entry) && Array.isArray(entry.hooks) && entry.hooks.some(match),
       ),
   );
 }
 
+/** Whether any event of a `hooks` map already holds a native hook. */
+function hasNativeHooks(hooks: Record<string, unknown>): boolean {
+  return holdsHook(hooks, isNativeHookObject);
+}
+
 /**
  * Remove the native hook objects from every event, then any entry left with
  * no hooks and any event left with no entries. Other hooks sharing an entry
@@ -181,7 +198,8 @@ export class ClaudeCodeHookProvider implements AdapterHookProvider {
    * Idempotent: skips writing if the native hooks are already present.
    *
    * Hook entries registered:
-   * - `Stop` → `cleo session end --quiet` (triggers LLM extraction, reflector, consolidation)
+   * - `Stop` → `cleo hook stop` (the goal runtime first, then `cleo session end`,
+   *   which triggers LLM extraction, reflector, consolidation; T13796)
    * - `PostToolUse` (Write|Edit) → brain observation for file modifications
    *   and the NEXUS post-check
    *
@@ -196,12 +214,11 @@ export class ClaudeCodeHookProvider implements AdapterHookProvider {
     // untouched — never replaced with an object holding only CLEO's entries.
     const wrote = await this.updateSettings(projectDir, (settings) => {
       const hooks = hookMap(settings);
-      if (hasNativeHooks(hooks)) return false; // Already wired — idempotent
-
-      appendHookEntry(hooks, 'Stop', {
-        matcher: '',
-        hooks: [{ type: 'command', command: NATIVE_STOP_HOOK_COMMAND }],
-      });
+      // A fresh project gets every native hook; a wired one keeps its PostToolUse as the user left it.
+      const fresh = !hasNativeHooks(hooks) && !holdsHook(hooks, isStopDispatchHookObject);
+      // T13796: one Stop hook, folding in the separate ask-enforce and old session-end hooks.
+      const stopChanged = applyStopDispatch(hooks, 'claude-code', true);
+      if (!fresh) return stopChanged;
       appendHookEntry(hooks, 'PostToolUse', {
         matcher: 'Write|Edit',
         hooks: [

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

@@ -96,20 +96,23 @@ describe('syncProjectHeavyCommandHooks', () => {
     });
   });
 
-  it('installs the ask-enforce Stop hook beside it for Claude Code and Codex (T13420)', async () => {
+  it('installs ONE Stop dispatcher (goal → ask-enforce → session end) for Claude Code and Codex (T13796)', async () => {
     useAll();
     await syncProjectHeavyCommandHooks(project, 'rewrite', { env });
     const stop = (file: string) =>
       JSON.stringify(JSON.parse(readFileSync(file, 'utf-8')).hooks.Stop ?? []);
     const claude = join(project, '.claude', 'settings.local.json');
     const codex = join(project, '.codex', 'hooks.json');
-    expect(stop(claude)).toContain('cleo hook ask-enforce --provider claude-code');
-    expect(stop(codex)).toContain('cleo hook ask-enforce --provider codex');
-    await syncProjectHeavyCommandHooks(project, 'rewrite', {
-      env: { ...env, CLEO_ASK_ENFORCE: 'off' },
-    });
+    expect(stop(claude)).toContain('cleo hook stop --provider claude-code');
+    expect(stop(codex)).toContain('cleo hook stop --provider codex');
+    // Ask-enforce runs inside the dispatcher; there is no separate Stop entry for it.
     expect(stop(claude)).not.toContain('ask-enforce');
     expect(stop(codex)).not.toContain('ask-enforce');
+    expect(stop(claude).match(/cleo hook stop/g)).toHaveLength(1);
+    // Mode off removes Codex's dispatcher; Claude Code's keeps its session end.
+    await syncProjectHeavyCommandHooks(project, 'off', { env });
+    expect(stop(codex)).not.toContain('cleo hook stop');
+    expect(stop(claude)).toContain('cleo hook stop --provider claude-code');
   });
 
   it('a .codex FILE blocks only Codex, with the reason and remedy; the others install', async () => {

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

@@ -55,12 +55,15 @@ import {
   heavyCommandHookEntry,
   heavyCommandHookObject,
   isUserHomeDir,
+  LEGACY_SESSION_END_STOP_COMMAND,
   LOCAL_SETTINGS_EXCLUDE_MARKER,
   OLDER_CLEO_HOOK_ANSWER,
   OLDER_CLEO_MARKER_PREFIX,
   OPENCODE_HEAVY_COMMAND_PLUGIN,
-  syncJsonAskEnforceHook,
+  STOP_DISPATCH_HOOK_ID,
+  stopDispatchHookObject,
   syncJsonHeavyCommandHook,
+  syncJsonStopDispatchHook,
   syncOpencodeHeavyCommandPlugin,
 } from '../heavy-command-hook-install.js';
 
@@ -330,40 +333,44 @@ describe.each(SHELLS)('heavyCommandHookCommand under %s', (shell) => {
   });
 });
 
-describe('syncJsonAskEnforceHook (T13420)', () => {
-  const read = (p: string) => JSON.parse(readFileSync(p, 'utf-8'));
-
-  it('adds one Stop entry beside the heavy-command hook, then is idempotent', async () => {
-    const path = join(dir, 'project', '.claude', 'settings.local.json');
-    await syncJsonHeavyCommandHook(path, 'claude-code', 'rewrite');
-    expect(await syncJsonAskEnforceHook(path, 'claude-code', true)).toBe('installed');
-    expect(read(path).hooks).toEqual({
-      PreToolUse: [heavyCommandHookEntry('claude-code')],
-      Stop: [{ hooks: [askEnforceHookObject('claude-code')] }],
-    });
-    expect(await syncJsonAskEnforceHook(path, 'claude-code', true)).toBe('unchanged');
+describe('askEnforceHookObject (T13420)', () => {
+  it('runs a fail-open script: exits 0 and prints only a JSON answer', () => {
+    const claude = String(askEnforceHookObject('claude-code').command);
+    expect(claude).toContain('command -v cleo >/dev/null 2>&1 || exit 0');
+    expect(claude).toContain(`${ASK_ENFORCE_HOOK_ID} --provider claude-code 2>/dev/null`);
+    expect(claude.endsWith('exit 0 # cleo-hook')).toBe(true);
+    expect(String(askEnforceHookObject('codex').command)).toMatch(/^\/bin\/sh -c '/);
   });
+});
 
-  it('keeps user Stop hooks, refreshes a stale CLEO one, and removes only its own', async () => {
-    const path = join(dir, 'hooks.json');
+describe('syncJsonStopDispatchHook (T13796)', () => {
+  const read = (p: string) => JSON.parse(readFileSync(p, 'utf-8'));
+
+  it('folds ask-enforce and the old session end into one Stop dispatcher, keeps user hooks, removes only its own', async () => {
+    const path = join(dir, 'codex-hooks.json');
     const user = { hooks: [{ type: 'command', command: './notify.sh' }] };
-    const stale = { hooks: [{ type: 'command', command: `${ASK_ENFORCE_HOOK_ID} # cleo-hook` }] };
-    writeFileSync(path, JSON.stringify({ hooks: { Stop: [user, stale] } }));
-    expect(await syncJsonAskEnforceHook(path, 'codex', true)).toBe('updated');
-    expect(read(path).hooks.Stop).toEqual([user, { hooks: [askEnforceHookObject('codex')] }]);
-    expect(await syncJsonAskEnforceHook(path, 'codex', false)).toBe('removed');
+    const legacy = {
+      matcher: '',
+      hooks: [{ type: 'command', command: LEGACY_SESSION_END_STOP_COMMAND }],
+    };
+    const ask = { hooks: [askEnforceHookObject('codex')] };
+    writeFileSync(path, JSON.stringify({ hooks: { Stop: [user, legacy, ask] } }));
+    expect(await syncJsonStopDispatchHook(path, 'codex', true)).toBe('installed');
+    expect(read(path).hooks.Stop).toEqual([user, { hooks: [stopDispatchHookObject('codex')] }]);
+    expect(await syncJsonStopDispatchHook(path, 'codex', true)).toBe('unchanged');
+    expect(await syncJsonStopDispatchHook(path, 'codex', false)).toBe('removed');
     expect(read(path).hooks.Stop).toEqual([user]);
-    expect(await syncJsonAskEnforceHook(join(dir, 'missing.json'), 'codex', false)).toBe(
+    expect(await syncJsonStopDispatchHook(join(dir, 'missing.json'), 'codex', false)).toBe(
       'unchanged',
     );
   });
 
-  it('runs a fail-open script: exits 0 and prints only a JSON answer', () => {
-    const claude = String(askEnforceHookObject('claude-code').command);
+  it('runs a fail-open script that forwards only a JSON answer', () => {
+    const claude = String(stopDispatchHookObject('claude-code').command);
     expect(claude).toContain('command -v cleo >/dev/null 2>&1 || exit 0');
-    expect(claude).toContain(`${ASK_ENFORCE_HOOK_ID} --provider claude-code 2>/dev/null`);
+    expect(claude).toContain(`${STOP_DISPATCH_HOOK_ID} --provider claude-code 2>/dev/null`);
     expect(claude.endsWith('exit 0 # cleo-hook')).toBe(true);
-    expect(String(askEnforceHookObject('codex').command)).toMatch(/^\/bin\/sh -c '/);
+    expect(String(stopDispatchHookObject('codex').command)).toMatch(/^\/bin\/sh -c '/);
   });
 });
 

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

@@ -56,7 +56,7 @@ import {
   opencodeHeavyCommandPluginSource,
   syncClaudeCodeHeavyCommandHook,
   syncCodexHeavyCommandHook,
-  syncJsonAskEnforceHook,
+  syncJsonStopDispatchHook,
   syncOpencodeHeavyCommandPlugin,
   trackedFileModified,
 } from './heavy-command-hook-install.js';
@@ -193,21 +193,20 @@ function errorText(err: unknown): string {
 
 /** Sync one provider; never throws. */
 /**
- * Install (or remove) CLEO's ask-enforce Stop hook (T13420) in the same JSON
- * config as the heavy-command hook, after that hook synced. It rides the
- * heavy-command delivery: removed when that hook's mode is `off` or when
- * `CLEO_ASK_ENFORCE=off`. Never fails the heavy-command outcome.
- * shortcut: no separate outcome or doctor row yet; add one when a config key replaces the env switch.
+ * 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.
  */
-async function syncAskEnforceHook(
+async function syncStopDispatch(
   provider: 'claude-code' | 'codex',
   target: string,
   mode: HeavyCommandHookMode,
-  env: Env,
 ): Promise<void> {
-  const install = mode !== 'off' && env.CLEO_ASK_ENFORCE?.trim().toLowerCase() !== 'off';
   try {
-    await syncJsonAskEnforceHook(target, provider, install);
+    await syncJsonStopDispatchHook(target, provider, provider === 'claude-code' || mode !== 'off');
   } catch {
     // Fail open: a config the Stop hook cannot be written to keeps the heavy-command result.
   }
@@ -232,7 +231,7 @@ async function syncProvider(
         : provider === 'codex'
           ? await syncCodexHeavyCommandHook(projectDir, mode)
           : syncOpencodeHeavyCommandPlugin(projectDir, mode);
-    if (provider !== 'opencode') await syncAskEnforceHook(provider, target, mode, env);
+    if (provider !== 'opencode') await syncStopDispatch(provider, target, mode);
     return { provider, status: result, target };
   } catch (err) {
     if (err instanceof HeavyHookSharedConfigError) {

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

@@ -44,7 +44,7 @@ import { homedir, tmpdir } from 'node:os';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { updateJsonConfigFile } from '@cleocode/caamp';
 import type { HeavyCommandHookMode } from '@cleocode/contracts';
-import { CLEO_HOOK_MARKER, hookMap, isPlainObject } from './hook-config.js';
+import { appendHookEntry, CLEO_HOOK_MARKER, hookMap, isPlainObject } from './hook-config.js';
 
 /** Identifies the heavy-command hook among CLEO's hook commands. */
 export const HEAVY_COMMAND_HOOK_ID = 'cleo hook heavy-command';
@@ -460,45 +460,102 @@ 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`. */
+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.
+ * 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.
+ *
+ * @param provider - `claude-code` or `codex` (Codex runs hooks through the login shell).
+ */
+export function stopDispatchHookObject(provider: 'claude-code' | 'codex'): Record<string, unknown> {
+  const script = `command -v cleo >/dev/null 2>&1 || exit 0; out="$(${STOP_DISPATCH_HOOK_ID} --provider ${provider} 2>/dev/null)"; case "$out" in "{"*) printf '%s\\n' "$out";; esac; exit 0`;
+  const line = provider === 'codex' ? `/bin/sh -c ${shellWord(script)}` : script;
+  return {
+    type: 'command',
+    command: `${line} ${CLEO_HOOK_MARKER}`,
+    timeout: STOP_DISPATCH_HOOK_TIMEOUT_SEC,
+  };
+}
+
+/** Whether one hook object is CLEO's Stop dispatcher. */
+export function isStopDispatchHookObject(hook: unknown): boolean {
+  return (
+    isPlainObject(hook) &&
+    typeof hook.command === 'string' &&
+    hook.command.includes(CLEO_HOOK_MARKER) &&
+    hook.command.includes(`${STOP_DISPATCH_HOOK_ID} `)
+  );
+}
+
+/** The separate Stop hooks the dispatcher folds in: ask-enforce and the old session end. */
+function isFoldedStopHook(hook: unknown): boolean {
+  return (
+    isAskEnforceHookObject(hook) ||
+    (isPlainObject(hook) && hook.command === LEGACY_SESSION_END_STOP_COMMAND)
+  );
+}
+
 /**
- * Add, refresh or (`install: false`) remove CLEO's ask-enforce Stop hook in a
- * JSON hook config (`hooks.Stop`), through CAAMP's locked atomic writer. Only
- * CLEO's own hook object is touched; a malformed file throws untouched.
+ * Leave exactly one CLEO Stop hook, the dispatcher (or, `install: false`,
+ * none), in a `hooks` map: the separate ask-enforce and legacy session-end
+ * Stop hooks are removed in place, user hooks stay.
+ *
+ * @param hooks - The config's `hooks` map (edited in place).
+ * @param provider - `claude-code` or `codex`.
+ * @param install - `false` removes the dispatcher too.
+ * @returns whether the map changed.
+ */
+export function applyStopDispatch(
+  hooks: Record<string, unknown>,
+  provider: 'claude-code' | 'codex',
+  install: boolean,
+): boolean {
+  const folded = placeHeavyHook(hooks, null, 'Stop', isFoldedStopHook).changed;
+  const desired = install ? stopDispatchHookObject(provider) : null;
+  const placed = placeHeavyHook(hooks, desired, 'Stop', isStopDispatchHookObject);
+  if (desired === null || placed.found) return folded || placed.changed;
+  appendHookEntry(hooks, 'Stop', { hooks: [desired] });
+  return true;
+}
+
+/**
+ * Sync CLEO's Stop dispatcher into a JSON hook config through CAAMP's locked
+ * atomic writer, folding the separate ask-enforce and session-end Stop hooks
+ * into it (T13796). A malformed file throws untouched.
  *
  * @param configPath - the config file (created when missing, unless removing).
  * @param provider - `claude-code` or `codex`.
- * @param install - `false` removes the hook.
+ * @param install - `false` removes the dispatcher.
  * @returns what changed.
  */
-export async function syncJsonAskEnforceHook(
+export async function syncJsonStopDispatchHook(
   configPath: string,
   provider: 'claude-code' | 'codex',
   install: boolean,
 ): Promise<HeavyHookSyncResult> {
-  const mine = (hook: unknown) => isAskEnforceHookObject(hook);
-  if (!install) {
-    if (!existsSync(configPath)) return 'unchanged';
-    const removed = await updateJsonConfigFile(configPath, (config) => {
-      if (config.hooks === undefined) return false;
-      return placeHeavyHook(hookMap(config), null, 'Stop', mine).changed;
-    });
-    return removed ? 'removed' : 'unchanged';
-  }
-  ensureParentDir(configPath);
+  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, askEnforceHookObject(provider), 'Stop', mine);
-    if (placed.found) {
-      if (placed.changed) result = 'updated';
-      return placed.changed;
-    }
-    const existing = hooks.Stop;
-    hooks.Stop = [
-      ...(Array.isArray(existing) ? existing : []),
-      { hooks: [askEnforceHookObject(provider)] },
-    ];
-    result = 'installed';
+    const stop = hooks.Stop;
+    const had =
+      Array.isArray(stop) &&
+      stop.some(
+        (g) => isPlainObject(g) && Array.isArray(g.hooks) && g.hooks.some(isStopDispatchHookObject),
+      );
+    if (!applyStopDispatch(hooks, provider, install)) return false;
+    result = !install ? 'removed' : had ? 'updated' : 'installed';
     return true;
   });
   return result;