cclaw-cli 0.39.1 → 0.41.0

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.d.ts

@@ -58,7 +58,23 @@ export interface HarnessAdapter {
          */
         nativeSubagentDispatch: "full" | "generic" | "partial" | "none";
         hookSurface: "full" | "plugin" | "limited" | "none";
-        structuredAsk: "AskUserQuestion" | "AskQuestion" | "plain-text";
+        /**
+         * Structured-ask primitive exposed by the harness.
+         *
+         * - `AskUserQuestion`   — Claude Code native tool (≤5 options × multi-question).
+         * - `AskQuestion`       — Cursor native tool (≥2 options, multi-question, `allow_multiple`).
+         * - `question`          — OpenCode native tool (header + options + "type custom"
+         *   fallback); **gated**: requires `permission.question: "allow"` in
+         *   `opencode.json`, and for ACP clients additionally needs
+         *   `OPENCODE_ENABLE_QUESTION_TOOL=1`.
+         * - `request_user_input` — Codex CLI tool (1-3 short questions); experimental
+         *   and primarily surfaced inside Plan / Collaboration mode templates
+         *   (`codex-rs/collaboration-mode-templates`). Available to agents running
+         *   inside Codex but may be hidden on very old builds.
+         * - `plain-text`        — fallback only; used when no native primitive is
+         *   available (no shipping harness uses this in v0.41.0).
+         */
+        structuredAsk: "AskUserQuestion" | "AskQuestion" | "question" | "request_user_input" | "plain-text";
         /**
          * Declared fallback pattern used when the harness cannot satisfy a
          * mandatory delegation natively. Drives `checkMandatoryDelegations`

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
@@ -91,24 +104,44 @@ export const HARNESS_ADAPTERS = {
         capabilities: {
             nativeSubagentDispatch: "partial",
             hookSurface: "plugin",
-            structuredAsk: "plain-text",
+            // OpenCode exposes a native `question` tool (header + options +
+            // custom-answer fallback, multi-question navigation). It is
+            // permission-gated — `opencode.json` must set
+            // `permission.question: "allow"` and ACP clients must export
+            // `OPENCODE_ENABLE_QUESTION_TOOL=1`. cclaw surfaces the tool name
+            // in the Decision Protocol and in the OpenCode playbook; skills
+            // fall back to the shared plain-text lettered list when the tool
+            // is denied or unavailable.
+            structuredAsk: "question",
             subagentFallback: "role-switch"
         }
     },
     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",
-            structuredAsk: "plain-text",
+            hookSurface: "limited",
+            // Codex CLI exposes `request_user_input` — an experimental tool
+            // that asks 1-3 short questions and returns the user's answers.
+            // It is the primitive the built-in Plan / Collaboration mode
+            // templates use (see `codex-rs/collaboration-mode-templates`).
+            // Agents running inside Codex can call it directly; cclaw wires
+            // it into the Decision Protocol and the Codex playbook. The
+            // shared plain-text lettered list is the documented fallback
+            // when the tool is unavailable.
+            structuredAsk: "request_user_input",
             subagentFallback: "role-switch"
         }
     }
@@ -122,6 +155,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 +243,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 +377,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 +412,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 +456,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 +475,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))
@@ -975,8 +984,24 @@ async function writeHarnessGapsState(projectRoot, harnesses) {
                 remediation.push(`subagent dispatch → record explicit harness_limitation waiver; no parity path available`);
                 break;
         }
-        if (capabilities.structuredAsk === "plain-text") {
-            remediation.push("structured ask → fall back to a numbered plain-text list; first option is default");
+        // Per-harness structuredAsk remediation: record either the fallback
+        // requirement (plain-text) or the gating / experimental status of the
+        // native primitive so `cclaw doctor` and harness-gaps.json stay
+        // honest about *why* a primitive might silently not fire.
+        switch (capabilities.structuredAsk) {
+            case "plain-text":
+                remediation.push("structured ask → fall back to a numbered plain-text list; first option is default");
+                break;
+            case "question":
+                remediation.push(`structured ask → OpenCode \`question\` tool; enable with \`permission.question: "allow"\` in \`opencode.json\` (ACP clients additionally need \`OPENCODE_ENABLE_QUESTION_TOOL=1\`). Fallback: shared plain-text lettered list.`);
+                break;
+            case "request_user_input":
+                remediation.push("structured ask → Codex `request_user_input` tool (experimental; surfaced in Plan / Collaboration mode). Fallback: shared plain-text lettered list when the tool is hidden.");
+                break;
+            case "AskUserQuestion":
+            case "AskQuestion":
+                // Native first-class ask — no remediation required.
+                break;
         }
         for (const event of missingHookEvents) {
             remediation.push(`hook event ${event} → schedule the corresponding script manually or accept reduced observability`);
@@ -1306,15 +1331,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.41.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {