cclaw-cli 0.40.0 → 0.42.0

package/README.md

@@ -152,7 +152,7 @@ inside `/cc-ops` subcommands.
 |---|---|
 | **`/cc <idea>`** | Classify the task, discover origin docs (`docs/prd/**`, ADRs, root `PRD.md`, …), sniff the stack, recommend a track, then start the first stage of that track. `/cc` without arguments resumes the current flow. |
 | **`/cc-next`** | The one progression primitive. Reads `flow-state.json`, checks gates + mandatory subagent delegations, and either resumes the current stage or advances to the next. `/cc-next` in a new session is how you **resume**. |
-| **`/cc-ideate`** | Repository improvement discovery. Scans for TODOs, flaky tests, oversized modules, docs drift, and recurring knowledge-store lessons; returns a ranked backlog before you commit to a specific feature. |
+| **`/cc-ideate`** | Repository improvement discovery. Scans for TODOs, flaky tests, oversized modules, docs drift, and recurring knowledge-store lessons, **persists the ranked backlog** to `.cclaw/artifacts/ideation-<date>-<slug>.md`, and ends with a concrete handoff: launch `/cc` on the selected candidate in the same session, save-and-close, or discard. Resume check on next run reuses any ideation artifact younger than 30 days. Never mutates `flow-state.json`. |
 | **`/cc-view`** | Read-only flow visibility. `/cc-view status` (default) shows stage progress, mandatory delegations with their fulfillment mode (isolated / generic-dispatch / role-switch), the ship closeout substate (retro → compound → archive), and the active harness parity row. `/cc-view tree` renders the same picture as a tree with a closeout sub-branch under ship and a per-harness playbook summary. `/cc-view diff` shows stage/gate/closeout/delegation deltas since the last run. Never mutates state (except diff's snapshot baseline). |
 
 > Power-user surface: `/cc-ops` is an operational router for manual
@@ -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/ideate-command.d.ts

@@ -1,2 +1,9 @@
 export declare function ideateCommandContract(): string;
 export declare function ideateCommandSkillMarkdown(): string;
+/**
+ * Exposed for tests and docs that need to mention the artifact convention
+ * without hard-coding the path string in two places.
+ */
+export declare const IDEATION_ARTIFACT_PATH_PATTERN = ".cclaw/artifacts/ideation-<YYYY-MM-DD-slug>.md";
+export declare const IDEATION_ARTIFACT_GLOB_PATTERN = ".cclaw/artifacts/ideation-*.md";
+export declare const IDEATION_RESUME_WINDOW = 30;

package/dist/content/ideate-command.js

@@ -1,39 +1,62 @@
 import { RUNTIME_ROOT } from "../constants.js";
 const IDEATE_SKILL_FOLDER = "flow-ideate";
 const IDEATE_SKILL_NAME = "flow-ideate";
+/**
+ * Directory + filename convention for ideation artifacts. These are separate
+ * from stage artifacts (00-..08-*.md) because `/cc-ideate` runs outside the
+ * critical-path flow state machine and must not collide with stage numbering.
+ */
+const IDEATION_ARTIFACT_GLOB = ".cclaw/artifacts/ideation-*.md";
+const IDEATION_ARTIFACT_PATTERN = ".cclaw/artifacts/ideation-<YYYY-MM-DD-slug>.md";
+const IDEATION_RESUME_WINDOW_DAYS = 30;
+/**
+ * Structured-ask tool list reused across cclaw skills. Kept inline here (small
+ * enough) to avoid cross-module coupling; larger stage skills cite the shared
+ * protocol file instead.
+ */
+const STRUCTURED_ASK_TOOLS = "`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";
 export function ideateCommandContract() {
     return `# /cc-ideate
 
 ## Purpose
 
-Repository-improvement discovery mode. Generate a ranked backlog of high-value
-improvements before committing to a specific feature request.
+Repository-improvement discovery mode. Generate a ranked backlog of
+high-value improvements, persist it as an artifact on disk, and end with
+an explicit handoff — either launch \`/cc\` on a chosen candidate in the
+same session, or save/discard the backlog.
 
 ## HARD-GATE
 
-- This is discovery mode only. Do not start implementation automatically.
-- Every recommendation must include evidence from the current repository.
-- End with a decision prompt: pick one candidate or cancel.
+- Discovery mode only. Never mutate \`.cclaw/state/flow-state.json\`.
+- Every recommendation cites evidence from the current repository
+  (file path, command output, or knowledge-store entry id).
+- Always write a persisted artifact to
+  \`${IDEATION_ARTIFACT_PATTERN}\`. Chat-only output is not acceptable —
+  the next session must be able to resume.
+- Always end with a structured handoff prompt, not an open question.
 
 ## Algorithm
 
-1. Scan repo signals:
-   - open TODO/backlog notes
-   - flaky or failing tests
-   - oversized modules / complexity hotspots
-   - docs drift vs changed code
-   - repeated learnings from \`.cclaw/knowledge.jsonl\`
-2. Produce 5-10 candidates with:
-   - impact (High/Medium/Low)
-   - effort (S/M/L)
-   - confidence (High/Medium/Low)
-   - evidence path(s)
-3. Rank candidates by impact/effort ratio.
-4. Present one recommendation as default.
-5. Ask user to choose:
-   - (A) start with recommended item
-   - (B) choose another candidate
-   - (C) cancel
+1. **Resume check.** Glob \`${IDEATION_ARTIFACT_GLOB}\`. If any artifact
+   has been modified within the last ${IDEATION_RESUME_WINDOW_DAYS} days,
+   offer the user: continue that backlog, start fresh, or cancel.
+2. **Scan repo signals:**
+   - open TODO/FIXME/XXX/HACK notes,
+   - flaky or failing tests,
+   - oversized modules / complexity hotspots,
+   - docs drift vs changed code,
+   - repeated entries in \`${RUNTIME_ROOT}/knowledge.jsonl\`.
+3. **Produce 5-10 candidates** with impact (High/Medium/Low),
+   effort (S/M/L), confidence (High/Medium/Low), and one evidence path
+   per candidate.
+4. **Rank by impact/effort**, recommend the top item.
+5. **Write the artifact** at
+   \`${IDEATION_ARTIFACT_PATTERN}\` using the schema in the skill.
+6. **Present the handoff prompt** with four concrete options — not A/B/C
+   letters. Default = "Start /cc on the top recommendation".
 
 ## Primary skill
 
@@ -43,31 +66,152 @@ improvements before committing to a specific feature request.
 export function ideateCommandSkillMarkdown() {
     return `---
 name: ${IDEATE_SKILL_NAME}
-description: "Repository ideation mode: detect and rank high-leverage improvements before implementation."
+description: "Repository ideation mode: detect and rank high-leverage improvements, persist a backlog artifact, and hand off to /cc or save/discard."
 ---
 
 # /cc-ideate
 
 ## Announce at start
 
-"Using flow-ideate to identify highest-leverage improvements in this repository."
+"Using flow-ideate to identify highest-leverage improvements in this
+repository. Will persist a ranked backlog to
+\`${IDEATION_ARTIFACT_PATTERN}\` and end with an explicit handoff."
 
 ## HARD-GATE
 
-Do not start coding in ideate mode. End with an explicit user choice.
+- Do not start coding in ideate mode.
+- Do not mutate \`.cclaw/state/flow-state.json\` — ideation sits outside
+  the critical-path flow.
+- Always produce the artifact file on disk before presenting the handoff.
+- Always end with a structured handoff that names the concrete follow-up
+  command for each option. No A/B/C letters without command context.
 
 ## Protocol
 
-1. Collect evidence from the current repo state.
-2. Build candidate improvements with impact/effort/confidence.
-3. Rank and recommend one candidate.
-4. Ask for explicit selection.
-5. If user selects a candidate, hand off to \`/cc <selected idea>\`.
+### Phase 0 — Resume check
 
-## Candidate format
+1. Use the harness's file-glob tool (\`Glob\` pattern
+   \`${IDEATION_ARTIFACT_GLOB}\` or equivalent \`ls\`/\`find\`).
+2. Filter to files modified within the last ${IDEATION_RESUME_WINDOW_DAYS} days.
+3. If one or more match, present **one** structured ask using the
+   harness's native tool (${STRUCTURED_ASK_TOOLS}) with options:
+   - **Continue the existing backlog** — read the most-recent
+     ideation-*.md and work from its candidate list; skip re-scanning.
+   - **Start a fresh scan** — proceed to Phase 1; the old artifact stays
+     on disk for history.
+   - **Cancel** — stop; do not scan or write anything.
+4. If no recent artifact exists, proceed to Phase 1 silently.
 
-| ID | Improvement | Impact | Effort | Confidence | Evidence |
-|---|---|---|---|---|---|
-| I-1 |  | High/Medium/Low | S/M/L | High/Medium/Low | path or command evidence |
+### Phase 1 — Collect evidence
+
+Scan the current repo. Examples of signals (not exhaustive):
+
+- \`rg -n 'TODO|FIXME|XXX|HACK|TBD'\` grouped by file.
+- Test-runner output (\`npm test\`, \`pytest\`, \`go test ./...\`) — note
+  failures, timeouts, deprecation warnings.
+- Module size outliers (\`wc -l\` or \`du\`) with weak direct test coverage.
+- Docs drift: check that \`README.md\` / \`docs/\` reference files that
+  still exist and flags/APIs that still match \`src/\`.
+- \`${RUNTIME_ROOT}/knowledge.jsonl\` entries with \`type: "heuristic"\`
+  or repeated \`subject:\` values.
+
+Record each finding with the exact file path or command that produced it.
+
+### Phase 2 — Build candidates
+
+For each high-signal finding, construct a candidate:
+
+- **ID** — \`I-1\`, \`I-2\`, …
+- **Title** — one short imperative phrase
+- **Impact** — High / Medium / Low
+- **Effort** — S / M / L
+- **Confidence** — High / Medium / Low
+- **Evidence** — path(s) or command output, inline if short
+- **Proposed handoff** — the exact \`/cc <phrase>\` the user would run
+  to act on this candidate
+
+Aim for 5–10 candidates. Do not invent candidates without evidence.
+
+### Phase 3 — Rank and write the artifact
+
+1. Sort by impact/effort ratio; break ties with confidence.
+2. Compute the artifact filename:
+   - \`slug\` = first 3–5 words of the top recommendation, lowercase,
+     non-alphanumeric collapsed to \`-\`, trimmed. When ideation is
+     focus-hinted (user passed an argument), use the focus hint instead.
+   - \`date\` = today in \`YYYY-MM-DD\` (local time).
+   - Path = \`.cclaw/artifacts/ideation-<date>-<slug>.md\`.
+3. Use the harness's write-file tool (\`Write\`, \`apply_patch\`, or shell
+   \`cat <<EOF > path\`) to create the artifact with this schema:
+
+   \`\`\`markdown
+   # Ideation — <date>
+
+   **Focus:** <user-supplied focus or "open-ended scan">
+   **Generated:** <ISO-8601 timestamp>
+   **Recommendation:** I-1
+
+   ## Ranked backlog
+
+   | ID | Improvement | Impact | Effort | Confidence | Evidence |
+   |---|---|---|---|---|---|
+   | I-1 | Fix feature-worktree test timeouts | High | S | High | tests/unit/feature-system.test.ts:31 |
+   | …   | …                                  | …    | … | …    | …                                     |
+
+   ## Candidate detail
+
+   ### I-1 — Fix feature-worktree test timeouts
+   - **Evidence:** \`npm test\` hangs 40s on tests/unit/feature-system.test.ts:31.
+   - **Handoff:** \`/cc Fix feature-worktree test timeouts on macOS\`
+
+   ### I-2 — …
+   \`\`\`
+
+4. Confirm in chat: "Wrote <path>."
+
+### Phase 4 — Handoff prompt
+
+Present **one** structured ask using the harness's native tool
+(${STRUCTURED_ASK_TOOLS}). Each option must name the concrete follow-up —
+no bare A/B/C.
+
+Required options, in this order:
+
+1. **Start /cc on the top recommendation** — the agent immediately loads
+   \`${RUNTIME_ROOT}/skills/using-cclaw/SKILL.md\` and invokes
+   \`/cc <I-1 handoff phrase>\` in the same turn. Default choice.
+2. **Pick a different candidate** — the agent asks which ID (I-2, I-3, …)
+   and then invokes \`/cc <that candidate's handoff phrase>\`.
+3. **Save and close** — leave the artifact on disk, do nothing else.
+   Next session: \`/cc-ideate\` will offer to resume it.
+4. **Discard** — delete the just-written artifact. Use only when the
+   scan produced nothing actionable.
+
+When the structured-ask tool is unavailable, fall back to a plain-text
+lettered list with the same four labels. Do not invent extra options.
+
+### Phase 5 — Execute the choice
+
+- **Start /cc on I-1** or **different candidate:** announce
+  "Handing off to /cc <phrase>" and load the \`using-cclaw\` router
+  skill. From there, the normal \`/cc\` classification and stage flow
+  takes over. Do not produce a second artifact; the ideation file is
+  preserved as the origin document for this run.
+- **Save and close:** reply with the artifact path and stop.
+- **Discard:** delete the artifact file, confirm deletion, stop.
+
+## Do not
+
+- Do not write into \`.cclaw/artifacts/0X-*.md\` (stage artifacts).
+- Do not mutate \`.cclaw/state/flow-state.json\` at any phase.
+- Do not end the turn with an ungrounded "pick one" question — every
+  option in the handoff prompt must reference a concrete command.
 `;
 }
+/**
+ * Exposed for tests and docs that need to mention the artifact convention
+ * without hard-coding the path string in two places.
+ */
+export const IDEATION_ARTIFACT_PATH_PATTERN = IDEATION_ARTIFACT_PATTERN;
+export const IDEATION_ARTIFACT_GLOB_PATTERN = IDEATION_ARTIFACT_GLOB;
+export const IDEATION_RESUME_WINDOW = IDEATION_RESUME_WINDOW_DAYS;

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.42.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {