cclaw-cli 0.39.1 → 0.41.0

package/dist/content/harness-playbooks.js

@@ -134,7 +134,7 @@ Cursor dispatch is real isolation.
 const OPENCODE_PLAYBOOK = `---
 harness: opencode
 fallback: role-switch
-description: "OpenCode has plugin-based dispatch hooks but no isolated subagent worker primitive. cclaw uses an in-session role-switch with a delegation-log entry + evidenceRefs."
+description: "OpenCode has plugin-based dispatch hooks and a native structured-ask tool (question) but no isolated subagent worker primitive. cclaw uses an in-session role-switch with a delegation-log entry + evidenceRefs, and emits Decision Protocol calls through the question tool when it is permitted."
 ---
 
 # OpenCode — Parity Playbook
@@ -145,6 +145,22 @@ delegation gate by role-switching inside the same session: the agent
 announces the role, performs the work against the contract, and records
 evidence.
 
+**Structured ask: native \`question\` tool.** OpenCode ships a first-class
+\`question\` primitive (header + question text + options, plus a
+"type custom" fallback; supports multi-question navigation). It is
+permission-gated:
+
+- \`opencode.json\` must grant \`permission.question: "allow"\` (or be
+  covered by a \`"*": "allow"\` default).
+- ACP clients additionally need \`OPENCODE_ENABLE_QUESTION_TOOL=1\` set
+  on the \`opencode acp\` process.
+
+When the tool is permitted, every Decision Protocol call maps to a single
+\`question\` invocation. When it is denied or the host doesn't expose it,
+fall back to the shared plain-text lettered list — same skeleton, same
+artifact decision log. Full mapping:
+\`.cclaw/references/harness-tools/opencode.md\`.
+
 ## Role-switch protocol
 
 1. Announce the role explicitly in a single message:
@@ -192,28 +208,55 @@ 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.
+
+## Structured ask: native \`request_user_input\` tool
+
+Codex exposes \`request_user_input\` — an experimental tool that accepts
+1-3 short questions and returns the user's answers in the same order.
+It is the primitive the built-in Plan / Collaboration mode templates use
+(see \`codex-rs/collaboration-mode-templates/templates/plan.md\`), and
+agents running inside Codex can call it directly. Answers come back as
+free-form strings, not option IDs — keep lettered options inline in the
+question text so the user's reply maps cleanly to the artifact
+decision log.
+
+cclaw stage skills invoke \`request_user_input\` for every Decision
+Protocol call when the tool is available, and fall back to the shared
+plain-text lettered list when Codex returns a schema error or when the
+current host hides the tool (older builds, non-collaboration mode). Full
+mapping: \`.cclaw/references/harness-tools/codex.md\`.
 
 ## Fallback: role-switch
 
@@ -243,33 +286,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
+
+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 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. |
+| 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/harness-tool-refs.d.ts

@@ -17,4 +17,4 @@
 import type { HarnessId } from "../types.js";
 export declare const HARNESS_TOOL_REFS_DIR = "references/harness-tools";
 export declare function harnessToolRefMarkdown(harness: HarnessId): string;
-export declare const HARNESS_TOOL_REFS_INDEX_MD = "---\nname: Harness tool maps\ndescription: \"Index file. One reference per supported harness \u2014 cite the per-harness file instead of hardcoding tool names in stage skills.\"\n---\n\n# Harness Tool Maps\n\ncclaw supports four harnesses; each exposes different primitive names for the same capabilities. Stage skills and utility skills cite the file matching the currently active harness and fall back to plain-text equivalents for capabilities that the harness lacks.\n\n| Harness | File | Notes |\n|---|---|---|\n| Claude Code | `.cclaw/references/harness-tools/claude.md` | Richest tool surface (AskUserQuestion, Task, WebFetch, WebSearch, MCP, \u2026). |\n| Cursor | `.cclaw/references/harness-tools/cursor.md` | Near-parity with Claude; uses `AskQuestion` instead of `AskUserQuestion`. |\n| OpenCode | `.cclaw/references/harness-tools/opencode.md` | No native ask-user / dispatch; more plain-text fallbacks. |\n| Codex | `.cclaw/references/harness-tools/codex.md` | No native ask-user / dispatch; shell + file I/O only by default. |\n\nWhen a new harness is added or an existing one renames a tool, update the corresponding file (and this index) \u2014 do NOT scatter tool names across skill text.\n";
+export declare const HARNESS_TOOL_REFS_INDEX_MD = "---\nname: Harness tool maps\ndescription: \"Index file. One reference per supported harness \u2014 cite the per-harness file instead of hardcoding tool names in stage skills.\"\n---\n\n# Harness Tool Maps\n\ncclaw supports four harnesses; each exposes different primitive names for the same capabilities. Stage skills and utility skills cite the file matching the currently active harness and fall back to plain-text equivalents for capabilities that the harness lacks.\n\n| Harness | File | Notes |\n|---|---|---|\n| Claude Code | `.cclaw/references/harness-tools/claude.md` | Richest tool surface (AskUserQuestion, Task, WebFetch, WebSearch, MCP, \u2026). |\n| Cursor | `.cclaw/references/harness-tools/cursor.md` | Near-parity with Claude; uses `AskQuestion` instead of `AskUserQuestion`. |\n| OpenCode | `.cclaw/references/harness-tools/opencode.md` | Native `question` tool (permission-gated) for structured asks; no isolated subagent dispatch. |\n| Codex | `.cclaw/references/harness-tools/codex.md` | Native `request_user_input` tool (experimental, Plan / Collaboration mode) for structured asks; no subagent dispatch. |\n\nWhen a new harness is added or an existing one renames a tool, update the corresponding file (and this index) \u2014 do NOT scatter tool names across skill text.\n";

package/dist/content/harness-tool-refs.js

@@ -133,13 +133,13 @@ description: "Canonical mapping of cclaw capability names → OpenCode primitive
 
 # OpenCode — Tool Map
 
-OpenCode exposes a leaner tool surface than Claude Code / Cursor. When a cclaw skill describes a capability that OpenCode lacks, fall back to the plain-text equivalent listed below.
+OpenCode exposes a leaner tool surface than Claude Code / Cursor, but it DOES have a native structured-ask primitive (\`question\`) — you just have to opt into it. When a cclaw skill describes a capability that OpenCode lacks entirely, fall back to the plain-text equivalent listed below.
 
 ## Core capabilities
 
 | cclaw capability | OpenCode primitive | Notes |
 |---|---|---|
-| Ask user a structured question | **Not available as a tool.** | Emit a plain-text numbered list: \`A) ... B) ... C) (recommended) ...\`. Wait for the user's letter. |
+| Ask user a structured question | \`question\` tool | Each call has a header, question text, and a list of options; users can pick an option or type a custom answer. Supports multiple questions with navigation. **Gated:** \`opencode.json\` must set \`permission.question: "allow"\`; ACP clients additionally need the \`OPENCODE_ENABLE_QUESTION_TOOL=1\` env var. If the tool is denied or unavailable, fall back to a plain-text lettered list (\`A) ... B) ... C) (recommended) ...\`). |
 | Dispatch a subagent | **Not available as a tool.** | Inline the work in the current turn, or split across multiple turns with the user driving. |
 | Read file | file-read primitive | Same role as \`Read\`. |
 | Edit file | file-edit primitive | Same role as \`StrReplace\`; confirm diff before writing. |
@@ -154,6 +154,22 @@ OpenCode exposes a leaner tool surface than Claude Code / Cursor. When a cclaw s
 
 ## Decision-protocol mapping
 
+When the \`question\` tool is enabled, issue one call per decision:
+
+\`\`\`
+question({
+  header: "<stage> decision",
+  question: "<one-sentence decision>",
+  options: [
+    "A) <label> — <trade-off>",
+    "B) <label> — <trade-off>",
+    "C) <label> — <trade-off>  (recommended, because <reason>)"
+  ]
+})
+\`\`\`
+
+If the tool is denied or the host doesn't expose it, fall back to plain text using the same skeleton:
+
 \`\`\`
 Decision: <one sentence>.
 
@@ -166,7 +182,7 @@ Please reply with the letter.
 
 ## Escalation / fall-back
 
-Because OpenCode lacks native ask-user and dispatch tools, more of cclaw's protocols degrade to plain text. This is expected — the flow gates and artifacts are identical; only the delivery channel changes.
+OpenCode has the structured-ask primitive (\`question\`) but no isolated subagent dispatch, so delegation falls back to the role-switch playbook. Flow gates and artifacts are identical; only the delivery channel changes.
 `;
 const CODEX_TOOLS_MD = `---
 harness: codex
@@ -176,14 +192,14 @@ description: "Canonical mapping of cclaw capability names → Codex CLI primitiv
 
 # Codex — Tool Map
 
-Codex (OpenAI Codex CLI) exposes roughly the same core surface as OpenCode: file I/O, shell, no native ask-user, no dispatch. Fall back to plain text for anything else.
+Codex (OpenAI Codex CLI) exposes file I/O, shell, skills, and lifecycle hooks (≥ v0.114, gated by the \`codex_hooks\` feature flag). It does NOT have isolated subagent dispatch, but it DOES expose a native structured-ask tool (\`request_user_input\`) on builds with the Plan / Collaboration mode templates. Fall back to plain text only when that tool is denied or hidden.
 
 ## Core capabilities
 
 | cclaw capability | Codex primitive | Notes |
 |---|---|---|
-| Ask user a structured question | **Not available as a tool.** | Emit a plain-text lettered list; wait for the user's reply. |
-| Dispatch a subagent | **Not available as a tool.** | Inline the work; split turns if needed. |
+| Ask user a structured question | \`request_user_input\` tool | Accepts 1-3 short questions and returns the user's answers in the same order. Experimental; used by Codex's built-in Plan / Collaboration mode (see \`codex-rs/collaboration-mode-templates/templates/plan.md\`). Offer only meaningful options — filler choices are explicitly discouraged. Free-form answer strings are returned; keep the lettered options inline in the question text. Fall back to a plain-text lettered list if the tool is hidden or errors. |
+| Dispatch a subagent | **Not available as a tool.** | Codex has no named or generic subagent dispatch. cclaw closes the mandatory-delegation gate with the role-switch playbook (\`.cclaw/references/harnesses/codex-playbook.md\`). |
 | Read file | \`read\` / \`open\` primitive | Same role as \`Read\`. |
 | Edit file | \`edit\` / \`patch\` primitive | Same role as \`StrReplace\`. |
 | Create file | \`write\` primitive | Prefer editing existing files. |
@@ -192,11 +208,23 @@ Codex (OpenAI Codex CLI) exposes roughly the same core surface as OpenCode: file
 | Shell command | shell primitive | Codex CLI may restrict some binaries by default — check the effective permissions. |
 | Fetch URL | \`curl\` via shell | Extract markdown manually. |
 | Web search | **Not available.** | Ask user for docs / URL. |
-| Todo tracking | **Not available as a tool.** | Keep an inline \`### TODO\` section; update it as you progress. |
+| Todo tracking | \`update_plan\` tool (Codex-native checklist) | \`update_plan\` is Codex's built-in progress / checklist surface and is **separate** from Plan / Collaboration mode — do not conflate them. cclaw also keeps an inline \`### TODO\` block in-turn as an audit mirror. |
 | MCP tool call | Depends on runtime config. | If MCP is wired, cite the descriptor; otherwise treat as unavailable. |
 
 ## Decision-protocol mapping
 
+When \`request_user_input\` is available, issue a single call with 1-3 questions:
+
+\`\`\`
+request_user_input({
+  questions: [
+    "<stage> — <one-sentence decision>. Reply A/B/C. A) <label> — <trade-off>. B) <label> — <trade-off>. C) <label> — <trade-off> (recommended, <reason>)."
+  ]
+})
+\`\`\`
+
+Answers come back as free-form strings, not option IDs — keep the lettered options inline so the user's reply maps cleanly to the artifact decision log. When the tool is hidden (older build, non-collaboration mode), fall back to plain text with the same skeleton:
+
 \`\`\`
 Decision: <one sentence>.
 
@@ -209,7 +237,7 @@ Please reply with the letter.
 
 ## Escalation / fall-back
 
-Treat missing tools as "plain-text required", not "skip the step". The gate still has to pass; only the channel changes.
+\`request_user_input\` is the only structured-ask primitive Codex ships; dispatch still requires the role-switch playbook. Treat missing tools as "plain-text required", not "skip the step". The gate still has to pass; only the channel changes.
 `;
 const HARNESS_TOOL_REFS = {
     claude: CLAUDE_TOOLS_MD,
@@ -233,8 +261,8 @@ cclaw supports four harnesses; each exposes different primitive names for the sa
 |---|---|---|
 | Claude Code | \`.cclaw/${HARNESS_TOOL_REFS_DIR}/claude.md\` | Richest tool surface (AskUserQuestion, Task, WebFetch, WebSearch, MCP, …). |
 | Cursor | \`.cclaw/${HARNESS_TOOL_REFS_DIR}/cursor.md\` | Near-parity with Claude; uses \`AskQuestion\` instead of \`AskUserQuestion\`. |
-| OpenCode | \`.cclaw/${HARNESS_TOOL_REFS_DIR}/opencode.md\` | No native ask-user / dispatch; more plain-text fallbacks. |
-| Codex | \`.cclaw/${HARNESS_TOOL_REFS_DIR}/codex.md\` | No native ask-user / dispatch; shell + file I/O only by default. |
+| OpenCode | \`.cclaw/${HARNESS_TOOL_REFS_DIR}/opencode.md\` | Native \`question\` tool (permission-gated) for structured asks; no isolated subagent dispatch. |
+| Codex | \`.cclaw/${HARNESS_TOOL_REFS_DIR}/codex.md\` | Native \`request_user_input\` tool (experimental, Plan / Collaboration mode) for structured asks; no subagent dispatch. |
 
 When a new harness is added or an existing one renames a tool, update the corresponding file (and this index) — do NOT scatter tool names across skill text.
 `;

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/content/protocols.js

@@ -13,10 +13,18 @@ Shared format for decisions that require user confirmation.
 1. State the decision in one sentence.
 2. Provide 2-4 labeled options (A, B, C...).
 3. Mark one option as **recommended** with a short rationale.
-4. Use harness question tools when available:
-   - Claude: \`AskUserQuestion\`
-   - Cursor: \`AskQuestion\`
-   - OpenCode/Codex: plain text options
+4. Use the harness's structured-ask tool when available:
+   - Claude: \`AskUserQuestion\` (up to ~4 options × multi-question).
+   - Cursor: \`AskQuestion\` (≥2 options, multi-question, optional \`allow_multiple\`).
+   - OpenCode: \`question\` tool (options + "type custom" fallback).
+     Requires \`permission.question: "allow"\` in \`opencode.json\`; ACP
+     clients additionally need \`OPENCODE_ENABLE_QUESTION_TOOL=1\`.
+   - Codex: \`request_user_input\` (1-3 short questions; experimental,
+     surfaced in Plan / Collaboration mode).
+   - Fallback (any harness where the native tool is hidden, denied, or
+     returns a schema error): a numbered / lettered plain-text list
+     keeping the same Re-ground / Simplify / RECOMMENDATION / Options
+     skeleton described below.
 5. Wait for user choice before proceeding.
 
 ## Decision skeleton

package/dist/content/retro-command.js

@@ -48,8 +48,11 @@ in the structured ask; there is no \`--skip\` flag.
    - scan \`${knowledgePath()}\` for entries recorded during this run,
    - structure the draft as: Outcomes / Slowed / Accelerated / Repeatable rule.
 4. Update \`closeout.retroDraftedAt = <ISO>\` in flow-state.
-5. Present **one** structured ask (AskUserQuestion on Claude, AskQuestion on
-   Cursor, plain-text options elsewhere):
+5. Present **one** structured ask using the harness's native tool
+   (\`AskUserQuestion\` on Claude, \`AskQuestion\` on Cursor, \`question\` on
+   OpenCode when \`permission.question: "allow"\` is set,
+   \`request_user_input\` on Codex in Plan / Collaboration mode; fall back
+   to a plain-text lettered list when the tool is hidden or errors):
    - \`accept\` (default) — keep the draft as-is,
    - \`edit\` — user edits \`${retroArtifactPath()}\` in-place, then re-runs \`/cc-next\`,
    - \`skip\` — record \`retroSkipped: true\` + one-line reason, no compound entry required.
@@ -106,8 +109,9 @@ Do not silently skip. Do not finalize without updating \`flow-state.json\`.
    - **Accelerated** — patterns/decisions that worked and are worth keeping.
    - **Repeatable rule** — one candidate rule/pattern for next run.
    Record \`closeout.retroDraftedAt\`.
-3. Ask the user **one** structured question via the harness question tool
-   (AskUserQuestion / AskQuestion / plain text fallback):
+3. Ask the user **one** structured question via the harness's native
+   ask tool (\`AskUserQuestion\` / \`AskQuestion\` / \`question\` /
+   \`request_user_input\`; plain-text lettered list as fallback):
 
    > Retro draft ready at \`${retroArtifactPath()}\`. How do you want to
    > proceed? (default: accept)

package/dist/content/stages/design.js

@@ -37,7 +37,7 @@ export const DESIGN = {
     interactionProtocol: [
         "Review architecture decisions section-by-section.",
         "For EACH issue found in a review section, present it ONE AT A TIME. Do NOT batch multiple issues.",
-        "For each issue: use the Decision Protocol — describe concretely with file/line references, present labeled options (A/B/C) with trade-offs, effort estimate (S/M/L/XL), risk level (Low/Med/High), and mark one as (recommended). Do NOT use a numeric Completeness rubric; recommend the option that best covers architecture, data-flow, failure-modes, test, and perf review concerns for the issue with the lowest risk. If AskQuestion/AskUserQuestion is available, send exactly ONE question per call, validate fields against runtime schema, and on schema error immediately fall back to plain-text question instead of retrying guessed payloads.",
+        "For each issue: use the Decision Protocol — describe concretely with file/line references, present labeled options (A/B/C) with trade-offs, effort estimate (S/M/L/XL), risk level (Low/Med/High), and mark one as (recommended). Do NOT use a numeric Completeness rubric; recommend the option that best covers architecture, data-flow, failure-modes, test, and perf review concerns for the issue with the lowest risk. If the harness's native structured-ask tool is available (`AskUserQuestion` / `AskQuestion` / `question` / `request_user_input`), send exactly ONE question per call, validate fields against the runtime schema, and on schema error immediately fall back to a plain-text lettered list instead of retrying guessed payloads.",
         "Only proceed to the next review section after ALL issues in the current section are resolved.",
         "If a section has no issues, say 'No issues found' and move on.",
         "Do not skip failure-mode mapping.",

package/dist/content/stages/review.js

@@ -39,9 +39,9 @@ export const REVIEW = {
         "Run Layer 1 (spec compliance) completely before starting Layer 2.",
         "In each review section, present findings ONE AT A TIME. Do NOT batch.",
         "Classify every finding as Critical, Important, or Suggestion.",
-        "For each Critical finding: use the Decision Protocol — present resolution options (A/B/C) with trade-offs, and mark one as (recommended). Do NOT use a numeric Completeness rubric; recommend the option that fully closes the finding with no carry-over risk and the smallest blast radius. If AskQuestion/AskUserQuestion is available, send exactly ONE question per call, validate fields against runtime schema, and on schema error immediately fall back to plain-text question instead of retrying guessed payloads.",
+        "For each Critical finding: use the Decision Protocol — present resolution options (A/B/C) with trade-offs, and mark one as (recommended). Do NOT use a numeric Completeness rubric; recommend the option that fully closes the finding with no carry-over risk and the smallest blast radius. If the harness's native structured-ask tool is available (`AskUserQuestion` on Claude, `AskQuestion` on Cursor, `question` on OpenCode with `permission.question: \"allow\"`, `request_user_input` on Codex in Plan/Collaboration mode), send exactly ONE question per call, validate fields against the runtime schema, and on schema error immediately fall back to a plain-text lettered list instead of retrying guessed payloads.",
         "Resolve all critical blockers before ship.",
-        "For final verdict: use AskQuestion/AskUserQuestion only if runtime schema is confirmed; otherwise collect verdict with a plain-text single-choice prompt (APPROVED / APPROVED_WITH_CONCERNS / BLOCKED).",
+        "For final verdict: use the native structured-ask tool (`AskUserQuestion` / `AskQuestion` / `question` / `request_user_input`) only if runtime schema is confirmed; otherwise collect verdict with a plain-text single-choice prompt (APPROVED / APPROVED_WITH_CONCERNS / BLOCKED).",
         "**STOP.** Do NOT proceed to ship until the user provides an explicit verdict."
     ],
     process: [

package/dist/content/stages/scope.js

@@ -32,7 +32,7 @@ export const SCOPE = {
         "**Error and Rescue Registry** — For each capability: what breaks, how detected, what fallback."
     ],
     interactionProtocol: [
-        "For scope mode selection: use the Decision Protocol — present expand/selective/hold/reduce as labeled options with trade-offs and mark one as (recommended). Do NOT use a numeric Completeness rubric; recommend the option that best covers the prime-directive failure modes, four data-flow paths, observability, and deferred handling for the in-scope set with the smallest blast radius. Base your recommendation on default heuristics: greenfield -> expand, enhancement -> selective, bugfix/hotfix/refactor -> hold, broad blast radius -> reduce. If AskQuestion/AskUserQuestion is available, send exactly ONE question per call, validate fields against runtime schema, and on schema error immediately fall back to plain-text question instead of retrying guessed payloads.",
+        "For scope mode selection: use the Decision Protocol — present expand/selective/hold/reduce as labeled options with trade-offs and mark one as (recommended). Do NOT use a numeric Completeness rubric; recommend the option that best covers the prime-directive failure modes, four data-flow paths, observability, and deferred handling for the in-scope set with the smallest blast radius. Base your recommendation on default heuristics: greenfield -> expand, enhancement -> selective, bugfix/hotfix/refactor -> hold, broad blast radius -> reduce. If the harness's native structured-ask tool is available (`AskUserQuestion` / `AskQuestion` / `question` / `request_user_input`), send exactly ONE question per call, validate fields against the runtime schema, and on schema error immediately fall back to a plain-text lettered list instead of retrying guessed payloads.",
         "Walk through the scope checklist interactively. Each checklist item that surfaces a decision should be presented to the user as a question, not as a monologue. Do not dump all items at once.",
         "Challenge premise and verify the problem framing before anything else.",
         "Take a position on every scope decision. Avoid hedging phrases like 'this could work' or 'there are many ways'; state your recommendation and one concrete condition that would change it.",

package/dist/content/stages/ship.js

@@ -35,7 +35,7 @@ export const SHIP = {
     interactionProtocol: [
         "Run preflight checks before any release action.",
         "Document release notes and rollback plan explicitly.",
-        "For finalization mode: use the Decision Protocol — present modes as labeled options (A/B/C/D) with consequences, and mark one as (recommended). Do NOT use a numeric Completeness rubric; recommend the mode that best addresses release blast-radius, rollback readiness, observability, and stakeholder communication — ties go to the most reversible option. If AskQuestion/AskUserQuestion is available, send exactly ONE question per call, validate fields against runtime schema, and on schema error immediately fall back to plain-text question instead of retrying guessed payloads.",
+        "For finalization mode: use the Decision Protocol — present modes as labeled options (A/B/C/D) with consequences, and mark one as (recommended). Do NOT use a numeric Completeness rubric; recommend the mode that best addresses release blast-radius, rollback readiness, observability, and stakeholder communication — ties go to the most reversible option. If the harness's native structured-ask tool is available (`AskUserQuestion` / `AskQuestion` / `question` / `request_user_input`), send exactly ONE question per call, validate fields against the runtime schema, and on schema error immediately fall back to a plain-text lettered list instead of retrying guessed payloads.",
         "Do not proceed if critical blockers remain from review.",
         "**STOP.** Present finalization options and wait for user selection before executing any finalization action."
     ],

package/dist/content/start-command.js

@@ -76,7 +76,7 @@ This is the **recommended way to start** working with cclaw. Use \`/cc-next\` fo
 7. Present the recommendation as a single decision with explicit options:
    > \`Recommended track: <quick|medium|standard>\` because \`<one-line reason citing matched triggers>\`.
    > Override? (A) keep \`<recommended>\`  (B) switch track  (C) cancel.
-   If \`AskQuestion\`/\`AskUserQuestion\` is available, send exactly ONE question; on schema error, fall back to plain text.
+   If the harness's native ask tool is available (\`AskUserQuestion\` / \`AskQuestion\` / \`question\` / \`request_user_input\`), send exactly ONE question; on schema error, fall back to a plain-text lettered list.
 8. Persist the chosen track to \`${flowPath}\` (\`track\` field). Compute \`skippedStages\` from the track and write that too. Use the **first stage of the chosen track** as \`currentStage\` (quick → \`spec\`, medium/standard → \`brainstorm\`, trivial fast-path → \`design\` or \`spec\` per Phase 0).
 9. Write the prompt to \`.cclaw/artifacts/00-idea.md\` with the following header lines: \`Class:\` (from Phase 0), \`Track:\` (chosen track + matched heuristic), \`Stack:\` (from Phase 2 detection, or \`unknown\`), and a \`Discovered context\` section if Phase 1 found origin docs.
 10. Load the **first-stage skill for the chosen track** and its command file:

package/dist/content/subagents.js

@@ -47,8 +47,8 @@ Human input remains mandatory only at explicit approval gates (plan approval, us
 |---|---|---|---|---|
 | Claude | \`native\` | Task (named subagent_type) | AskUserQuestion | \`.cclaw/references/harnesses/claude-playbook.md\` |
 | Cursor | \`generic-dispatch\` | Task (generic subagent_type: explore/generalPurpose/…) | AskQuestion | \`.cclaw/references/harnesses/cursor-playbook.md\` |
-| OpenCode | \`role-switch\` | plugin dispatch _or_ in-session role-switch | plain-text options | \`.cclaw/references/harnesses/opencode-playbook.md\` |
-| Codex | \`role-switch\` | in-session role-switch (mandatory evidenceRefs) | plain-text options | \`.cclaw/references/harnesses/codex-playbook.md\` |
+| OpenCode | \`role-switch\` | plugin dispatch _or_ in-session role-switch | \`question\` (permission-gated; \`permission.question: "allow"\`) | \`.cclaw/references/harnesses/opencode-playbook.md\` |
+| Codex | \`role-switch\` | in-session role-switch (mandatory evidenceRefs) | \`request_user_input\` (experimental; Plan / Collaboration mode) | \`.cclaw/references/harnesses/codex-playbook.md\` |
 
 **Dispatch rules driven by \`subagentFallback\`:**