cclaw-cli 0.40.0 → 0.41.0

package/README.md

@@ -359,8 +359,8 @@ 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) | limited (Bash-only `PreToolUse`/`PostToolUse`; requires `codex_hooks` feature flag) | plain-text | `codex-playbook.md` |
+| OpenCode | plugin / in-session | `role-switch` | plugin | `question` (permission-gated; `permission.question: "allow"`) | `opencode-playbook.md` |
+| OpenAI Codex | in-session only | `role-switch` (evidenceRefs required) | limited (Bash-only `PreToolUse`/`PostToolUse`; requires `codex_hooks` feature flag) | `request_user_input` (experimental; Plan / Collaboration mode) | `codex-playbook.md` |
 
 What the fallbacks mean:
 

package/dist/content/compound-command.js

@@ -39,8 +39,10 @@ the user can approve individual lifts, accept-all, or skip.
    "Drift check" section in the skill): confirm the lift target file is
    current, spot-check the repo for contradictions, demote stale clusters
    into a new superseding entry instead of a lift.
-6. Otherwise, present **one** structured ask (AskUserQuestion / AskQuestion /
-   plain text) summarising all candidates at once:
+6. Otherwise, present **one** structured ask via the harness's native ask
+   tool (\`AskUserQuestion\` / \`AskQuestion\` / \`question\` /
+   \`request_user_input\`; plain-text lettered list as fallback) summarising
+   all candidates at once:
    - \`apply-all\` (default) — apply every listed lift,
    - \`apply-selected\` — prompt per-candidate,
    - \`skip\` — record a skip reason and advance without changes.

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:
@@ -225,6 +241,23 @@ Codex CLI has a different shape from Claude/Cursor:
   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
 
 Codex has no subagent dispatch — neither named nor generic. Mandatory

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/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\`:**
 

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

@@ -104,7 +104,15 @@ 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"
         }
     },
@@ -125,7 +133,15 @@ export const HARNESS_ADAPTERS = {
         capabilities: {
             nativeSubagentDispatch: "none",
             hookSurface: "limited",
-            structuredAsk: "plain-text",
+            // 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"
         }
     }

package/dist/install.js

@@ -984,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`);

package/package.json

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