cclaw-cli 0.39.1 → 0.40.0

package/README.md

@@ -127,9 +127,12 @@ Plus harness-specific shims:
 - `.claude/commands/cc*.md` + `.claude/hooks/hooks.json`
 - `.cursor/commands/cc*.md` + `.cursor/hooks.json` + `.cursor/rules/cclaw-workflow.mdc`
 - `.opencode/commands/cc*.md` + `.opencode/plugins/cclaw-plugin.mjs`
-- `.agents/skills/cclaw-cc*/SKILL.md` (Codex; activated via `/use cclaw-cc`
-  or description-based auto-matching — Codex no longer reads `.codex/commands/`
-  or `.codex/hooks.json`, and `cclaw sync` cleans those up if present)
+- `.agents/skills/cc*/SKILL.md` + `.codex/hooks.json` (Codex; skills are
+  activated via `/use cc` or description-based auto-matching. Hooks
+  require Codex CLI ≥ v0.114 and `[features] codex_hooks = true` in
+  `~/.codex/config.toml`; `cclaw init --codex` offers to patch that flag
+  for you. `.codex/commands/` and the legacy `.agents/skills/cclaw-cc*/`
+  folders are auto-cleaned on sync.)
 - `AGENTS.md` with a managed routing block (includes a Codex-specific note)
 
 `.cclaw/config.yaml` holds every tunable key (prompt guard strictness,
@@ -357,7 +360,7 @@ closes every real gap with a documented fallback — not a silent waiver.
 | Claude Code | full (named subagents) | `native` | full | `AskUserQuestion` | [`claude-playbook.md`](./src/content/harness-playbooks.ts) |
 | Cursor | generic Task dispatcher | `generic-dispatch` | full | `AskQuestion` | `cursor-playbook.md` |
 | OpenCode | plugin / in-session | `role-switch` | plugin | plain-text | `opencode-playbook.md` |
-| OpenAI Codex | in-session only | `role-switch` (evidenceRefs required) | none (no hooks API) | plain-text | `codex-playbook.md` |
+| OpenAI Codex | in-session only | `role-switch` (evidenceRefs required) | limited (Bash-only `PreToolUse`/`PostToolUse`; requires `codex_hooks` feature flag) | plain-text | `codex-playbook.md` |
 
 What the fallbacks mean:
 
@@ -380,16 +383,21 @@ What the fallbacks mean:
   harness declares it. Currently unused — v0.33 removed the old
   Codex-only auto-waiver path.
 
-> **Codex note (v0.39+).** Codex CLI deprecated custom prompts and the
-> `.codex/hooks.json` API, so cclaw installs Codex entry points as
-> native **skills** under `.agents/skills/cclaw-cc*/SKILL.md`. Invoke
-> them with `/use cclaw-cc`, `/use cclaw-cc-next`, `/use cclaw-cc-view`,
-> `/use cclaw-cc-ops`, `/use cclaw-cc-ideate`, or just say something
-> like *"run cc for payments refund fix"* — Codex auto-matches skills
-> from their description. Hook-driven checks (prompt-guard, stop-save,
-> post-tool context monitor) are substituted in the `cclaw-cc*` skill
-> bodies as explicit agent steps; run `cclaw doctor` to see what's
-> missing and how the playbook compensates.
+> **Codex note (v0.40+).** Codex CLI deprecated custom prompts in v0.89
+> (Jan 2026), but Codex ≥ v0.114 (Mar 2026) grew an experimental
+> lifecycle hooks API. cclaw installs Codex entry points as native
+> **skills** under `.agents/skills/cc*/SKILL.md` (invoke with `/use cc`,
+> `/use cc-next`, `/use cc-view`, `/use cc-ops`, `/use cc-ideate`, or
+> by typing `/cc …` in plain text — Codex auto-matches from the skill
+> description) **and** writes `.codex/hooks.json` so session-start
+> rehydration, stop-checkpoint, prompt-guard, workflow-guard, and
+> context-monitor fire automatically — as long as you enable the
+> `codex_hooks` feature flag in `~/.codex/config.toml`. `cclaw init
+> --codex` asks for consent before patching that file. Codex's
+> `PreToolUse`/`PostToolUse` are Bash-only; the stage skills compensate
+> for `Write`/`Edit`/`MCP` tool calls with explicit in-turn checks. Run
+> `cclaw doctor` to see the current state of hooks, the feature flag,
+> and any legacy layout to clean up.
 
 The full capability matrix lives in
 [`docs/harnesses.md`](./docs/harnesses.md). Per-harness playbooks are

package/dist/cli.js

@@ -15,6 +15,7 @@ import { CCLAW_VERSION, RUNTIME_ROOT } from "./constants.js";
 import { createDefaultConfig } from "./config.js";
 import { detectHarnesses } from "./init-detect.js";
 import { HARNESS_ADAPTERS } from "./harness-adapters.js";
+import { classifyCodexHooksFlag, codexConfigPath, patchCodexHooksFlag, readCodexConfig, writeCodexConfig } from "./codex-feature-flag.js";
 import { runEval } from "./eval/runner.js";
 import { createStderrProgressLogger } from "./eval/progress.js";
 import { writeBaselinesFromReport } from "./eval/baseline.js";
@@ -152,7 +153,7 @@ function buildInitSurfacePreview(harnesses) {
     for (const harness of harnesses) {
         const adapter = HARNESS_ADAPTERS[harness];
         if (adapter.shimKind === "skill") {
-            lines.push(`${adapter.commandDir}/cclaw-cc*/SKILL.md`);
+            lines.push(`${adapter.commandDir}/cc*/SKILL.md`);
         }
         else {
             lines.push(`${adapter.commandDir}/cc*.md`);
@@ -164,9 +165,12 @@ function buildInitSurfacePreview(harnesses) {
             lines.push(".cursor/hooks.json");
             lines.push(".cursor/rules/cclaw-workflow.mdc");
         }
-        // Codex has no hooks file — it reads skills from `.agents/skills/` only
-        // (v0.39.0+). Legacy `.codex/commands/*` and `.codex/hooks.json` are
-        // auto-cleaned on sync.
+        if (harness === "codex") {
+            // v0.40.0: .codex/hooks.json is managed again now that Codex CLI
+            // grew a real hooks API (v0.114+, behind the `codex_hooks`
+            // feature flag). Legacy `.codex/commands/*` is still auto-cleaned.
+            lines.push(".codex/hooks.json (requires `codex_hooks = true` in ~/.codex/config.toml)");
+        }
         if (harness === "opencode") {
             lines.push(".opencode/plugins/cclaw-plugin.mjs");
             lines.push("opencode.json(.c) plugin registration");
@@ -207,6 +211,85 @@ async function promptInitConfig(defaults, ctx) {
         rl.close();
     }
 }
+/**
+ * When Codex is one of the installed harnesses, check the Codex CLI
+ * config file for the `codex_hooks` feature flag. If it is missing or
+ * disabled, offer to patch it in with the user's explicit consent.
+ *
+ * The function is deliberately advisory: it never fails init — the worst
+ * case is that Codex runs without the hooks engine, which is exactly
+ * how v0.39.x already shipped. We always print a resolution hint so
+ * the user knows what to do next regardless of which branch was taken.
+ */
+async function maybeEnableCodexHooksFlag(harnesses, parsed, ctx) {
+    if (!harnesses || !harnesses.includes("codex"))
+        return;
+    const configPath = codexConfigPath();
+    let existing;
+    try {
+        existing = await readCodexConfig(configPath);
+    }
+    catch (err) {
+        ctx.stdout.write(`note: Could not read ${configPath} to check the codex_hooks flag: ` +
+            `${err instanceof Error ? err.message : String(err)}\n`);
+        return;
+    }
+    const state = classifyCodexHooksFlag(existing);
+    if (state === "enabled") {
+        return;
+    }
+    const humanState = state === "missing-file"
+        ? "Codex config file does not exist yet"
+        : state === "missing-section"
+            ? "no [features] section"
+            : state === "missing-key"
+                ? "no codex_hooks key"
+                : "codex_hooks is not enabled";
+    const instructions = `To enable Codex hooks manually later, ensure ${configPath} contains:\n` +
+        `  [features]\n  codex_hooks = true\n`;
+    if (parsed.interactive === false) {
+        ctx.stdout.write(`note: codex_hooks feature flag is not enabled (${humanState}).\n` +
+            `      cclaw wrote .codex/hooks.json, but Codex will ignore it until you enable the flag.\n` +
+            `      ${instructions}`);
+        return;
+    }
+    if (!isInitPromptAllowed(ctx)) {
+        ctx.stdout.write(`note: codex_hooks feature flag is not enabled (${humanState}).\n` +
+            `      cclaw wrote .codex/hooks.json, but Codex will ignore it until you enable the flag.\n` +
+            `      ${instructions}`);
+        return;
+    }
+    const rl = createInterface({
+        input: process.stdin,
+        output: ctx.stdout
+    });
+    try {
+        const answer = (await rl.question(`\nCodex CLI hooks are off (${humanState}).\n` +
+            `Enable [features] codex_hooks = true in ${configPath} now? [y/N]: `)).trim().toLowerCase();
+        const yes = answer === "y" || answer === "yes";
+        if (!yes) {
+            ctx.stdout.write(`Leaving ${configPath} untouched. ${instructions}`);
+            return;
+        }
+        const { updated, changed } = patchCodexHooksFlag(existing);
+        if (!changed) {
+            ctx.stdout.write(`codex_hooks is already enabled — no changes written.\n`);
+            return;
+        }
+        try {
+            await writeCodexConfig(configPath, updated);
+            ctx.stdout.write(`Enabled [features] codex_hooks = true in ${configPath}.\n`);
+        }
+        catch (err) {
+            ctx.stdout.write(`Could not write ${configPath}: ` +
+                `${err instanceof Error ? err.message : String(err)}\n` +
+                `${instructions}`);
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
 async function resolveInitInputs(parsed, ctx) {
     const detectedHarnesses = parsed.harnesses ? [] : await detectHarnesses(ctx.cwd);
     const autoHarnesses = parsed.harnesses
@@ -744,6 +827,7 @@ async function runCommand(parsed, ctx) {
         }
         const trackNote = effectiveTrack ? ` (track=${effectiveTrack})` : "";
         info(ctx, `Initialized .cclaw runtime and generated harness shims${trackNote}`);
+        await maybeEnableCodexHooksFlag(effectiveHarnesses, parsed, ctx);
         return 0;
     }
     if (command === "sync") {

package/dist/codex-feature-flag.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Manage the `codex_hooks` feature flag in `~/.codex/config.toml`.
+ *
+ * Codex CLI ≥ v0.114 (Mar 2026) exposes lifecycle hooks via
+ * `.codex/hooks.json`, but the hooks engine is inert unless the user has
+ * opted into it with:
+ *
+ * ```toml
+ * [features]
+ * codex_hooks = true
+ * ```
+ *
+ * in `$CODEX_HOME/config.toml` (default: `~/.codex/config.toml`).
+ * cclaw's `init --codex` prompts the user to flip this flag for them;
+ * this module owns the detection / mutation code so the prompt logic in
+ * `cli.ts` stays small and testable.
+ *
+ * The TOML mutations here are intentionally surgical — we never reparse
+ * or rewrite the whole document. A deliberately narrow regex based
+ * approach lets the function stay dependency-free and preserves the
+ * user's comments, whitespace, and custom key ordering.
+ */
+/**
+ * Absolute path of the Codex config file. Respects `$CODEX_HOME` when
+ * present (the only override Codex CLI documents); falls back to
+ * `~/.codex/config.toml` otherwise.
+ */
+export declare function codexConfigPath(env?: NodeJS.ProcessEnv): string;
+export type CodexHooksFlagState = "enabled" | "disabled" | "missing-key" | "missing-section" | "missing-file";
+/**
+ * Inspect a TOML document and decide which of the five canonical states
+ * it represents. Comments and blank lines are ignored. Only the first
+ * `[features]` section is considered — duplicates are technically invalid
+ * TOML and Codex rejects them, so cclaw does not try to be clever there.
+ */
+export declare function classifyCodexHooksFlag(toml: string | null): CodexHooksFlagState;
+/**
+ * Return a TOML document with `[features] codex_hooks = true` set.
+ * Preserves all other content verbatim:
+ *   - If the document lacks a `[features]` section, we append one at the
+ *     end of the file (separated by a blank line).
+ *   - If `[features]` exists without `codex_hooks`, we insert the key
+ *     immediately after the header.
+ *   - If `codex_hooks` exists with any non-`true` value, we rewrite
+ *     just that line.
+ *   - If the flag is already `true`, the input is returned unchanged.
+ */
+export declare function patchCodexHooksFlag(toml: string | null): {
+    updated: string;
+    changed: boolean;
+};
+/**
+ * Read the Codex config, return `null` when the file does not exist.
+ * All other read errors propagate so callers can surface a useful
+ * message instead of silently degrading.
+ */
+export declare function readCodexConfig(configPath: string): Promise<string | null>;
+export declare function writeCodexConfig(configPath: string, content: string): Promise<void>;

package/dist/codex-feature-flag.js

@@ -0,0 +1,193 @@
+/**
+ * Manage the `codex_hooks` feature flag in `~/.codex/config.toml`.
+ *
+ * Codex CLI ≥ v0.114 (Mar 2026) exposes lifecycle hooks via
+ * `.codex/hooks.json`, but the hooks engine is inert unless the user has
+ * opted into it with:
+ *
+ * ```toml
+ * [features]
+ * codex_hooks = true
+ * ```
+ *
+ * in `$CODEX_HOME/config.toml` (default: `~/.codex/config.toml`).
+ * cclaw's `init --codex` prompts the user to flip this flag for them;
+ * this module owns the detection / mutation code so the prompt logic in
+ * `cli.ts` stays small and testable.
+ *
+ * The TOML mutations here are intentionally surgical — we never reparse
+ * or rewrite the whole document. A deliberately narrow regex based
+ * approach lets the function stay dependency-free and preserves the
+ * user's comments, whitespace, and custom key ordering.
+ */
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+/**
+ * Absolute path of the Codex config file. Respects `$CODEX_HOME` when
+ * present (the only override Codex CLI documents); falls back to
+ * `~/.codex/config.toml` otherwise.
+ */
+export function codexConfigPath(env = process.env) {
+    const codexHome = env.CODEX_HOME && env.CODEX_HOME.trim().length > 0
+        ? env.CODEX_HOME
+        : path.join(os.homedir(), ".codex");
+    return path.join(codexHome, "config.toml");
+}
+/**
+ * Inspect a TOML document and decide which of the five canonical states
+ * it represents. Comments and blank lines are ignored. Only the first
+ * `[features]` section is considered — duplicates are technically invalid
+ * TOML and Codex rejects them, so cclaw does not try to be clever there.
+ */
+export function classifyCodexHooksFlag(toml) {
+    if (toml === null) {
+        return "missing-file";
+    }
+    const lines = toml.split(/\r?\n/);
+    let inFeaturesSection = false;
+    let sawFeaturesHeader = false;
+    for (const rawLine of lines) {
+        const stripped = stripTomlComment(rawLine).trim();
+        if (stripped.length === 0)
+            continue;
+        const headerMatch = /^\[\s*([A-Za-z0-9_.-]+)\s*\]$/u.exec(stripped);
+        if (headerMatch) {
+            const section = headerMatch[1];
+            if (section === "features") {
+                inFeaturesSection = true;
+                sawFeaturesHeader = true;
+            }
+            else {
+                inFeaturesSection = false;
+            }
+            continue;
+        }
+        if (inFeaturesSection) {
+            const keyMatch = /^codex_hooks\s*=\s*(.*)$/u.exec(stripped);
+            if (keyMatch) {
+                const value = keyMatch[1].trim().toLowerCase();
+                return value === "true" ? "enabled" : "disabled";
+            }
+        }
+    }
+    if (sawFeaturesHeader)
+        return "missing-key";
+    return "missing-section";
+}
+function stripTomlComment(line) {
+    // Naive but sufficient for our narrow use case: we only read cclaw's
+    // own writes back, and cclaw never emits `=` after a `#` inside a
+    // string literal in config.toml. If a user has complex string values
+    // with `#` inside them, worst case we trip `classifyCodexHooksFlag`
+    // and prompt them again — non-destructive.
+    const hashIndex = line.indexOf("#");
+    return hashIndex === -1 ? line : line.slice(0, hashIndex);
+}
+/**
+ * Return a TOML document with `[features] codex_hooks = true` set.
+ * Preserves all other content verbatim:
+ *   - If the document lacks a `[features]` section, we append one at the
+ *     end of the file (separated by a blank line).
+ *   - If `[features]` exists without `codex_hooks`, we insert the key
+ *     immediately after the header.
+ *   - If `codex_hooks` exists with any non-`true` value, we rewrite
+ *     just that line.
+ *   - If the flag is already `true`, the input is returned unchanged.
+ */
+export function patchCodexHooksFlag(toml) {
+    const initial = toml ?? "";
+    const state = classifyCodexHooksFlag(toml);
+    if (state === "enabled") {
+        return { updated: initial, changed: false };
+    }
+    if (state === "missing-file" || state === "missing-section") {
+        const prefix = initial.length === 0
+            ? ""
+            : initial.endsWith("\n") ? initial : `${initial}\n`;
+        const separator = initial.trim().length === 0 ? "" : "\n";
+        const block = `${separator}[features]\ncodex_hooks = true\n`;
+        return { updated: `${prefix}${block}`, changed: true };
+    }
+    if (state === "missing-key") {
+        const updated = insertKeyInFeaturesSection(initial);
+        return { updated, changed: true };
+    }
+    const updated = replaceCodexHooksLineInFeaturesSection(initial);
+    return { updated, changed: true };
+}
+function insertKeyInFeaturesSection(toml) {
+    // Walk into `[features]`, remember the index of the last key / non-blank
+    // line inside that section, and splice `codex_hooks = true` immediately
+    // after it. This keeps the inserted key adjacent to existing features,
+    // never stranded after a blank line or pushed down past a later section
+    // header. If `[features]` is empty, we insert right after its header.
+    const lines = toml.split(/\r?\n/);
+    let inFeaturesSection = false;
+    let featuresHeaderIndex = -1;
+    let lastFeatureKeyIndex = -1;
+    for (let index = 0; index < lines.length; index += 1) {
+        const rawLine = lines[index];
+        const stripped = stripTomlComment(rawLine).trim();
+        const headerMatch = /^\[\s*([A-Za-z0-9_.-]+)\s*\]$/u.exec(stripped);
+        if (headerMatch) {
+            if (inFeaturesSection)
+                break;
+            if (headerMatch[1] === "features") {
+                inFeaturesSection = true;
+                featuresHeaderIndex = index;
+                lastFeatureKeyIndex = index;
+            }
+            continue;
+        }
+        if (inFeaturesSection && stripped.length > 0) {
+            lastFeatureKeyIndex = index;
+        }
+    }
+    if (featuresHeaderIndex === -1) {
+        // caller should have short-circuited before getting here; defensive
+        return toml;
+    }
+    lines.splice(lastFeatureKeyIndex + 1, 0, "codex_hooks = true");
+    const joined = lines.join("\n");
+    return joined.endsWith("\n") ? joined : `${joined}\n`;
+}
+function replaceCodexHooksLineInFeaturesSection(toml) {
+    const lines = toml.split(/\r?\n/);
+    let inFeaturesSection = false;
+    for (let index = 0; index < lines.length; index += 1) {
+        const rawLine = lines[index];
+        const stripped = stripTomlComment(rawLine).trim();
+        const headerMatch = /^\[\s*([A-Za-z0-9_.-]+)\s*\]$/u.exec(stripped);
+        if (headerMatch) {
+            inFeaturesSection = headerMatch[1] === "features";
+            continue;
+        }
+        if (inFeaturesSection && /^codex_hooks\s*=/u.test(stripped)) {
+            const indent = /^\s*/u.exec(rawLine)?.[0] ?? "";
+            lines[index] = `${indent}codex_hooks = true`;
+        }
+    }
+    const joined = lines.join("\n");
+    return joined.endsWith("\n") ? joined : `${joined}\n`;
+}
+/**
+ * Read the Codex config, return `null` when the file does not exist.
+ * All other read errors propagate so callers can surface a useful
+ * message instead of silently degrading.
+ */
+export async function readCodexConfig(configPath) {
+    try {
+        return await fs.readFile(configPath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return null;
+        }
+        throw err;
+    }
+}
+export async function writeCodexConfig(configPath, content) {
+    await fs.mkdir(path.dirname(configPath), { recursive: true });
+    await fs.writeFile(configPath, content, "utf8");
+}

package/dist/constants.d.ts

@@ -14,7 +14,7 @@ export declare const EVALS_ROOT = ".cclaw/evals";
 export declare const EVALS_CONFIG_PATH = ".cclaw/evals/config.yaml";
 export declare const EVALS_DIRS: readonly [".cclaw/evals", ".cclaw/evals/corpus", ".cclaw/evals/rubrics", ".cclaw/evals/baselines", ".cclaw/evals/reports"];
 export declare const REQUIRED_DIRS: readonly [".cclaw", ".cclaw/commands", ".cclaw/skills", ".cclaw/contexts", ".cclaw/templates", ".cclaw/artifacts", ".cclaw/worktrees", ".cclaw/state", ".cclaw/runs", ".cclaw/rules", ".cclaw/adapters", ".cclaw/agents", ".cclaw/hooks", ".cclaw/custom-skills", ".cclaw/evals", ".cclaw/evals/corpus", ".cclaw/evals/rubrics", ".cclaw/evals/baselines", ".cclaw/evals/reports"];
-export declare const REQUIRED_GITIGNORE_PATTERNS: readonly ["# cclaw generated artifacts", ".cclaw/", "# cclaw evals: user-owned, track in git", "!.cclaw/evals/", "!.cclaw/evals/config.yaml", "!.cclaw/evals/corpus/", "!.cclaw/evals/corpus/**", "!.cclaw/evals/rubrics/", "!.cclaw/evals/rubrics/**", "!.cclaw/evals/baselines/", "!.cclaw/evals/baselines/**", ".claude/commands/cc-*.md", ".claude/commands/cc.md", ".cursor/commands/cc-*.md", ".cursor/commands/cc.md", ".opencode/commands/cc-*.md", ".opencode/commands/cc.md", ".agents/skills/cclaw-cc/SKILL.md", ".agents/skills/cclaw-cc-*/SKILL.md", ".claude/hooks/hooks.json", ".cursor/hooks.json", ".opencode/plugins/cclaw-plugin.mjs", ".cursor/rules/cclaw-workflow.mdc"];
+export declare const REQUIRED_GITIGNORE_PATTERNS: readonly ["# cclaw generated artifacts", ".cclaw/", "# cclaw evals: user-owned, track in git", "!.cclaw/evals/", "!.cclaw/evals/config.yaml", "!.cclaw/evals/corpus/", "!.cclaw/evals/corpus/**", "!.cclaw/evals/rubrics/", "!.cclaw/evals/rubrics/**", "!.cclaw/evals/baselines/", "!.cclaw/evals/baselines/**", ".claude/commands/cc-*.md", ".claude/commands/cc.md", ".cursor/commands/cc-*.md", ".cursor/commands/cc.md", ".opencode/commands/cc-*.md", ".opencode/commands/cc.md", ".agents/skills/cc/SKILL.md", ".agents/skills/cc-*/SKILL.md", ".claude/hooks/hooks.json", ".cursor/hooks.json", ".codex/hooks.json", ".opencode/plugins/cclaw-plugin.mjs", ".cursor/rules/cclaw-workflow.mdc"];
 export declare const COMMAND_FILE_ORDER: FlowStage[];
 export declare const UTILITY_COMMANDS: readonly ["learn", "next", "ideate", "view", "status", "tree", "diff", "ops", "feature", "tdd-log", "retro", "compound", "archive", "rewind"];
 export declare const SUBAGENT_SKILL_FOLDERS: readonly ["subagent-dev", "parallel-dispatch"];

package/dist/constants.js

@@ -91,12 +91,15 @@ export const REQUIRED_GITIGNORE_PATTERNS = [
     ".cursor/commands/cc.md",
     ".opencode/commands/cc-*.md",
     ".opencode/commands/cc.md",
-    // Codex uses skill-kind shims under `.agents/skills/cclaw-cc*/` since
-    // v0.39.0; legacy `.codex/commands/*` is auto-cleaned on sync.
-    ".agents/skills/cclaw-cc/SKILL.md",
-    ".agents/skills/cclaw-cc-*/SKILL.md",
+    // Codex uses skill-kind shims under `.agents/skills/cc*/` since
+    // v0.40.0 (renamed from the `cclaw-cc*` layout in v0.39.0/v0.39.1).
+    // `cclaw sync` and `cclaw uninstall` both auto-remove the legacy
+    // `cclaw-cc*` directories.
+    ".agents/skills/cc/SKILL.md",
+    ".agents/skills/cc-*/SKILL.md",
     ".claude/hooks/hooks.json",
     ".cursor/hooks.json",
+    ".codex/hooks.json",
     ".opencode/plugins/cclaw-plugin.mjs",
     ".cursor/rules/cclaw-workflow.mdc"
 ];

package/dist/content/harness-playbooks.js

@@ -192,28 +192,38 @@ has either a \`completed\` row with evidenceRefs (role-switch) or a
 const CODEX_PLAYBOOK = `---
 harness: codex
 fallback: role-switch
-description: "OpenAI Codex has no subagent dispatch and no hooks. cclaw ships entry points as skills under .agents/skills/; mandatory delegations fall back to role-switch with evidenceRefs."
+description: "OpenAI Codex exposes lifecycle hooks (v0.114+, gated by the codex_hooks feature flag) but no subagent dispatch and no custom slash commands. cclaw ships entry points as skills under .agents/skills/cc*/ and wires .codex/hooks.json; mandatory delegations fall back to role-switch with evidenceRefs."
 ---
 
 # OpenAI Codex — Parity Playbook
 
-Codex CLI exposes **neither a custom slash-command system nor a hooks
-API**. cclaw v0.39.0 acknowledged this and rewired the codex harness:
+Codex CLI has a different shape from Claude/Cursor:
 
 - **Entry points are skills.** \`/cc\`, \`/cc-next\`, \`/cc-ideate\`,
   \`/cc-view\`, \`/cc-ops\` are generated as skills at
-  \`.agents/skills/cclaw-cc/SKILL.md\` (and \`cclaw-cc-next/\`, etc.). They
-  activate via Codex's native \`/use <skillName>\` command or
-  automatically when the user's prompt mentions any of the
-  \`/cc\`-style tokens (skill descriptions include them verbatim).
-- **No hooks.** Everything that Claude/Cursor get from
-  \`SessionStart\` / \`PreToolUse\` / \`PostToolUse\` / \`Stop\` /
-  \`PreCompact\` must run as explicit agent steps. The session rehydration,
-  prompt-guard, workflow-guard, context-monitor, and stop-checkpoint
-  behaviors are documented in \`.cclaw/skills/using-cclaw/SKILL.md\`.
-- **Legacy paths are dead.** \`.codex/commands/*\` and \`.codex/hooks.json\`
-  are removed on every \`cclaw sync\`. Do not restore them by hand —
-  Codex CLI never read either path.
+  \`.agents/skills/cc/SKILL.md\` (and \`cc-next/\`, \`cc-view/\`,
+  \`cc-ideate/\`, \`cc-ops/\`). They activate via Codex's native
+  \`/use <skillName>\` command or automatically when the user's prompt
+  mentions any of the \`/cc\`-style tokens (skill descriptions include
+  them verbatim). Codex CLI removed custom prompts in v0.89 (Jan 2026);
+  there is no way to register a true custom slash command.
+- **Lifecycle hooks.** Codex CLI ≥ v0.114 (Mar 2026) exposes lifecycle
+  hooks at \`.codex/hooks.json\`, gated behind the experimental
+  \`[features] codex_hooks = true\` flag in \`~/.codex/config.toml\`.
+  cclaw writes \`.codex/hooks.json\` on sync; if the flag is off, the
+  file is simply inert and \`cclaw doctor\` emits a warning. \`cclaw init\`
+  offers to patch the flag with explicit user consent.
+- **Tool interception is Bash-only.** Codex's \`PreToolUse\` and
+  \`PostToolUse\` events only fire for the \`Bash\` tool. \`Write\`,
+  \`Edit\`, \`WebSearch\`, and MCP tool calls are **not** gated by hooks.
+  cclaw partially compensates by also wiring \`UserPromptSubmit\` to
+  \`prompt-guard.sh\` so the stage routing check fires before the turn
+  executes, but workflow-guard (TDD red-first, artifact presence) only
+  fires on Bash turns. See the hook coverage matrix below.
+- **Legacy paths.** \`.codex/commands/*\` was never consumed by Codex and
+  is removed on every \`cclaw sync\`. The v0.39.x \`.agents/skills/cclaw-cc*/\`
+  layout is replaced by \`.agents/skills/cc*/\` and the old folders are
+  auto-removed on sync. Do not restore either by hand.
 
 ## Fallback: role-switch
 
@@ -243,33 +253,57 @@ disabled in v0.33 and remains off.
 
 ## Invocation cheatsheet
 
-- \`/use cclaw-cc\` — open the \`/cc\` skill and pick a track.
-- \`/use cclaw-cc-next\` — advance the flow one stage.
-- \`/use cclaw-cc-ops\` — compound / archive / rewind.
+- \`/use cc\` — open the \`/cc\` skill and pick a track.
+- \`/use cc-next\` — advance the flow one stage.
+- \`/use cc-ops\` — compound / archive / rewind.
 - Typing \`/cc …\` or \`/cc-next …\` in plain text also works: Codex
   matches the skill descriptions (which spell out these tokens) and
   auto-loads the right skill body.
 - Use Codex's built-in \`/skill\` UI to enable or disable
   cclaw skills per session.
 
-## Hook substitution matrix
+## Feature flag — how to enable hooks
 
-| Hook intent | Codex substitute |
-|-------------|------------------|
-| SessionStart rehydration | On first turn, the agent reads \`.cclaw/state/flow-state.json\` and \`.cclaw/knowledge.jsonl\` explicitly before acting. |
-| PreToolUse prompt-guard | The \`/cc\` skill body enforces task classification before writes. |
-| PreToolUse workflow-guard | The active stage skill enforces TDD / artifact gates before writes. |
-| PostToolUse context-monitor | End-of-turn budget check lives in \`.cclaw/references/protocols/ethos.md\`. |
-| Stop checkpoint | Stage-completion protocol updates \`.cclaw/state/flow-state.json\` in the same turn. |
-| PreCompact digest | Manual \`/cc-view status\` before \`/compact\`; the user triggers this. |
+Codex CLI ignores \`.codex/hooks.json\` unless \`codex_hooks = true\`
+appears under \`[features]\` in \`~/.codex/config.toml\`:
+
+\`\`\`toml
+[features]
+codex_hooks = true
+\`\`\`
+
+\`cclaw init --codex\` prompts to write this automatically (one-line
+diff, preserving the rest of \`config.toml\` untouched). Decline the
+prompt to leave the file alone; the skill-level \`/use cc\` entry points
+continue to work regardless.
+
+## Hook coverage matrix
+
+| Hook intent | Codex mapping | Coverage |
+|-------------|---------------|----------|
+| SessionStart rehydration | \`SessionStart\` matcher \`startup|resume\` → \`session-start.sh\` | Full. |
+| PreToolUse prompt-guard | \`PreToolUse\` matcher \`Bash\` + \`UserPromptSubmit\` → \`prompt-guard.sh\` | Bash tool calls are gated inline; \`UserPromptSubmit\` catches prompts before any tool fires, so non-Bash writes (\`Write\`/\`Edit\`) are still prompt-guarded at the turn boundary. |
+| PreToolUse workflow-guard | \`PreToolUse\` matcher \`Bash\` → \`workflow-guard.sh\` | Bash-only. For \`Write\`/\`Edit\` calls the agent performs the TDD-order / artifact check in-turn (see the stage skill). |
+| PostToolUse context-monitor | \`PostToolUse\` matcher \`Bash\` → \`context-monitor.sh\` | Bash-only. Other tool calls get context-monitored at end-of-turn via \`.cclaw/references/protocols/ethos.md\`. |
+| Stop checkpoint | \`Stop\` → \`stop-checkpoint.sh\` | Full. |
+| PreCompact digest | Not supported — Codex has no \`PreCompact\` event. | Covered by \`/cc-ops retro\` and the user running \`/cc-view status\` before Codex's \`/compact\` command. |
 
 ## Verification
 
 \`cclaw doctor\` on a codex-enabled install checks:
 
-- \`shim:codex:cclaw-cc:present\` and \`frontmatter\` (plus the four
-  utility skills).
-- No legacy \`.codex/commands/\` or \`.codex/hooks.json\` lingering.
+- \`shim:codex:cc:present\` and \`frontmatter\` (plus the four utility
+  skills \`cc-next\`, \`cc-view\`, \`cc-ops\`, \`cc-ideate\`).
+- \`hook:schema:codex\` validates \`.codex/hooks.json\` shape.
+- \`hook:wiring:codex\` verifies the generated hooks reference every
+  runtime script cclaw needs (session-start, prompt-guard, workflow-guard,
+  context-monitor, stop-checkpoint).
+- \`warning:codex:feature_flag\` is emitted as a warning (not an error)
+  when \`~/.codex/config.toml\` is missing the \`codex_hooks\` feature
+  flag — hooks silently do nothing in that state.
+- \`warning:codex:legacy_commands_dir\` and
+  \`warning:codex:legacy_cclaw_cc_skills\` catch leftovers from older
+  cclaw versions.
 - Every mandatory agent for the active stage has a \`completed\` row
   with \`fulfillmentMode: "role-switch"\` and at least one \`evidenceRef\`.
 `;

package/dist/content/harnesses-doc.js

@@ -112,7 +112,7 @@ Harness-specific additions:
 - \`claude\`: \`.claude/commands/cc*.md\`, \`.claude/hooks/hooks.json\`
 - \`cursor\`: \`.cursor/commands/cc*.md\`, \`.cursor/hooks.json\`, \`.cursor/rules/cclaw-workflow.mdc\`
 - \`opencode\`: \`.opencode/commands/cc*.md\`, \`.opencode/plugins/cclaw-plugin.mjs\`, opencode plugin registration
-- \`codex\`: \`.agents/skills/cclaw-cc/SKILL.md\`, \`.agents/skills/cclaw-cc-next/SKILL.md\`, \`.agents/skills/cclaw-cc-ideate/SKILL.md\`, \`.agents/skills/cclaw-cc-view/SKILL.md\`, \`.agents/skills/cclaw-cc-ops/SKILL.md\` (Codex CLI reads \`.agents/skills/\` on startup; \`.codex/*\` was never consumed by the CLI and is auto-cleaned on sync)
+- \`codex\`: \`.agents/skills/cc/SKILL.md\`, \`.agents/skills/cc-next/SKILL.md\`, \`.agents/skills/cc-ideate/SKILL.md\`, \`.agents/skills/cc-view/SKILL.md\`, \`.agents/skills/cc-ops/SKILL.md\`, \`.codex/hooks.json\` (Codex CLI reads \`.agents/skills/\` for custom skills and consumes \`.codex/hooks.json\` on v0.114+ when \`[features] codex_hooks = true\` is set in \`~/.codex/config.toml\`. \`.codex/commands/\` and the legacy \`.agents/skills/cclaw-cc*/\` layout from v0.39.x are auto-cleaned on sync.)
 
 ## Runtime observability
 

package/dist/content/hook-events.js

@@ -32,10 +32,16 @@ export const HOOK_EVENTS_BY_HARNESS = {
         precompact_digest: "plugin session.cleared/session.resumed hooks"
     },
     codex: {
-    // Codex CLI has no hooks primitive. cclaw substitutes via skills
-    // under `.agents/skills/cclaw-cc*/SKILL.md` plus explicit in-turn
-    // agent steps (see codex playbook). All semantic events are
-    // intentionally unmapped here so `harness-gaps.json` exposes them
-    // honestly.
+        // Codex CLI v0.114+ exposes lifecycle hooks via `.codex/hooks.json`,
+        // gated by `[features] codex_hooks = true` in `~/.codex/config.toml`.
+        // SessionStart, Stop, and UserPromptSubmit fire for every turn;
+        // PreToolUse/PostToolUse are **Bash-only** (Write/Edit/WebSearch/MCP
+        // calls do not trigger them). `precompact_digest` is unmapped —
+        // Codex has no PreCompact event; cclaw covers it via `/cc-ops retro`.
+        session_rehydrate: "SessionStart matcher startup|resume",
+        pre_tool_prompt_guard: "PreToolUse matcher Bash -> prompt-guard.sh (plus UserPromptSubmit for non-Bash prompts)",
+        pre_tool_workflow_guard: "PreToolUse matcher Bash -> workflow-guard.sh (Bash-only)",
+        post_tool_context_monitor: "PostToolUse matcher Bash -> context-monitor.sh (Bash-only)",
+        stop_checkpoint: "Stop -> stop-checkpoint.sh"
     }
 };

package/dist/content/hooks.js

@@ -1209,14 +1209,14 @@ Cclaw generates real hook integrations for every harness that exposes a
 hook primitive:
 - **Claude/Cursor:** lifecycle rehydration + PreToolUse/PostToolUse + Stop
 - **OpenCode:** session lifecycle + system transform rehydration + bootstrap parity (digest/warnings/knowledge snapshot)
-- **Codex:** *no hooks API exists in Codex CLI* — substitution happens via skills (\`.agents/skills/cclaw-cc*/SKILL.md\`) and explicit in-turn agent steps. See \`.cclaw/references/harnesses/codex-playbook.md\`.
+- **Codex:** Codex CLI ≥ v0.114 exposes lifecycle hooks at \`.codex/hooks.json\`, gated behind \`[features] codex_hooks = true\` in \`~/.codex/config.toml\`. \`PreToolUse\`/\`PostToolUse\` intercept **only the \`Bash\` tool** in Codex; \`Write\`/\`Edit\`/\`WebSearch\`/MCP calls are substituted via the \`/cc\` skill bodies under \`.agents/skills/cc*/SKILL.md\` and explicit in-turn agent steps. See \`.cclaw/references/harnesses/codex-playbook.md\` for the coverage matrix.
 
 | Harness | Hook file | Events |
 |---------|-----------|--------|
 | Claude Code | \`.claude/hooks/hooks.json\` | SessionStart(startup/resume/clear/compact), PreToolUse, PostToolUse, Stop |
 | Cursor | \`.cursor/hooks.json\` | sessionStart/sessionResume/sessionClear/sessionCompact, preToolUse, postToolUse, stop |
 | OpenCode | \`${RUNTIME_ROOT}/hooks/opencode-plugin.mjs\` | session.created/updated/resumed/cleared/compacted/idle, tool.execute.before/after, system transform |
-| Codex | *none* | skill-description matching + in-turn agent steps (no hooks API) |
+| Codex | \`.codex/hooks.json\` | SessionStart(startup/resume), UserPromptSubmit, PreToolUse(Bash), PostToolUse(Bash), Stop (feature-gated by \`codex_hooks = true\`) |
 
 Hook state files:
 - \`${RUNTIME_ROOT}/state/stage-activity.jsonl\`

package/dist/content/observe.d.ts

@@ -23,4 +23,23 @@ export declare function summarizeObservationsScript(): string;
  */
 export declare function claudeHooksJsonWithObservation(): string;
 export declare function cursorHooksJsonWithObservation(): string;
+/**
+ * Codex CLI ≥ v0.114 hooks. Differences vs. the Claude shape:
+ *
+ * - `SessionStart` matcher is limited to `startup|resume` — Codex does
+ *   not emit `clear` or `compact` lifecycle phases.
+ * - `PreToolUse` / `PostToolUse` fire **only for the `Bash` tool**
+ *   (documented Codex limitation, v0.114/v0.115). We use the `Bash`
+ *   matcher verbatim so Codex doesn't silently swallow our commands.
+ * - `UserPromptSubmit` is supported and is the closest analogue to
+ *   Cursor's `preToolUse` for non-Bash tooling — we run prompt-guard
+ *   there so workflow/prompt checks still fire when the tool being
+ *   used is `Write` or `Edit` rather than `Bash`.
+ * - There is no `PreCompact` event in Codex CLI — pre-compact
+ *   semantics are carried by the agent itself inside `/cc-ops retro`.
+ *
+ * The entire file is inert unless the user opts into
+ * `[features] codex_hooks = true` in `~/.codex/config.toml`; cclaw
+ * doctor and the init prompt handle that flag.
+ */
 export declare function codexHooksJsonWithObservation(): string;

package/dist/content/observe.js

@@ -1792,20 +1792,44 @@ export function cursorHooksJsonWithObservation() {
         }
     }, null, 2);
 }
+/**
+ * Codex CLI ≥ v0.114 hooks. Differences vs. the Claude shape:
+ *
+ * - `SessionStart` matcher is limited to `startup|resume` — Codex does
+ *   not emit `clear` or `compact` lifecycle phases.
+ * - `PreToolUse` / `PostToolUse` fire **only for the `Bash` tool**
+ *   (documented Codex limitation, v0.114/v0.115). We use the `Bash`
+ *   matcher verbatim so Codex doesn't silently swallow our commands.
+ * - `UserPromptSubmit` is supported and is the closest analogue to
+ *   Cursor's `preToolUse` for non-Bash tooling — we run prompt-guard
+ *   there so workflow/prompt checks still fire when the tool being
+ *   used is `Write` or `Edit` rather than `Bash`.
+ * - There is no `PreCompact` event in Codex CLI — pre-compact
+ *   semantics are carried by the agent itself inside `/cc-ops retro`.
+ *
+ * The entire file is inert unless the user opts into
+ * `[features] codex_hooks = true` in `~/.codex/config.toml`; cclaw
+ * doctor and the init prompt handle that flag.
+ */
 export function codexHooksJsonWithObservation() {
     return JSON.stringify({
         cclawHookSchemaVersion: 1,
         hooks: {
             SessionStart: [{
-                    matcher: "startup|resume|clear|compact",
+                    matcher: "startup|resume",
                     hooks: [{
                             type: "command",
-                            command: `bash ${RUNTIME_ROOT}/hooks/session-start.sh`,
-                            statusMessage: "Loading cclaw flow state"
+                            command: `bash ${RUNTIME_ROOT}/hooks/session-start.sh`
+                        }]
+                }],
+            UserPromptSubmit: [{
+                    hooks: [{
+                            type: "command",
+                            command: `bash ${RUNTIME_ROOT}/hooks/prompt-guard.sh`
                         }]
                 }],
             PreToolUse: [{
-                    matcher: "*",
+                    matcher: "Bash",
                     hooks: [{
                             type: "command",
                             command: `bash ${RUNTIME_ROOT}/hooks/prompt-guard.sh`
@@ -1815,7 +1839,7 @@ export function codexHooksJsonWithObservation() {
                         }]
                 }],
             PostToolUse: [{
-                    matcher: "*",
+                    matcher: "Bash",
                     hooks: [{
                             type: "command",
                             command: `bash ${RUNTIME_ROOT}/hooks/context-monitor.sh`
@@ -1827,14 +1851,6 @@ export function codexHooksJsonWithObservation() {
                             command: `bash ${RUNTIME_ROOT}/hooks/stop-checkpoint.sh`,
                             timeout: 10
                         }]
-                }],
-            PreCompact: [{
-                    matcher: "manual|auto",
-                    hooks: [{
-                            type: "command",
-                            command: `bash ${RUNTIME_ROOT}/hooks/pre-compact.sh`,
-                            timeout: 10
-                        }]
                 }]
         }
     }, null, 2);

package/dist/doctor.js

@@ -20,6 +20,7 @@ import { reconcileAndWriteCurrentStageGateCatalog, verifyCompletedStagesGateClos
 import { parseTddCycleLog, validateTddCycleOrder } from "./tdd-cycle.js";
 import { stageSkillFolder } from "./content/skills.js";
 import { doctorCheckMetadata } from "./doctor-registry.js";
+import { classifyCodexHooksFlag, codexConfigPath, readCodexConfig } from "./codex-feature-flag.js";
 import { LANGUAGE_RULE_PACK_DIR, LANGUAGE_RULE_PACK_FILES, LEGACY_LANGUAGE_RULE_PACK_FOLDERS, UTILITY_SKILL_FOLDERS } from "./content/utility-skills.js";
 import { CONTEXT_MODES, DEFAULT_CONTEXT_MODE } from "./content/contexts.js";
 import { DOCTOR_REFERENCE_MARKDOWN } from "./content/doctor-references.js";
@@ -635,16 +636,18 @@ export async function doctorChecks(projectRoot, options = {}) {
             });
         }
     }
-    // Hook JSON files per harness. Codex is absent because Codex CLI has no
-    // hooks primitive — cclaw stopped writing `.codex/hooks.json` in v0.39.0.
-    // OpenCode ships hooks through its plugin system (covered below).
+    // Hook JSON files per harness. OpenCode ships hooks through its plugin
+    // system (covered below). Codex joined the managed list in v0.40.0 — Codex
+    // CLI ≥ v0.114 consumes `.codex/hooks.json` behind the `codex_hooks`
+    // feature flag.
     const hookPaths = {
         claude: ".claude/hooks/hooks.json",
-        cursor: ".cursor/hooks.json"
+        cursor: ".cursor/hooks.json",
+        codex: ".codex/hooks.json"
     };
     for (const harness of configuredHarnesses) {
         const hp = hookPaths[harness];
-        if (!hp && harness !== "opencode" && harness !== "codex") {
+        if (!hp && harness !== "opencode") {
             checks.push({
                 name: `hook:json:${harness}`,
                 ok: false,
@@ -661,7 +664,7 @@ export async function doctorChecks(projectRoot, options = {}) {
                 ok: hookOk,
                 details: fullPath
             });
-            if (harness === "claude" || harness === "cursor") {
+            if (harness === "claude" || harness === "cursor" || harness === "codex") {
                 const schema = validateHookDocument(harness, parsed);
                 checks.push({
                     name: `hook:schema:${harness}`,
@@ -762,10 +765,11 @@ export async function doctorChecks(projectRoot, options = {}) {
         });
     }
     if (configuredHarnesses.includes("codex")) {
-        // Codex CLI has no hooks primitive and no slash-command discovery
-        // (`.codex/commands/*` was never read). cclaw ships codex shims as
-        // skills under `.agents/skills/cclaw-cc*/SKILL.md`. Every required
-        // skill must exist with the expected frontmatter `name`.
+        // Codex CLI has no custom slash-command discovery (`.codex/commands/*`
+        // was never read, even historically). cclaw ships codex entry points
+        // as skills under `.agents/skills/cc*/SKILL.md`; Codex v0.114+ also
+        // supports lifecycle hooks at `.codex/hooks.json` (gated by the
+        // `codex_hooks` feature flag in `~/.codex/config.toml`).
         const skillsRoot = path.join(projectRoot, ".agents/skills");
         for (const skillName of harnessShimSkillNames()) {
             const skillPath = path.join(skillsRoot, skillName, "SKILL.md");
@@ -791,26 +795,87 @@ export async function doctorChecks(projectRoot, options = {}) {
                         : `${skillPath} absent; cannot validate frontmatter`
             });
         }
-        // Warn if legacy `.codex/commands/*` or `.codex/hooks.json` is still
-        // around — cclaw syncs should have removed these, but a botched
-        // upgrade or a manual restore could leave them dangling.
+        // Hook wiring: the generated `.codex/hooks.json` must reference every
+        // runtime script cclaw needs. Separate from the schema check above;
+        // schema covers structure, this check covers semantic wiring.
+        const codexHooksFile = path.join(projectRoot, ".codex/hooks.json");
+        const codexDoc = await readHookDocument(codexHooksFile);
+        const codexHooks = toObject(codexDoc?.hooks) ?? {};
+        const codexSessionCmds = collectHookCommands(codexHooks.SessionStart);
+        const codexPreCmds = collectHookCommands(codexHooks.PreToolUse);
+        const codexPostCmds = collectHookCommands(codexHooks.PostToolUse);
+        const codexStopCmds = collectHookCommands(codexHooks.Stop);
+        const codexWiringOk = codexSessionCmds.some((cmd) => cmd.includes("session-start.sh")) &&
+            codexPreCmds.some((cmd) => cmd.includes("prompt-guard.sh")) &&
+            codexPreCmds.some((cmd) => cmd.includes("workflow-guard.sh")) &&
+            codexPostCmds.some((cmd) => cmd.includes("context-monitor.sh")) &&
+            codexStopCmds.some((cmd) => cmd.includes("stop-checkpoint.sh"));
+        checks.push({
+            name: "hook:wiring:codex",
+            ok: codexWiringOk,
+            details: `${codexHooksFile} must wire session-start/prompt-guard/workflow-guard/context-monitor/stop-checkpoint (PreToolUse/PostToolUse run Bash-only in Codex v0.114+)`
+        });
+        // Feature flag warning: Codex ignores `.codex/hooks.json` unless the
+        // user has `[features] codex_hooks = true` in `~/.codex/config.toml`.
+        // Advisory warning — not a hard failure, because the skills still
+        // work without the flag.
+        const codexConfig = codexConfigPath();
+        let featureFlagNote = "";
+        try {
+            const content = await readCodexConfig(codexConfig);
+            const state = classifyCodexHooksFlag(content);
+            featureFlagNote =
+                state === "enabled"
+                    ? `codex_hooks feature flag is enabled in ${codexConfig}`
+                    : state === "missing-file"
+                        ? `warning: ${codexConfig} does not exist; .codex/hooks.json will be ignored until you create it with \`[features]\\ncodex_hooks = true\\n\`.`
+                        : state === "missing-section"
+                            ? `warning: ${codexConfig} has no [features] section; add \`[features]\\ncodex_hooks = true\\n\` to enable cclaw hooks.`
+                            : state === "missing-key"
+                                ? `warning: ${codexConfig} is missing the codex_hooks key under [features]. Add \`codex_hooks = true\` to enable cclaw hooks.`
+                                : `warning: ${codexConfig} sets codex_hooks to a non-true value; set \`codex_hooks = true\` under [features] to enable cclaw hooks.`;
+        }
+        catch (err) {
+            featureFlagNote = `warning: could not read ${codexConfig}: ${err instanceof Error ? err.message : String(err)}`;
+        }
+        checks.push({
+            name: "warning:codex:feature_flag",
+            ok: true,
+            details: featureFlagNote
+        });
+        // Legacy `.codex/commands/*` must not linger from older cclaw installs.
+        // (The `.codex/hooks.json` path is now managed and is validated above,
+        // so there is no longer a legacy_hooks_json warning.)
         const legacyCommandsDir = path.join(projectRoot, ".codex/commands");
         const legacyCommandsPresent = await exists(legacyCommandsDir);
         checks.push({
             name: "warning:codex:legacy_commands_dir",
             ok: true,
             details: legacyCommandsPresent
-                ? `warning: ${legacyCommandsDir} still present; Codex never read this directory — run \`cclaw sync\` to remove it.`
+                ? `warning: ${legacyCommandsDir} still present; Codex never consumed this directory — run \`cclaw sync\` to remove it.`
                 : `no legacy ${legacyCommandsDir} detected`
         });
-        const legacyHooks = path.join(projectRoot, ".codex/hooks.json");
-        const legacyHooksPresent = await exists(legacyHooks);
+        // Legacy v0.39.x skill layout under `.agents/skills/cclaw-cc*/`
+        // must have been removed — cclaw sync deletes these automatically,
+        // but flag leftovers so users notice an upgrade issue.
+        const legacyCodexSkills = [];
+        try {
+            const entries = await fs.readdir(skillsRoot);
+            for (const entry of entries) {
+                if (/^cclaw-cc(?:-.*)?$/u.test(entry)) {
+                    legacyCodexSkills.push(entry);
+                }
+            }
+        }
+        catch {
+            // skills root absent; nothing to warn about
+        }
         checks.push({
-            name: "warning:codex:legacy_hooks_json",
-            ok: true,
-            details: legacyHooksPresent
-                ? `warning: ${legacyHooks} still present; Codex CLI has no hooks API — run \`cclaw sync\` to remove it.`
-                : `no legacy ${legacyHooks} detected`
+            name: "warning:codex:legacy_cclaw_cc_skills",
+            ok: legacyCodexSkills.length === 0,
+            details: legacyCodexSkills.length === 0
+                ? `no legacy cclaw-cc* skill folders detected under .agents/skills/`
+                : `warning: legacy skill folders from cclaw v0.39.x present (${legacyCodexSkills.join(", ")}); run \`cclaw sync\` to remove them.`
         });
     }
     if (configuredHarnesses.includes("opencode")) {

package/dist/harness-adapters.js

@@ -14,35 +14,48 @@ const RUNTIME_AGENTS_BLOCK_GLOBAL_PATTERN = new RegExp(RUNTIME_AGENTS_BLOCK_SOUR
 const UTILITY_SHIMS = [
     {
         fileName: "cc-next.md",
-        skillName: "cclaw-cc-next",
+        skillName: "cc-next",
         command: "next",
         skillFolder: "flow-next-step",
         commandFile: "next.md"
     },
     {
         fileName: "cc-ideate.md",
-        skillName: "cclaw-cc-ideate",
+        skillName: "cc-ideate",
         command: "ideate",
         skillFolder: "flow-ideate",
         commandFile: "ideate.md"
     },
     {
         fileName: "cc-view.md",
-        skillName: "cclaw-cc-view",
+        skillName: "cc-view",
         command: "view",
         skillFolder: "flow-view",
         commandFile: "view.md"
     },
     {
         fileName: "cc-ops.md",
-        skillName: "cclaw-cc-ops",
+        skillName: "cc-ops",
         command: "ops",
         skillFolder: "flow-ops",
         commandFile: "ops.md"
     }
 ];
 /** Skill-kind shim name for the root `/cc` entry point. */
-const ENTRY_SHIM_SKILL_NAME = "cclaw-cc";
+const ENTRY_SHIM_SKILL_NAME = "cc";
+/**
+ * Skill directory names that v0.39.0 / v0.39.1 installed under
+ * `.agents/skills/` before the rename. We delete these on every sync so
+ * upgrades from those versions do not leave orphaned `cclaw-cc*`
+ * folders that would double-register in Codex's skill listing.
+ */
+const LEGACY_CODEX_SKILL_NAMES = [
+    "cclaw-cc",
+    "cclaw-cc-next",
+    "cclaw-cc-view",
+    "cclaw-cc-ops",
+    "cclaw-cc-ideate"
+];
 /**
  * Shims that older cclaw versions installed as top-level slash commands but
  * which we now treat as internal (skill-only, invoked by the agent, never
@@ -98,16 +111,20 @@ export const HARNESS_ADAPTERS = {
     codex: {
         id: "codex",
         // Codex CLI reads skills from the universal `.agents/skills/` path
-        // (OpenAI Codex 0.89, Jan 2026; legacy `~/.codex/skills/` also
-        // supported). It has no native `.codex/commands/` slash-command
-        // discovery and no `.codex/hooks.json` primitive — v0.39.0 migrated
-        // cclaw to write skill-kind shims here and stops generating the
-        // dead `.codex/*` surfaces.
+        // (OpenAI Codex 0.89, Jan 2026). It does NOT have a native
+        // `.codex/commands/*` slash-command discovery — cclaw installs
+        // its entry points as skills here. Since v0.114 (Mar 2026) Codex
+        // also exposes lifecycle hooks via `.codex/hooks.json`, behind
+        // the `[features] codex_hooks = true` feature flag in
+        // `~/.codex/config.toml`. cclaw writes that file on sync and
+        // `hookSurface: "limited"` records the reality: SessionStart /
+        // UserPromptSubmit / Stop fire for every turn, but PreToolUse /
+        // PostToolUse only intercept the `Bash` tool.
         commandDir: ".agents/skills",
         shimKind: "skill",
         capabilities: {
             nativeSubagentDispatch: "none",
-            hookSurface: "none",
+            hookSurface: "limited",
             structuredAsk: "plain-text",
             subagentFallback: "role-switch"
         }
@@ -122,6 +139,7 @@ export function harnessTier(harnessId) {
     }
     if (capabilities.hookSurface === "full" ||
         capabilities.hookSurface === "plugin" ||
+        capabilities.hookSurface === "limited" ||
         capabilities.nativeSubagentDispatch === "generic" ||
         capabilities.nativeSubagentDispatch === "partial") {
         return "tier2";
@@ -209,26 +227,33 @@ If the same approach fails three times in a row (same command, same finding, sam
 ### Detail Level
 
 - This managed AGENTS block is intentionally minimal for cross-project use.
-- Harness coverage is tiered: Tier1 (claude), Tier2 (cursor/opencode/codex), Tier3 (fallback/manual-only).
+- Harness coverage is tiered: Tier1 (claude), Tier2 (cursor/opencode/codex — codex has Bash-only tool hooks), Tier3 (fallback/manual-only).
 - Detailed operating procedures live in \`.cclaw/skills/using-cclaw/SKILL.md\`.
 - Preamble budget and cooldown rules live in \`.cclaw/references/protocols/ethos.md\`.
 - Subagent orchestration patterns: \`.cclaw/skills/subagent-dev/SKILL.md\` and \`.cclaw/skills/parallel-dispatch/SKILL.md\`.
 
 ### Codex users
 
-OpenAI Codex CLI has **no native \`/cc\` slash command** and **no hooks API**. The
-\`/cc\`, \`/cc-next\`, \`/cc-ideate\`, \`/cc-view\`, \`/cc-ops\` tokens above describe
-intent — in Codex they map onto skills cclaw installs at
-\`.agents/skills/cclaw-cc*/SKILL.md\`. Activate one of two ways:
+OpenAI Codex CLI has **no native \`/cc\` slash command** (custom prompts
+were deprecated in v0.89, Jan 2026). The \`/cc\`, \`/cc-next\`,
+\`/cc-ideate\`, \`/cc-view\`, \`/cc-ops\` tokens above describe intent — in
+Codex they map onto skills cclaw installs at
+\`.agents/skills/cc*/SKILL.md\`. Activate one of two ways:
 
-- Type \`/use cclaw-cc\` (or \`cclaw-cc-next\`, etc.) at Codex's prompt.
+- Type \`/use cc\` (or \`cc-next\`, etc.) at Codex's prompt.
 - Type \`/cc …\` as plain text — Codex matches the skill \`description\`
   frontmatter (which spells out the token verbatim) and loads the right
   skill body automatically.
 
-Legacy \`.codex/commands/*\` and \`.codex/hooks.json\` are removed on
-\`cclaw sync\` — Codex CLI never consumed either path. See
-\`.cclaw/references/harnesses/codex-playbook.md\` for the hook-substitution matrix.
+Codex CLI v0.114+ (Mar 2026) **does** expose lifecycle hooks via
+\`.codex/hooks.json\`, gated by the \`[features] codex_hooks = true\` flag
+in \`~/.codex/config.toml\`. cclaw generates \`.codex/hooks.json\` on
+sync; if the feature flag is off, hooks are inert and cclaw's
+session-start rehydration simply does not fire. Run \`cclaw doctor\` to
+see if the flag is missing. \`.codex/commands/*\` is still unused by
+Codex CLI and is removed on every sync. See
+\`.cclaw/references/harnesses/codex-playbook.md\` for the hook coverage
+matrix (Bash-only \`PreToolUse\`/\`PostToolUse\`; other events are full).
 ${CCLAW_MARKER_END}`;
 }
 /** Removes the cclaw AGENTS.md block. */
@@ -336,14 +361,22 @@ function codexSkillBody(command, skillFolder, commandFile) {
     const extraContractHeading = command === "cc"
         ? "If you have not already loaded the cclaw meta-skill this session, also load `.cclaw/skills/using-cclaw/SKILL.md` — it is the routing brain for stage/utility selection."
         : "This skill is a utility entry point, not a flow stage. Do not mutate `.cclaw/state/flow-state.json` directly.";
+    const skillSlug = command === "cc" ? "cc" : `cc-${command}`;
     return `# ${title}
 
 You are running inside the OpenAI Codex harness. Codex has **no native
-\`${slashToken}\` slash command and no \`.codex/hooks.json\` primitive** — cclaw
-ships its entry points as skills under \`.agents/skills/\` and relies on
-\`AGENTS.md\` + skill descriptions for activation. If the user typed
-\`${slashToken} …\` as plain text (or asked to perform its action in English),
-follow the steps below.
+\`${slashToken}\` slash command** — custom prompts were deprecated in
+Codex CLI v0.89 (Jan 2026). cclaw ships its entry points as skills
+under \`.agents/skills/${skillSlug}/\` so the user can either:
+
+- Type \`/use ${skillSlug}\` at the Codex prompt, or
+- Type \`${slashToken} …\` (or describe the intent in English) — Codex's
+  skill matcher picks this skill up via the description frontmatter.
+
+Lifecycle hooks **are** available in Codex CLI v0.114+ (behind the
+\`[features] codex_hooks = true\` flag in \`~/.codex/config.toml\`) and
+cclaw installs a matching \`.codex/hooks.json\` — see the playbook for
+what the hook surface does and does not cover.
 
 ## Protocol
 
@@ -363,10 +396,11 @@ follow the steps below.
   append a completed row with \`evidenceRefs\` to
   \`.cclaw/state/delegation-log.json\`. Silent auto-waiver is disabled
   (v0.33+).
-- Codex has no hooks. Session rehydration, prompt-guard, workflow-guard,
-  context-monitor, stop-checkpoint, and pre-compact behavior all have to
-  run as explicit agent steps. Read \`.cclaw/references/harnesses/codex-playbook.md\`
-  for the substitution matrix.
+- Codex's \`PreToolUse\` / \`PostToolUse\` hooks currently only intercept
+  the \`Bash\` tool. \`Write\`, \`Edit\`, \`WebSearch\`, and MCP tool calls
+  are **not** gated by hooks — read
+  \`.cclaw/references/harnesses/codex-playbook.md\` for what cclaw
+  substitutes with in-turn agent steps for those call classes.
 `;
 }
 function codexSkillMarkdown(command, skillName, skillFolder, commandFile) {
@@ -406,9 +440,16 @@ async function writeSkillKindShims(commandDir) {
 }
 /**
  * Legacy codex surfaces cclaw wrote before v0.39.0 that Codex CLI never
- * actually consumed (`.codex/commands/*.md` had no discovery, `.codex/hooks.json`
- * had no hooks API). On every sync we proactively delete these so users
- * upgrading from older installs see a clean `.codex/` (or no `.codex/` at all).
+ * consumed (`.codex/commands/*.md` had no discovery primitive). We keep
+ * removing `.codex/commands/` on every sync so upgrades from those
+ * installs leave a clean slate, but as of v0.40.0 we DO write
+ * `.codex/hooks.json` again — Codex CLI grew a real hooks API in
+ * v0.114.0 (Mar 2026), and that file is the current, supported target.
+ *
+ * This function also removes skill folders named after the old
+ * `cclaw-cc*` scheme (v0.39.0 / v0.39.1) now that cclaw installs them
+ * as plain `cc*`. Leaving them around would make Codex list two skills
+ * for the same entry point.
  */
 async function cleanupLegacyCodexSurfaces(projectRoot) {
     const legacyCommandsDir = path.join(projectRoot, ".codex/commands");
@@ -418,16 +459,21 @@ async function cleanupLegacyCodexSurfaces(projectRoot) {
     catch {
         // best-effort cleanup
     }
-    const legacyHooksFile = path.join(projectRoot, ".codex/hooks.json");
-    try {
-        await fs.rm(legacyHooksFile, { force: true });
-    }
-    catch {
-        // best-effort cleanup
+    // Remove the old `cclaw-cc*` skill folders if they exist from a
+    // previous cclaw install. Idempotent; best-effort.
+    const legacySkillsRoot = path.join(projectRoot, ".agents/skills");
+    for (const name of LEGACY_CODEX_SKILL_NAMES) {
+        const folder = path.join(legacySkillsRoot, name);
+        try {
+            await fs.rm(folder, { recursive: true, force: true });
+        }
+        catch {
+            // best-effort
+        }
     }
-    // If `.codex/` is now empty we drop it entirely — codex CLI doesn't need
-    // that directory anymore. Leave it alone if the user stored their own
-    // data there.
+    // If `.codex/` is now empty we drop it — happens when neither hooks
+    // are enabled nor the user has their own state there. Otherwise we
+    // leave the directory alone.
     try {
         const codexDir = path.join(projectRoot, ".codex");
         const entries = await fs.readdir(codexDir);

package/dist/install.js

@@ -23,7 +23,7 @@ import { archiveCommandContract, archiveCommandSkillMarkdown } from "./content/a
 import { rewindCommandContract, rewindCommandSkillMarkdown } from "./content/rewind-command.js";
 import { subagentDrivenDevSkill, parallelAgentsSkill } from "./content/subagents.js";
 import { sessionHooksSkillMarkdown } from "./content/session-hooks.js";
-import { sessionStartScript, stopCheckpointScript, preCompactScript, opencodePluginJs, claudeHooksJson, cursorHooksJson } from "./content/hooks.js";
+import { sessionStartScript, stopCheckpointScript, preCompactScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
 import { contextMonitorScript, promptGuardScript, workflowGuardScript } from "./content/observe.js";
 import { META_SKILL_NAME, usingCclawSkillMarkdown } from "./content/meta-skill.js";
 import { decisionProtocolMarkdown, completionProtocolMarkdown, ethosProtocolMarkdown } from "./content/protocols.js";
@@ -667,10 +667,18 @@ async function writeHooks(projectRoot, config) {
             await ensureDir(cursorDir);
             await writeMergedHookJson(projectRoot, path.join(cursorDir, "hooks.json"), cursorHooksJson());
         }
-        // Codex has no hooks primitive — v0.39.0 stopped generating
-        // `.codex/hooks.json` because Codex CLI never actually read it. Codex
-        // substitutes for hooks via explicit agent steps documented in the
-        // codex playbook.
+        else if (harness === "codex") {
+            // Codex CLI ≥ v0.114 (Mar 2026) supports lifecycle hooks at
+            // `.codex/hooks.json`, gated behind the `[features] codex_hooks = true`
+            // flag in `~/.codex/config.toml`. cclaw always writes the file so
+            // the moment the flag flips on, the cclaw hooks start firing. See
+            // `codexHooksJsonWithObservation` for the Bash-only caveat on
+            // PreToolUse/PostToolUse. `cclaw doctor` warns if the feature flag
+            // is not set.
+            const codexDir = path.join(projectRoot, ".codex");
+            await ensureDir(codexDir);
+            await writeMergedHookJson(projectRoot, path.join(codexDir, "hooks.json"), codexHooksJson());
+        }
         // OpenCode registration is auto-managed via opencode.json/opencode.jsonc.
     }
 }
@@ -905,13 +913,14 @@ async function writeCursorWorkflowRule(projectRoot, harnesses) {
 }
 async function syncDisabledHarnessArtifacts(projectRoot, harnesses) {
     const enabled = new Set(harnesses);
-    // Codex is intentionally absent — cclaw stopped generating `.codex/hooks.json`
-    // in v0.39.0 (the file was never consumed by Codex CLI). Legacy `.codex/*`
-    // files are removed unconditionally by `cleanupLegacyCodexSurfaces` during
-    // every `syncHarnessShims` pass.
+    // v0.40.0: `.codex/hooks.json` is back on the managed list now that
+    // Codex CLI actually consumes it (v0.114+, Mar 2026). Legacy
+    // `.codex/commands/` cleanup still happens unconditionally from
+    // `cleanupLegacyCodexSurfaces` inside `syncHarnessShims`.
     const managedHookFiles = [
         { harness: "claude", hookPath: path.join(projectRoot, ".claude/hooks/hooks.json") },
-        { harness: "cursor", hookPath: path.join(projectRoot, ".cursor/hooks.json") }
+        { harness: "cursor", hookPath: path.join(projectRoot, ".cursor/hooks.json") },
+        { harness: "codex", hookPath: path.join(projectRoot, ".codex/hooks.json") }
     ];
     for (const entry of managedHookFiles) {
         if (enabled.has(entry.harness))
@@ -1306,15 +1315,19 @@ export async function uninstallCclaw(projectRoot) {
             // directory not present
         }
     }
-    // v0.39.0 migrated Codex shims to `.agents/skills/cclaw-cc*/SKILL.md`
-    // (Codex CLI reads `.agents/skills/`, not `.codex/commands/`). On uninstall
-    // we remove just the cclaw-owned skill folders, not the whole
-    // `.agents/skills/` directory — other tools may share it.
+    // Codex shim location history:
+    // - < v0.39.0: `.codex/commands/cc*.md` (never consumed by Codex CLI)
+    // - v0.39.0 / v0.39.1: `.agents/skills/cclaw-cc*/SKILL.md`
+    // - ≥ v0.40.0: `.agents/skills/cc*/SKILL.md` (matches Codex's `/use cc`
+    //   prompt verbatim)
+    // Remove all three legacy layouts on uninstall so orphans can't linger.
+    // We only touch cclaw-owned folder names — other tools share
+    // `.agents/skills/` with us.
     const codexSkillsRoot = path.join(projectRoot, ".agents/skills");
     try {
         const entries = await fs.readdir(codexSkillsRoot);
         for (const entry of entries) {
-            if (/^cclaw-(?:cc)(?:-.*)?$/u.test(entry)) {
+            if (/^(?:cclaw-)?cc(?:-(?:next|view|ops|ideate))?$/u.test(entry)) {
                 await fs.rm(path.join(codexSkillsRoot, entry), { recursive: true, force: true });
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.39.1",
+  "version": "0.40.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {