cclaw-cli 0.51.22 → 0.51.23

package/README.md

@@ -344,8 +344,9 @@ The `tdd` stage is not prose guidance. It requires:
 - optional **REFACTOR** pass with coverage preservation
 
 `/cc-next` will not advance past `tdd` until the delegation log shows the
-subagent as `completed` (or, on Codex / OpenCode, role-switched with
-`evidenceRefs` — see [Harness support](#harness-support)).
+subagent as `completed`. Codex and OpenCode use generated native subagents
+by default; a role-switch row is only a degraded fallback and must include
+`evidenceRefs` — see [Harness support](#harness-support).
 
 ---
 
@@ -391,25 +392,25 @@ closes every real gap with a documented fallback — not a silent waiver.
 |---|---|---|---|---|
 | Claude Code | full (named subagents) | `native` | full | `AskUserQuestion` |
 | Cursor | generic Task dispatcher | `generic-dispatch` | full | `AskQuestion` |
-| OpenCode | plugin / in-session | `role-switch` | plugin | `question` (permission-gated; `permission.question: "allow"`) |
-| 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) |
+| OpenCode | native subagents (`.opencode/agents`) | `native` | plugin | `question` (permission-gated; `permission.question: "allow"`) |
+| OpenAI Codex | native parallel subagents (`.codex/agents`) | `native` | limited (Bash-only `PreToolUse`/`PostToolUse`; requires `codex_hooks` feature flag) | `request_user_input` (experimental; Plan / Collaboration mode) |
 
 What the fallbacks mean:
 
-- `native` — Claude runs mandatory delegations in isolated subagent
-  workers; cclaw records them with `fulfillmentMode: "isolated"`.
+- `native` — Claude, OpenCode, and Codex run mandatory delegations in
+  isolated subagent workers; cclaw records them with `fulfillmentMode: "isolated"`.
 - `generic-dispatch` — Cursor has a real Task tool with a fixed
   vocabulary of `subagent_type`s (`explore`, `generalPurpose`, …).
   cclaw maps each named agent (planner / reviewer / test-author /
   security-reviewer / doc-updater) onto the generic dispatcher with a
   structured role prompt.
-- `role-switch` — OpenCode and Codex lack an isolated worker primitive.
-  The agent announces the role in-session, performs the work, and
-  records a delegation row with `fulfillmentMode: "role-switch"` and at
-  least one `evidenceRef` pointing at the artifact section that
-  captures the output. Under role-switch, a `completed` row **without**
-  evidenceRefs is classified as `missingEvidence` by `cclaw doctor` and
-  blocks stage completion.
+- `role-switch` — degraded fallback only when the active runtime cannot
+  expose its declared dispatch surface. The agent announces
+  `## cclaw role-switch: <stage>/<agent> (<mode>)`, loads
+  `.cclaw/agents/<agent>.md`, writes outputs to the stage artifact, and
+  records a delegation row with `fulfillmentMode: "role-switch"` plus at
+  least one `evidenceRef`. A role-switch `completed` row without
+  evidenceRefs is classified as `missingEvidence` by `cclaw doctor`.
 - `waiver` — reserved. Only fires auto-waivers if every installed
   harness declares it. Currently unused — v0.33 removed the old
   Codex-only auto-waiver path.

package/dist/content/examples.js

@@ -726,8 +726,8 @@ const DOMAIN_LABELS = {
 export const RESEARCH_FLEET_USAGE_EXAMPLE = [
     "Before drafting `03-design.md`, run `research/research-fleet.md` once and",
     "capture all four lenses in `.cclaw/artifacts/02a-research.md`.",
-    "Dispatch semantics by harness: Claude/Cursor = parallel subagents in one turn;",
-    "OpenCode/Codex = sequential role-switch with explicit announcements.",
+    "Dispatch semantics by harness: Claude/OpenCode/Codex = native subagents;",
+    "Cursor = generic-dispatch Task mapping; role-switch only as degraded fallback.",
     "Design must include a `Research Fleet Synthesis` section that maps each",
     "lens to concrete architecture decisions and risks."
 ].join(" ");

package/dist/content/hook-manifest.js

@@ -74,10 +74,7 @@ export const HOOK_MANIFEST = [
         bindings: {
             claude: [{ event: "PreToolUse", matcher: "Write|Edit|MultiEdit|NotebookEdit|Bash" }],
             cursor: [{ event: "preToolUse", matcher: "*" }],
-            codex: [
-                { event: "UserPromptSubmit" },
-                { event: "PreToolUse", matcher: "Bash|bash" }
-            ]
+            codex: [{ event: "PreToolUse", matcher: "Bash|bash" }]
         }
     },
     {

package/dist/content/learnings.js

@@ -78,7 +78,7 @@ Do not invent alternate stores (no markdown mirror, no SQLite, no per-stage file
 
 Exactly one JSON object per line. Required fields must appear in the order:
 \`type, trigger, action, confidence, domain, stage, origin_stage, origin_run, frequency, universality, maturity, created, first_seen_ts, last_seen_ts, project\`.
-Optional fields \`source\` and \`severity\` may be appended after \`project\`.
+Optional fields \`source\`, \`severity\`, \`supersedes\`, and \`superseded_by\` may be appended after \`project\`.
 
 \`\`\`json
 {"type":"pattern","trigger":"when reviewing external payloads","action":"parse through zod before touching service layer","confidence":"high","domain":"api","stage":"review","origin_stage":"review","origin_run":"payload-hardening","frequency":1,"universality":"project","maturity":"raw","created":"2026-04-14T12:00:00Z","first_seen_ts":"2026-04-14T12:00:00Z","last_seen_ts":"2026-04-14T12:00:00Z","project":"cclaw"}
@@ -103,12 +103,15 @@ Optional fields \`source\` and \`severity\` may be appended after \`project\`.
 | \`project\` | string \\| null | yes | Repo or scope name. Use \`null\` when the entry crosses projects. |
 | \`source\` | \`"stage" \\| "retro" \\| "compound" \\| "ideate" \\| "manual" \\| null\` | no | Origin channel for the entry when known. |
 | \`severity\` | \`"critical" \\| "important" \\| "suggestion"\` | no | Priority signal for compound lifts; \`critical\` enables single-hit override in compound readiness analysis. |
+| \`supersedes\` | string[] | no | Non-empty IDs/slugs of older entries this entry refreshes. Use only for clear replacements discovered during compound closeout or curation. |
+| \`superseded_by\` | string | no | Non-empty ID/slug of the newer entry that refreshes this one. Use only when marking stale guidance as replaced. |
 
 Rules:
 - No other fields beyond the table above. Extra keys are forbidden and MUST be rejected by any writer.
 - Every required-null field must be emitted explicitly as \`null\` (not omitted). This keeps the file grep-friendly.
 - Append-only: never rewrite or delete a historical line. Corrections are new
-  entries whose \`trigger\` clearly supersedes the earlier one.
+  entries whose \`trigger\` clearly supersedes the earlier one; add \`supersedes\` /
+  \`superseded_by\` only when the replacement relationship is clear.
 - Keep each entry one line. No pretty-printing. No trailing commas.
 
 ## Curation policy (target: ≤ 50 active entries)

package/dist/content/meta-skill.d.ts

@@ -1,2 +1,3 @@
 export declare const META_SKILL_NAME = "using-cclaw";
+export declare const META_SKILL_GENERATED_HELPER_SKILLS: readonly ["subagent-dev", "parallel-dispatch", "session", "iron-laws"];
 export declare function usingCclawSkillMarkdown(): string;

package/dist/content/meta-skill.js

@@ -1,6 +1,15 @@
 import { conversationLanguagePolicyMarkdown } from "./language-policy.js";
 import { CLOSEOUT_CHAIN, closeoutChainInline, closeoutFlowMapSentence, closeoutProtocolBehaviorSentence } from "./closeout-guidance.js";
 export const META_SKILL_NAME = "using-cclaw";
+export const META_SKILL_GENERATED_HELPER_SKILLS = [
+    "subagent-dev",
+    "parallel-dispatch",
+    "session",
+    "iron-laws"
+];
+function generatedHelperSkillList() {
+    return META_SKILL_GENERATED_HELPER_SKILLS.map((name) => `\`${name}\``).join(", ");
+}
 export function usingCclawSkillMarkdown() {
     return `---
 name: using-cclaw
@@ -25,7 +34,7 @@ ${conversationLanguagePolicyMarkdown()}
 If \`.cclaw/state/flow-state.json\` exists and \`currentStage\` is set,
 load the matching stage SKILL before producing **substantive** work
 (artifact edits, code, structured clarifying questions). Do not improvise
-from memory. Load only generated helper surfaces that actually exist in this install: \`subagent-dev\`, \`parallel-dispatch\`, \`session\`, \`iron-laws\`, research playbooks, review prompts, or enabled language rule packs under \`.cclaw/rules/lang/\`. Do not invent helper-skill names beyond those generated surfaces.
+from memory. Load only generated helper surfaces that actually exist in this install: ${generatedHelperSkillList()}, research playbooks, review prompts, or enabled language rule packs under \`.cclaw/rules/lang/\`. Do not invent helper-skill names beyond those generated surfaces.
 
 Substantive vs. non-substantive:
 

package/dist/content/node-hooks.js

@@ -1636,7 +1636,7 @@ async function handleVerifyCurrentState(runtime) {
     process.stderr.write(result.stderr.trim().length > 0
       ? result.stderr
       : "[cclaw] hook: local Node runtime entrypoint is required for verify-current-state\\n");
-    return 1;
+    return mode === "strict" ? 1 : 0;
   }
   if (mode === "strict") {
     if (result.code !== 0) {

package/dist/content/skills.js

@@ -61,23 +61,24 @@ function autoSubagentDispatchBlock(stage, track) {
     const rules = stageAutoSubagentDispatch(stage);
     if (rules.length === 0)
         return "";
+    const schema = stageSchema(stage, track);
     const rows = rules
         .map((rule) => {
         const userGate = rule.requiresUserGate ? "required" : "not required";
-        return `| ${rule.agent} | ${rule.mode} | ${userGate} | ${rule.when} |`;
+        return `| ${rule.agent} | ${rule.mode} | ${userGate} | ${rule.when} | ${rule.purpose} |`;
     })
         .join("\n");
-    const mandatory = stageSchema(stage, track).mandatoryDelegations;
+    const mandatory = schema.mandatoryDelegations;
     const mandatoryList = mandatory.length > 0 ? mandatory.map((a) => `\`${a}\``).join(", ") : "none";
     const delegationLogRel = `${RUNTIME_ROOT}/state/delegation-log.json`;
+    const artifactRef = `${RUNTIME_ROOT}/artifacts/${schema.artifactRules.artifactFile}`;
     return `## Automatic Subagent Dispatch
-
-| Agent | Mode | User Gate | Trigger |
-|---|---|---|---|
+| Agent | Mode | User Gate | Trigger | Purpose |
+|---|---|---|---|---|
 ${rows}
-
-Mandatory delegations for this stage: ${mandatoryList}.
-Record completion/waiver in \`${delegationLogRel}\` before stage completion.
+Mandatory: ${mandatoryList}. Record completion/waiver in \`${delegationLogRel}\` before completion.
+### Harness Dispatch Contract
+Use true harness dispatch: Claude native Task, Cursor generic dispatch, OpenCode \`.opencode/agents/<agent>.md\`, Codex \`.codex/agents/<agent>.toml\`. Run independent read-only/review agents in parallel where safe, write evidence into \`${artifactRef}\`, then append \`${delegationLogRel}\` rows with matching \`fulfillmentMode: "isolated"\` or \`"generic-dispatch"\`. Do not collapse OpenCode or Codex to role-switch by default; role-switch is degraded fallback and must carry non-empty \`evidenceRefs\`. Missing evidence blocks completion.
 `;
 }
 function researchPlaybooksBlock(playbooks) {
@@ -160,15 +161,18 @@ function batchExecutionModeBlock(stage, track) {
     const schema = stageSchema(stage, track);
     if (!schema.batchExecutionAllowed)
         return "";
+    const orderingGuidance = track === "quick"
+        ? "Use spec acceptance items / bug reproduction slices for ordering."
+        : "Use plan slices for ordering.";
     return `## Batch Execution Mode
 
 Execute the current dependency batch task-by-task (RED -> GREEN -> REFACTOR).
 Stop on BLOCKED status or when user input is required.
-Apply concise turn announces: one announce per batch boundary (or when risk/plan
+Apply concise turn announces: one announce per batch boundary (or when risk/source
 changes materially), then execute tasks without repetitive boilerplate.
 
 Detailed walkthrough:
-Use the active track's upstream artifact for ordering: plan slices on standard/medium, or spec acceptance items / bug reproduction slices on quick. Keep RED -> GREEN -> REFACTOR evidence in the TDD artifact.
+${orderingGuidance} Keep RED -> GREEN -> REFACTOR evidence in the TDD artifact.
 `;
 }
 function crossStageTraceBlock(trace) {

package/dist/content/stage-command.d.ts

@@ -0,0 +1,2 @@
+import type { FlowStage } from "../types.js";
+export declare function stageCommandShimMarkdown(stage: FlowStage): string;

package/dist/content/stage-command.js

@@ -0,0 +1,17 @@
+import { RUNTIME_ROOT } from "../constants.js";
+import { stageSkillFolder } from "./skills.js";
+export function stageCommandShimMarkdown(stage) {
+    const skillPath = `${RUNTIME_ROOT}/skills/${stageSkillFolder(stage)}/SKILL.md`;
+    return `# /cc-${stage}
+
+This is a thin compatibility shim for the \`${stage}\` flow stage.
+
+Load and follow the authoritative stage skill:
+
+- \`${skillPath}\`
+
+Normal stage resume and advancement uses \`/cc-next\`. Use \`/cc-next\` to read
+\`.cclaw/state/flow-state.json\`, select the active stage, and advance only after
+that stage's gates pass. Do not duplicate the stage protocol here.
+`;
+}

package/dist/content/stages/review.js

@@ -35,8 +35,8 @@ export const REVIEW = {
             "Diff Scope — Run `git diff` against base branch. If no diff, exit early with APPROVED (no changes to review). Scope the review to changed files unless blast-radius analysis requires wider inspection.",
             "Change-Size Check — ~100 lines = normal. ~300 lines = consider splitting. ~1000+ lines = strongly recommend stacked PRs. Flag large diffs to the user.",
             "Risk-Based Second Opinion — compute changed-line count, files-touched count, and trust-boundary movement. Dispatch an adversarial reviewer only when trust boundaries changed, Critical/Important ambiguity remains, or the diff is both large and high-risk; otherwise record `not triggered`.",
-            "Load upstream evidence — read TDD artifact (RED + GREEN + REFACTOR), spec, and plan when present. On quick track, use spec acceptance items / bug reproduction slices instead of nonexistent plan artifacts.",
-            "Run traceability matrix when plan artifacts exist or the active track enforces it; on quick, confirm spec acceptance/reproduction slices are covered without requiring plan-task coverage.",
+            "Load upstream evidence — read TDD artifact (RED + GREEN + REFACTOR), spec, and the active track's upstream source items.",
+            "Run traceability matrix when the active track enforces it; otherwise confirm spec acceptance/reproduction slices are covered directly.",
             "Layer 1: Spec Compliance — check every acceptance criterion against implementation. Verdict: pass/fail per criterion.",
             "Layer 2: Integrated findings — one structured pass tagged by category: correctness, security, performance, architecture, external-safety.",
             "Security sweep — mandatory dedicated security-reviewer pass across diff + touched modules. A zero-finding pass must include `NO_CHANGE_ATTESTATION` with rationale.",
@@ -72,12 +72,12 @@ export const REVIEW = {
             { id: "review_layer_coverage_complete", description: "Layer coverage map in 07-review-army.json confirms spec/correctness/security/performance/architecture/external-safety tags were considered." },
             { id: "review_criticals_resolved", description: "Normal APPROVED or APPROVED_WITH_CONCERNS path only: no unresolved critical blockers remain. BLOCKED routes use review_verdict_blocked instead." },
             { id: "review_army_json_valid", description: "07-review-army.json passes schema validation (validateReviewArmy)." },
-            { id: "review_trace_matrix_clean", description: "Trace matrix has no orphaned criteria/tasks/test slices for the active run, and evidence cites a discovered real test command before ship handoff." }
+            { id: "review_trace_matrix_clean", description: "Trace matrix has no orphaned source items or test slices for the active run, and evidence cites a discovered real test command before ship handoff." }
         ],
         requiredEvidence: [
             "Artifact written to `.cclaw/artifacts/07-review.md`.",
             "Artifact written to `.cclaw/artifacts/07-review-army.json`.",
-            "Traceability matrix run recorded (no orphaned criteria/tasks/tests for enforced tracks).",
+            "Traceability matrix run recorded (no orphaned source items or tests for enforced tracks).",
             "Layer 1 verdict captured with per-criterion pass/fail.",
             "Layer 2 sections completed across correctness, security, performance, architecture, and external-safety findings.",
             "Severity log includes critical/important/suggestion buckets.",
@@ -85,7 +85,7 @@ export const REVIEW = {
             "Fresh verification command discovery recorded, and the command cited in `review_trace_matrix_clean` evidence before ship handoff.",
             "If BLOCKED: include explicit remediation route (`ROUTE_BACK_TO_TDD`) with blocking finding IDs."
         ],
-        inputs: ["implementation diff", "spec and plan artifacts", "test/build evidence"],
+        inputs: ["implementation diff", "upstream artifacts", "test/build evidence"],
         requiredContext: ["spec criteria", "tdd artifact", "rulebook constraints"],
         blockers: [
             "layer 1 failed",
@@ -118,9 +118,9 @@ export const REVIEW = {
             { section: "Layer 2 Findings", required: false, validationRule: "Each finding has severity, description, and resolution status across correctness, security, performance, architecture, and external-safety. Security coverage must include either explicit security findings or `NO_CHANGE_ATTESTATION: <reason>` when no security-relevant changes were found." },
             { section: "Review Findings Contract", required: true, validationRule: "Structured findings in 07-review-army.json include id/severity/confidence/fingerprint/reportedBy/status and source tags from {spec, correctness, security, performance, architecture, external-safety} with dedup reconciliation summary." },
             { section: "Review Readiness Snapshot", required: false, validationRule: "Optional compact summary: completed checks, delegation-log status, staleness signal, open critical blockers, and ship recommendation." },
-            { section: "Completeness Snapshot", required: false, validationRule: "Optional compact coverage summary for AC coverage, task coverage, test-slice coverage, and adversarial-review status when triggered." },
+            { section: "Completeness Snapshot", required: false, validationRule: "Optional compact coverage summary for AC coverage, source item coverage, test-slice coverage, and adversarial-review status when triggered." },
             { section: "Incoming Feedback Queue", required: false, validationRule: "When external review feedback exists, include a queue summary with per-item disposition (resolved / accepted-risk / rejected-with-evidence) and evidence refs." },
-            { section: "Trace Matrix Check", required: false, validationRule: "Records criteria/tasks/tests orphan counts (all zero on enforced tracks) with command output reference." },
+            { section: "Trace Matrix Check", required: false, validationRule: "Records source-item/test orphan counts (all zero on enforced tracks) with command output reference." },
             { section: "Blocked Route", required: false, validationRule: "When Final Verdict is BLOCKED: includes `ROUTE_BACK_TO_TDD`, rewind target `tdd`, and blocked finding IDs." },
             { section: "Severity Summary", required: true, validationRule: "Per-severity count lines for critical, important, and suggestion buckets." },
             { section: "Final Verdict", required: true, validationRule: "Exactly one of: APPROVED, APPROVED_WITH_CONCERNS, BLOCKED." }

package/dist/content/stages/scope.js

@@ -65,7 +65,7 @@ export const SCOPE = {
             "If the user says no but cannot name the change, offer concrete moves: keep scope, add one obvious adjacent capability, reduce to wedge, or re-open stack/product direction.",
             `Before final approval, record outside-voice findings and a \`## Scope Outside Voice Loop\` table using ${reviewLoopPolicySummary("scope")}`,
             "**STOP.** Wait for explicit user approval of the scope mode and scope contract before writing final approval language or advancing.",
-            "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` must be completed or explicitly waived. If no isolated planner is available, use `--waive-delegation=planner --waiver-reason=\"role-switch scope self-review completed\"`. Then close with `node .cclaw/hooks/stage-complete.mjs scope --passed=scope_mode_selected,scope_contract_written,scope_user_approved --evidence-json '{\"scope_mode_selected\":\"<user-approved mode + rationale>\",\"scope_contract_written\":\"<artifact path + sections>\",\"scope_user_approved\":\"<explicit user approval quote or summary>\"}'`. `scope_user_approved` must cite the user's approval; review-loop evidence alone is not approval."
+            "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` must be completed or explicitly waived for a real blocker. If the active harness cannot isolate a planner, run a role-switch planner pass instead: announce `## cclaw role-switch: scope/planner (mandatory)`, write the planner output/evidence into the scope artifact, and append a completed delegation row with `fulfillmentMode: \"role-switch\"` plus non-empty `evidenceRefs`. Then close with `node .cclaw/hooks/stage-complete.mjs scope --passed=scope_mode_selected,scope_contract_written,scope_user_approved --evidence-json '{\"scope_mode_selected\":\"<user-approved mode + rationale>\",\"scope_contract_written\":\"<artifact path + sections>\",\"scope_user_approved\":\"<explicit user approval quote or summary>\"}'`. `scope_user_approved` must cite the user's approval; review-loop evidence alone is not approval."
         ],
         process: [
             "Run configured pre-scope audit only when enabled.",

package/dist/content/stages/tdd.js

@@ -241,7 +241,12 @@ function tddStageVariantForTrack(track) {
         skillDescription: renderTrackTerminology(TDD.skillDescription, renderContext),
         philosophy: {
             ...TDD.philosophy,
-            hardGate: renderTrackTerminology(TDD.philosophy.hardGate, renderContext)
+            hardGate: renderTrackTerminology(TDD.philosophy.hardGate, renderContext),
+            purpose: renderTrackTerminology(TDD.philosophy.purpose, renderContext),
+            whenToUse: TDD.philosophy.whenToUse.map((value) => renderTrackTerminology(value, renderContext)),
+            whenNotToUse: TDD.philosophy.whenNotToUse.map((value) => renderTrackTerminology(value, renderContext)),
+            commonRationalizations: TDD.philosophy.commonRationalizations
+                .map((value) => renderTrackTerminology(value, renderContext))
         },
         executionModel: {
             ...TDD.executionModel,
@@ -258,7 +263,9 @@ function tddStageVariantForTrack(track) {
             requiredEvidence: TDD.executionModel.requiredEvidence
                 .map((value) => renderTrackTerminology(value, renderContext)),
             inputs: TDD.executionModel.inputs.map((value) => renderTrackTerminology(value, renderContext)),
-            requiredContext: [renderContext.upstreamArtifactLabel, "existing test patterns", "affected contracts and state boundaries"]
+            requiredContext: [renderContext.upstreamArtifactLabel, "existing test patterns", "affected contracts and state boundaries"],
+            blockers: TDD.executionModel.blockers.map((value) => renderTrackTerminology(value, renderContext)),
+            exitCriteria: TDD.executionModel.exitCriteria.map((value) => renderTrackTerminology(value, renderContext))
         },
         reviewLens: {
             ...TDD.reviewLens,
@@ -286,7 +293,7 @@ function tddStageVariantForTrack(track) {
                 if (row.section === "Traceability") {
                     return {
                         ...row,
-                        validationRule: "Spec acceptance item IDs and, for bug fixes, reproduction slice IDs are linked to RED/GREEN evidence. No plan artifact is required on quick."
+                        validationRule: "Spec acceptance item IDs and, for bug fixes, reproduction slice IDs are linked to RED/GREEN evidence."
                     };
                 }
                 return {

package/dist/content/subagents.js

@@ -83,16 +83,26 @@ can enforce phase-appropriate write boundaries. Use separate workers only when t
 |---|---|---|---|---|
 | Claude | \`native\` | Task (named subagent_type) | AskUserQuestion | \`npx cclaw-cli doctor\` |
 | Cursor | \`generic-dispatch\` | Task (generic subagent_type: explore/generalPurpose/…) | AskQuestion | \`npx cclaw-cli doctor\` |
-| OpenCode | \`role-switch\` | plugin dispatch _or_ in-session role-switch | \`question\` (permission-gated; \`permission.question: "allow"\`) | \`npx cclaw-cli doctor\` |
-| Codex | \`role-switch\` | in-session role-switch (mandatory evidenceRefs) | \`request_user_input\` (experimental; Plan / Collaboration mode) | \`npx cclaw-cli doctor\` |
+| OpenCode | \`native\` | generated \`.opencode/agents/<agent>.md\` subagents via Task / \`@agent\` mention | \`question\` (permission-gated; \`permission.question: "allow"\`) | \`npx cclaw-cli doctor\` |
+| Codex | \`native\` | generated \`.codex/agents/<agent>.toml\` custom agents via native parallel subagent spawning | \`request_user_input\` (experimental; Plan / Collaboration mode) | \`npx cclaw-cli doctor\` |
 
 **Dispatch rules driven by \`subagentFallback\`:**
 
 - \`native\` — use the harness's own named subagent primitive; delegation entry uses \`fulfillmentMode: "isolated"\`.
 - \`generic-dispatch\` — map each cclaw agent onto the generic dispatcher with a role prompt; delegation entry uses \`fulfillmentMode: "generic-dispatch"\`.
-- \`role-switch\` — announce the role in-session, perform the work, append a delegation row with \`fulfillmentMode: "role-switch"\` and ≥1 \`evidenceRef\`. Without evidenceRefs the \`delegation:mandatory:current_stage\` check reports \`missingEvidence\` and blocks stage completion.
+- \`role-switch\` — degraded fallback only when the active runtime cannot expose its declared dispatch surface. Announce the role in-session, perform the work, append a delegation row with \`fulfillmentMode: "role-switch"\` and ≥1 \`evidenceRef\`. Without evidenceRefs the \`delegation:mandatory:current_stage\` check reports \`missingEvidence\` and blocks stage completion.
 
-The only time a \`harness_limitation\` waiver fires automatically is when every installed harness declares \`subagentFallback: "waiver"\`. cclaw 0.33 no longer maps Codex onto auto-waiver — the agent must role-switch with evidence.
+### Native dispatch contract
+
+Use real harness subagents for OpenCode and Codex:
+
+1. OpenCode: invoke the generated \`.opencode/agents/<agent>.md\` subagent via Task or \`@<agent>\`. Built-in \`general\` / \`explore\` remain fallback subagent types for ad hoc tasks, but cclaw's core roles are generated by name.
+2. Codex: ask Codex to spawn the generated \`.codex/agents/<agent>.toml\` custom agent(s) by name; for review-style independent lanes, request parallel spawning and wait for all results before reconciliation.
+3. Claude: use the native named Task subagent. Cursor: map the cclaw role onto the generic Task/Subagent surface with a self-contained prompt.
+4. Produce stage output in the current artifact, with anchors suitable for \`evidenceRefs\`.
+5. Append delegation ledger rows with \`stage\`, \`agent\`, \`mode\`, \`status: "completed"\`, and \`fulfillmentMode\` matching the dispatch mode (\`"isolated"\` for Claude/OpenCode/Codex, \`"generic-dispatch"\` for Cursor).
+
+The only time a \`harness_limitation\` waiver fires automatically is when every installed harness declares \`subagentFallback: "waiver"\`. Do not map Codex or OpenCode onto auto-waiver or default role-switch; they have true subagent surfaces.
 
 ### Model routing
 

package/dist/content/templates.js

@@ -645,7 +645,7 @@ Execution rule: complete and verify each batch before starting the next batch.
 # TDD Artifact
 
 ## Upstream Handoff
-- Source artifacts: \`04-spec.md\`; \`05-plan.md\` when present. Quick track uses spec acceptance items / bug reproduction slices instead of nonexistent plan tasks.
+- Source artifacts: \`04-spec.md\` plus the active track's upstream source item (plan slice on standard/medium, spec acceptance item or bug reproduction slice on quick).
 - Decisions carried forward:
 - Constraints carried forward:
 - Open questions:
@@ -672,11 +672,11 @@ Execution rule: complete and verify each batch before starting the next batch.
 | S-1 |  |  |  |
 
 ## Acceptance Mapping
-| Slice | Plan task ID or quick source | Spec criterion ID |
+| Slice | Source item ID | Spec criterion ID |
 |---|---|---|
-| S-1 | T-1 / QS-1 | AC-1 |
+| S-1 | SRC-1 | AC-1 |
 
-> On quick track, map to the \`Quick Reproduction Contract\` bug slice or spec acceptance item. Do not invent a plan task just to satisfy this table.
+> Map each slice to the active track's source item: plan slice on standard/medium, or the \`Quick Reproduction Contract\` bug slice / spec acceptance item on quick.
 
 ## Failure Analysis
 | Slice | Expected missing behavior | Actual failure reason |
@@ -693,7 +693,7 @@ Execution rule: complete and verify each batch before starting the next batch.
 - Behavior preserved:
 
 ## Traceability
-- Plan task IDs:
+- Source item IDs:
 - Spec criterion IDs:
 
 
@@ -729,7 +729,7 @@ Execution rule: complete and verify each batch before starting the next batch.
 # Review Artifact
 
 ## Upstream Handoff
-- Source artifacts: \`04-spec.md\`, \`06-tdd.md\`; \`05-plan.md\` only when present. Quick track reviews spec acceptance items / bug reproduction slices without requiring plan-task coverage.
+- Source artifacts: \`04-spec.md\`, \`06-tdd.md\`, plus the active track's upstream source item when available.
 - Decisions carried forward:
 - Constraints carried forward:
 - Open questions:
@@ -766,15 +766,15 @@ Execution rule: complete and verify each batch before starting the next batch.
 
 ## Completeness Snapshot
 - AC coverage: <N>/<M> (<percent>%)
-- Task coverage (tasks backed by ≥1 test slice): <N>/<M> or \`N/A - quick track has no plan artifact\`
+- Source item coverage (source items backed by ≥1 test slice): <N>/<M> or \`N/A - direct spec/reproduction coverage\`
 - Slice coverage (slices linked to ≥1 AC or bug reproduction slice): <N>/<M>
 - Adversarial review: not triggered | pass | fail
 - Overall: complete | concerns | blocked
 
 ## Trace Matrix Check
-- Command: \`cclaw internal trace-matrix\` when plan artifacts exist or the active track enforces it; quick track may record direct AC/reproduction-slice coverage instead.
+- Command: \`cclaw internal trace-matrix\` when the active track enforces it; otherwise record direct AC/reproduction-slice coverage.
 - Orphaned criteria: 0
-- Orphaned tasks: 0 or \`N/A - quick track\`
+- Orphaned source items: 0 or \`N/A - direct spec/reproduction coverage\`
 - Orphaned tests: 0
 - Evidence ref:
 

package/dist/content/track-render-context.js

@@ -34,8 +34,15 @@ export function renderTrackTerminology(value, context) {
     }
     return value
         .replace(/\btask from the plan\b/giu, `${context.traceabilitySourceNoun} from the spec`)
+        .replace(/\bplan confirmation\b/giu, "spec approval")
+        .replace(/\bplan approval\b/giu, "spec approval")
+        .replace(/\bapproved plan slice\b/giu, `approved ${context.traceabilitySliceNoun}`)
+        .replace(/\bplanned slice\b/giu, context.traceabilitySliceNoun)
         .replace(/\bplan task ID\b/giu, context.traceabilityIdNoun)
         .replace(/\bplan task\b/giu, context.traceabilitySourceNoun)
+        .replace(/\bplan-task\b/giu, "acceptance-criterion")
+        .replace(/\btask coverage\b/giu, "source item coverage")
+        .replace(/\borphaned tasks\b/giu, "orphaned source items")
         .replace(/\bplan row\b/giu, "acceptance row")
         .replace(/\btraceable to plan slice\b/giu, `traceable to ${context.traceabilitySliceNoun}`)
         .replace(/\bplan slice\b/giu, context.traceabilitySliceNoun)

package/dist/delegation.d.ts

@@ -6,8 +6,8 @@ export type DelegationStatus = "scheduled" | "completed" | "failed" | "waived";
  * How a delegation was actually fulfilled. Advisory — mirrors the harness
  * `subagentFallback` that was in effect when the entry was recorded.
  *
- * - `isolated`         — Claude-style isolated subagent worker.
- * - `generic-dispatch` — Cursor-style Task dispatch mapped to a named role.
+ * - `isolated`         — native isolated subagent worker (Claude/OpenCode/Codex).
+ * - `generic-dispatch` — generic Task/Subagent dispatch mapped to a named role.
  * - `role-switch`      — performed in-session with explicit role announce.
  * - `harness-waiver`   — auto-waived due to missing dispatch capability.
  */

package/dist/delegation.js

@@ -18,6 +18,13 @@ function delegationLockPath(projectRoot) {
 function createSpanId() {
     return `dspan-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
+function activeHarnessSubagentFallback() {
+    const activeHarness = process.env.CCLAW_ACTIVE_HARNESS;
+    if (!activeHarness)
+        return undefined;
+    return HARNESS_ADAPTERS[activeHarness]
+        ?.capabilities.subagentFallback;
+}
 async function resolveReviewDiffBase(projectRoot) {
     let head = "";
     try {
@@ -229,10 +236,7 @@ export async function appendDelegation(projectRoot, entry) {
             stamped.evidenceRefs = [];
         }
         if (stamped.status === "completed" && stamped.fulfillmentMode === undefined) {
-            const activeFallback = process.env.CCLAW_ACTIVE_HARNESS
-                ? HARNESS_ADAPTERS[process.env.CCLAW_ACTIVE_HARNESS]
-                    ?.capabilities.subagentFallback
-                : undefined;
+            const activeFallback = activeHarnessSubagentFallback();
             if (activeFallback) {
                 stamped.fulfillmentMode = expectedFulfillmentMode([activeFallback]);
             }
@@ -291,8 +295,9 @@ export async function checkMandatoryDelegations(projectRoot, stage, options = {}
     const missingEvidence = [];
     const config = await readConfig(projectRoot).catch(() => null);
     const harnesses = config?.harnesses ?? [];
-    const fallbacks = harnesses.map((h) => HARNESS_ADAPTERS[h].capabilities.subagentFallback);
-    const expectedMode = expectedFulfillmentMode(fallbacks);
+    const configuredFallbacks = harnesses.map((h) => HARNESS_ADAPTERS[h].capabilities.subagentFallback);
+    const activeFallback = activeHarnessSubagentFallback();
+    const expectedMode = expectedFulfillmentMode(activeFallback ? [activeFallback] : configuredFallbacks);
     for (const agent of mandatory) {
         const rows = forRun.filter((e) => e.agent === agent);
         const completedRows = rows.filter((e) => e.status === "completed");
@@ -307,9 +312,11 @@ export async function checkMandatoryDelegations(projectRoot, stage, options = {}
         if (hasWaived) {
             waived.push(agent);
         }
-        // Evidence is required for any non-isolated completion mode. Legacy rows
-        // without fulfillmentMode are inferred to `isolated` during parse.
-        const evidenceRequired = completedRows.some((e) => (e.fulfillmentMode ?? "isolated") !== "isolated");
+        // Evidence is required for non-isolated completions and for explicit
+        // degraded role-switch rows. Native OpenCode/Codex/Claude isolated
+        // dispatch is accepted as true subagent work; role-switch remains a
+        // fallback that must point at artifact evidence.
+        const evidenceRequired = expectedMode !== "isolated" || completedRows.some((e) => (e.fulfillmentMode ?? "isolated") !== "isolated");
         if (hasCompleted &&
             evidenceRequired &&
             !completedRows.some((e) => Array.isArray(e.evidenceRefs) && e.evidenceRefs.length > 0)) {

package/dist/doctor-registry.js

@@ -39,7 +39,7 @@ const RULES = [
         }
     },
     {
-        test: /^(dir:|command:|utility_command:|skill:|utility_skill:|agent:|harness_tool_ref:|harness_ref:|stage_examples_ref:|doctor_ref:)/,
+        test: /^(dir:|command:|utility_command:|stage_command:|skill:|utility_skill:|agent:|harness_tool_ref:|harness_ref:|stage_examples_ref:|doctor_ref:)/,
         metadata: {
             severity: "error",
             summary: "Generated runtime surface presence check.",

package/dist/doctor.js

@@ -18,6 +18,7 @@ import { buildTraceMatrix } from "./trace-matrix.js";
 import { classifyReconciliationNotices, reconcileAndWriteCurrentStageGateCatalog, readReconciliationNotices, RECONCILIATION_NOTICES_REL_PATH, verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "./gate-evidence.js";
 import { parseTddCycleLog, validateTddCycleOrder } from "./tdd-cycle.js";
 import { stageSkillFolder } from "./content/skills.js";
+import { stageCommandShimMarkdown } from "./content/stage-command.js";
 import { doctorCheckMetadata } from "./doctor-registry.js";
 import { resolveTrackFromPrompt } from "./track-heuristics.js";
 import { classifyCodexHooksFlag, codexConfigPath, readCodexConfig } from "./codex-feature-flag.js";
@@ -289,17 +290,23 @@ function normalizeOpenCodePluginEntry(entry) {
     }
     return null;
 }
-async function opencodeRegistrationCheck(projectRoot) {
-    const expected = ".opencode/plugins/cclaw-plugin.mjs";
-    const candidates = [
+const OPENCODE_PLUGIN_REL_PATH = ".opencode/plugins/cclaw-plugin.mjs";
+function opencodeConfigCandidates(projectRoot) {
+    return [
         path.join(projectRoot, "opencode.json"),
         path.join(projectRoot, "opencode.jsonc"),
         path.join(projectRoot, ".opencode/opencode.json"),
         path.join(projectRoot, ".opencode/opencode.jsonc")
     ];
+}
+function openCodeConfigRegistersPlugin(parsed) {
+    const plugins = Array.isArray(parsed.plugin) ? parsed.plugin : [];
+    return plugins.some((entry) => normalizeOpenCodePluginEntry(entry) === OPENCODE_PLUGIN_REL_PATH);
+}
+async function opencodeRegistrationCheck(projectRoot) {
     const mismatches = [];
     let foundAnyConfig = false;
-    for (const configPath of candidates) {
+    for (const configPath of opencodeConfigCandidates(projectRoot)) {
         if (!(await exists(configPath))) {
             continue;
         }
@@ -309,17 +316,49 @@ async function opencodeRegistrationCheck(projectRoot) {
             mismatches.push(`${path.relative(projectRoot, configPath)} is unreadable or invalid JSON`);
             continue;
         }
-        const plugins = Array.isArray(parsed.plugin) ? parsed.plugin : [];
-        const registered = plugins.some((entry) => normalizeOpenCodePluginEntry(entry) === expected);
-        if (registered) {
-            return { ok: true, details: `${path.relative(projectRoot, configPath)} registers ${expected}` };
+        if (openCodeConfigRegistersPlugin(parsed)) {
+            return { ok: true, details: `${path.relative(projectRoot, configPath)} registers ${OPENCODE_PLUGIN_REL_PATH}` };
         }
-        mismatches.push(`${path.relative(projectRoot, configPath)} missing plugin ${expected}`);
+        mismatches.push(`${path.relative(projectRoot, configPath)} missing plugin ${OPENCODE_PLUGIN_REL_PATH}`);
     }
     if (foundAnyConfig) {
         return { ok: false, details: mismatches.join(" | ") };
     }
-    return { ok: false, details: `No opencode.json/opencode.jsonc found with plugin ${expected}` };
+    return { ok: false, details: `No opencode.json/opencode.jsonc found with plugin ${OPENCODE_PLUGIN_REL_PATH}` };
+}
+async function opencodeQuestionPermissionCheck(projectRoot) {
+    const mismatches = [];
+    for (const configPath of opencodeConfigCandidates(projectRoot)) {
+        if (!(await exists(configPath)))
+            continue;
+        const parsed = await readHookDocument(configPath);
+        if (!parsed || !openCodeConfigRegistersPlugin(parsed))
+            continue;
+        const permission = toObject(parsed.permission) ?? {};
+        if (permission.question === "allow") {
+            return {
+                ok: true,
+                details: `${path.relative(projectRoot, configPath)} sets permission.question to "allow" for structured questions`
+            };
+        }
+        mismatches.push(`${path.relative(projectRoot, configPath)} registers ${OPENCODE_PLUGIN_REL_PATH} but must set permission.question to "allow"`);
+    }
+    if (mismatches.length > 0) {
+        return { ok: false, details: mismatches.join(" | ") };
+    }
+    return {
+        ok: false,
+        details: `No opencode config with ${OPENCODE_PLUGIN_REL_PATH} registration found; cannot verify permission.question = "allow"`
+    };
+}
+function opencodeQuestionEnvCheck() {
+    if (process.env.OPENCODE_ENABLE_QUESTION_TOOL === "1") {
+        return { ok: true, details: "OPENCODE_ENABLE_QUESTION_TOOL=1 is set for ACP question tooling" };
+    }
+    return {
+        ok: false,
+        details: "Set OPENCODE_ENABLE_QUESTION_TOOL=1 for OpenCode ACP clients so permission-gated structured questions can use the question tool."
+    };
 }
 async function initRecoveryCheck(projectRoot) {
     const sentinelPath = path.join(projectRoot, RUNTIME_ROOT, "state", ".init-in-progress");
@@ -667,7 +706,6 @@ export async function doctorChecks(projectRoot, options = {}) {
         ok: agentsBlockOk,
         details: `${agentsFile} must contain the managed cclaw marker block with routing, verification, and minimal detail pointer`
     });
-    // User-facing entry commands only. Stage and view subcommands live in skills.
     for (const cmd of ["start", "next", "ideate", "view"]) {
         const cmdPath = path.join(projectRoot, RUNTIME_ROOT, "commands", `${cmd}.md`);
         checks.push({
@@ -676,6 +714,19 @@ export async function doctorChecks(projectRoot, options = {}) {
             details: cmdPath
         });
     }
+    for (const stage of FLOW_STAGES) {
+        const cmdPath = path.join(projectRoot, RUNTIME_ROOT, "commands", `${stage}.md`);
+        let stageCommandOk = false;
+        if (await exists(cmdPath)) {
+            const content = await fs.readFile(cmdPath, "utf8");
+            stageCommandOk = content === stageCommandShimMarkdown(stage);
+        }
+        checks.push({
+            name: `stage_command:${stage}`,
+            ok: stageCommandOk,
+            details: `${cmdPath} must be a thin shim to ${RUNTIME_ROOT}/skills/${stageSkillFolder(stage)}/SKILL.md and /cc-next`
+        });
+    }
     // Utility skills
     for (const [folder, label] of [
         ["learnings", "learnings"],
@@ -942,7 +993,6 @@ export async function doctorChecks(projectRoot, options = {}) {
         const codexStopCmds = collectHookCommands(codexHooks.Stop);
         const codexWiringOk = codexSessionCmds.some((cmd) => cmd.includes("session-start")) &&
             codexUserPromptCmds.some((cmd) => cmd.includes("prompt-guard")) &&
-            codexUserPromptCmds.some((cmd) => cmd.includes("workflow-guard")) &&
             codexUserPromptCmds.some((cmd) => cmd.includes("verify-current-state")) &&
             codexPreCmds.some((cmd) => cmd.includes("prompt-guard")) &&
             codexPreCmds.some((cmd) => cmd.includes("workflow-guard")) &&
@@ -951,7 +1001,7 @@ export async function doctorChecks(projectRoot, options = {}) {
         checks.push({
             name: "hook:wiring:codex",
             ok: codexWiringOk,
-            details: `${codexHooksFile} must wire SessionStart, UserPromptSubmit(prompt/workflow/verify-current-state), PreToolUse(prompt/workflow), PostToolUse(context-monitor), and Stop(stop-handoff). PreToolUse/PostToolUse run Bash-only in Codex v0.114+`
+            details: `${codexHooksFile} must wire SessionStart, UserPromptSubmit(prompt/verify-current-state), Bash-only PreToolUse(prompt/workflow), Bash-only PostToolUse(context-monitor), and Stop(stop-handoff). Codex workflow-guard is intentionally strict Bash-only.`
         });
         // Feature flag warning: Codex ignores `.codex/hooks.json` unless the
         // user has `[features] codex_hooks = true` in `~/.codex/config.toml`.
@@ -1074,6 +1124,18 @@ export async function doctorChecks(projectRoot, options = {}) {
             ok: registration.ok,
             details: registration.details
         });
+        const questionPermission = await opencodeQuestionPermissionCheck(projectRoot);
+        checks.push({
+            name: "hook:opencode:question_permission",
+            ok: questionPermission.ok,
+            details: questionPermission.details
+        });
+        const questionEnv = opencodeQuestionEnvCheck();
+        checks.push({
+            name: "warning:opencode:question_tool_env",
+            ok: questionEnv.ok,
+            details: questionEnv.details
+        });
     }
     const nodeVersion = await commandVersion("node");
     const nodeMajor = parseNodeMajor(nodeVersion.output);

package/dist/harness-adapters.d.ts

@@ -1,19 +1,20 @@
-import type { HarnessId } from "./types.js";
+import { type HarnessId } from "./types.js";
 export declare const CCLAW_MARKER_START = "<!-- cclaw-start -->";
 export declare const CCLAW_MARKER_END = "<!-- cclaw-end -->";
 export type SubagentFallback = 
-/** Harness has real, isolated subagent dispatch; no fallback needed. */
+/** Harness has real, isolated named subagent dispatch; no fallback needed. */
 "native"
 /**
- * Harness has generic dispatch (e.g. Cursor's Task tool with
- * `subagent_type`) but not user-defined named subagents; cclaw maps each
- * named agent to the generic dispatcher with a structured role prompt.
+ * Harness has a real dispatcher but not cclaw-named agents. cclaw maps each
+ * named role to the available built-in/generic subagent surface with a
+ * structured role prompt.
  */
  | "generic-dispatch"
 /**
  * No isolated dispatch — the agent performs the named subagent's role
  * in-session with an explicit role announce + delegation-log entry
- * carrying evidenceRefs. Accepted as `completed` in delegation checks.
+ * carrying evidenceRefs. Accepted as `completed` only when no true dispatch
+ * surface exists.
  */
  | "role-switch"
 /**
@@ -50,11 +51,11 @@ export interface HarnessAdapter {
     capabilities: {
         /**
          * Level of native subagent dispatch:
-         * - `full`    — isolated workers + user-defined named subagents (Claude).
-         * - `generic` — generic dispatcher (Task) without named agents (Cursor).
-         * - `partial` — plugin-based dispatch, not a first-class primitive
-         *   (OpenCode).
-         * - `none`    — no dispatch primitive at all (Codex).
+         * - `full`    — isolated workers + user-defined named subagents (Claude,
+         *   OpenCode, Codex custom agents).
+         * - `generic` — generic dispatcher without cclaw-named agents (Cursor).
+         * - `partial` — limited or plugin-only dispatch surface.
+         * - `none`    — no dispatch primitive at all.
          */
         nativeSubagentDispatch: "full" | "generic" | "partial" | "none";
         hookSurface: "full" | "plugin" | "limited" | "none";
@@ -87,6 +88,8 @@ export declare function harnessShimFileNames(): string[];
 /** Skill folder names cclaw writes under `<commandDir>` for skill-kind harnesses. */
 export declare function harnessShimSkillNames(): string[];
 export declare const HARNESS_ADAPTERS: Record<HarnessId, HarnessAdapter>;
+export declare function harnessDispatchSurface(harnessId: HarnessId): string;
+export declare function harnessDispatchFallback(harnessId: HarnessId): string;
 export type HarnessTier = "tier1" | "tier2" | "tier3";
 export declare function harnessTier(harnessId: HarnessId): HarnessTier;
 /**

package/dist/harness-adapters.js

@@ -1,10 +1,11 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { RUNTIME_ROOT } from "./constants.js";
+import { RUNTIME_ROOT, STAGE_TO_SKILL_FOLDER } from "./constants.js";
 import { conversationLanguagePolicyMarkdown } from "./content/language-policy.js";
 import { CCLAW_AGENTS, agentMarkdown } from "./content/core-agents.js";
 import { ironLawsAgentsMdBlock } from "./content/iron-laws.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
+import { FLOW_STAGES } from "./types.js";
 export const CCLAW_MARKER_START = "<!-- cclaw-start -->";
 export const CCLAW_MARKER_END = "<!-- cclaw-end -->";
 function escapeRegExp(value) {
@@ -46,12 +47,26 @@ const LEGACY_CODEX_SKILL_PREFIX = "cclaw-cc";
  * harness command directories so `/cc-learn` etc. do not linger.
  */
 const LEGACY_HARNESS_SHIMS = ["cc-learn.md"];
+function stageShimFileName(stage) {
+    return `cc-${stage}.md`;
+}
+function stageShimSkillName(stage) {
+    return `cc-${stage}`;
+}
 export function harnessShimFileNames() {
-    return ["cc.md", ...UTILITY_SHIMS.map((shim) => shim.fileName)];
+    return [
+        "cc.md",
+        ...UTILITY_SHIMS.map((shim) => shim.fileName),
+        ...FLOW_STAGES.map((stage) => stageShimFileName(stage))
+    ];
 }
 /** Skill folder names cclaw writes under `<commandDir>` for skill-kind harnesses. */
 export function harnessShimSkillNames() {
-    return [ENTRY_SHIM_SKILL_NAME, ...UTILITY_SHIMS.map((shim) => shim.skillName)];
+    return [
+        ENTRY_SHIM_SKILL_NAME,
+        ...UTILITY_SHIMS.map((shim) => shim.skillName),
+        ...FLOW_STAGES.map((stage) => stageShimSkillName(stage))
+    ];
 }
 export const HARNESS_ADAPTERS = {
     claude: {
@@ -85,7 +100,11 @@ export const HARNESS_ADAPTERS = {
         commandDir: ".opencode/commands",
         shimKind: "command",
         capabilities: {
-            nativeSubagentDispatch: "partial",
+            // OpenCode supports project-local markdown subagents under
+            // `.opencode/agents/`; primary agents can invoke them via the Task
+            // tool or explicit `@agent` mention. cclaw materializes its core
+            // roster there, so mandatory delegations are real isolated subagents.
+            nativeSubagentDispatch: "full",
             hookSurface: "plugin",
             // OpenCode exposes a native `question` tool (header + options +
             // custom-answer fallback, multi-question navigation). It is
@@ -95,7 +114,7 @@ export const HARNESS_ADAPTERS = {
             // in generated harness guidance; skills fall back to the shared
             // plain-text lettered list when the tool is denied or unavailable.
             structuredAsk: "question",
-            subagentFallback: "role-switch"
+            subagentFallback: "native"
         }
     },
     codex: {
@@ -103,8 +122,10 @@ export const HARNESS_ADAPTERS = {
         // Codex CLI reads skills from the universal `.agents/skills/` path
         // (OpenAI Codex 0.89, Jan 2026). It does NOT have a native
         // `.codex/commands/*` slash-command discovery — cclaw installs
-        // its entry points as skills here. Since v0.114 (Mar 2026) Codex
-        // also exposes lifecycle hooks via `.codex/hooks.json`, behind
+        // its entry points as skills here. Current Codex releases also support
+        // native parallel subagents and project-local `.codex/agents/*.toml`
+        // custom agents; cclaw materializes its core roster there. Since v0.114
+        // (Mar 2026) Codex also exposes lifecycle hooks via `.codex/hooks.json`, behind
         // the `[features] codex_hooks = true` feature flag in
         // `~/.codex/config.toml`. cclaw writes that file on sync and
         // `hookSurface: "limited"` records the reality: SessionStart /
@@ -113,7 +134,7 @@ export const HARNESS_ADAPTERS = {
         commandDir: ".agents/skills",
         shimKind: "skill",
         capabilities: {
-            nativeSubagentDispatch: "none",
+            nativeSubagentDispatch: "full",
             hookSurface: "limited",
             // Codex CLI exposes `request_user_input` — an experimental tool
             // that asks 1-3 short questions and returns the user's answers.
@@ -123,10 +144,29 @@ export const HARNESS_ADAPTERS = {
             // it into generated harness guidance. The shared plain-text
             // lettered list is the documented fallback when the tool is unavailable.
             structuredAsk: "request_user_input",
-            subagentFallback: "role-switch"
+            subagentFallback: "native"
         }
     }
 };
+export function harnessDispatchSurface(harnessId) {
+    switch (harnessId) {
+        case "claude":
+            return "Use Claude Code Task with the cclaw agent name as subagent_type; record fulfillmentMode: \"isolated\".";
+        case "cursor":
+            return "Use Cursor Subagent/Task with a generic subagent_type (explore for read-only mapping, generalPurpose for broader work, shell/browser-use when specifically needed) and paste the cclaw role prompt; record fulfillmentMode: \"generic-dispatch\" with evidenceRefs.";
+        case "opencode":
+            return "Use OpenCode subagents: invoke the generated .opencode/agents/<agent>.md agent via Task or @<agent>, run independent agents in parallel when safe, then record fulfillmentMode: \"isolated\".";
+        case "codex":
+            return "Use Codex native subagents: ask Codex to spawn the generated .codex/agents/<agent>.toml agent(s) by name, wait for all results, then record fulfillmentMode: \"isolated\".";
+    }
+}
+export function harnessDispatchFallback(harnessId) {
+    const adapter = HARNESS_ADAPTERS[harnessId];
+    if (adapter.capabilities.subagentFallback !== "role-switch") {
+        return "Role-switch is only a degradation path if the active runtime cannot expose the declared dispatch surface; include non-empty evidenceRefs when used.";
+    }
+    return "Use a visible role-switch pass with non-empty evidenceRefs because this harness has no true dispatch surface.";
+}
 export function harnessTier(harnessId) {
     const capabilities = HARNESS_ADAPTERS[harnessId].capabilities;
     if (capabilities.nativeSubagentDispatch === "full" &&
@@ -223,7 +263,7 @@ If the same approach fails three times in a row (same command, same finding, sam
 ### Detail Level
 
 - This managed AGENTS block is intentionally minimal for cross-project use.
-- Harness coverage is tiered: Tier1 (claude), Tier2 (cursor/opencode/codex — codex has Bash-only tool hooks), Tier3 (fallback/manual-only).
+- Subagent dispatch coverage: Claude/OpenCode/Codex support native isolated workers; Cursor uses generic Task dispatch. Codex still has Bash-only tool hooks.
 - Detailed operating procedures live in \`.cclaw/skills/using-cclaw/SKILL.md\`.
 - Keep preambles brief; re-announce role/stage only when either changes.
 - Subagent orchestration patterns: \`.cclaw/skills/subagent-dev/SKILL.md\` and \`.cclaw/skills/parallel-dispatch/SKILL.md\`.
@@ -336,6 +376,50 @@ Load and execute:
 ${utilityShimBehavior(command)}
 `;
 }
+function stageShimContent(harness, stage) {
+    const shimName = stageShimSkillName(stage);
+    const skillPath = `${RUNTIME_ROOT}/skills/${STAGE_TO_SKILL_FOLDER[stage]}/SKILL.md`;
+    return `---
+name: ${shimName}
+description: Generated shim for ${harness}. Flow stage pointer; normal advancement uses /cc-next.
+source: generated-by-cclaw
+---
+
+# cclaw ${stage}
+
+This is a thin compatibility shim for the \`${stage}\` flow stage.
+
+Load and follow the authoritative stage skill:
+
+- \`${skillPath}\`
+
+Normal stage resume and advancement uses \`/cc-next\`. Use \`/cc-next\` to read
+\`.cclaw/state/flow-state.json\`, select the active stage, and advance only after
+that stage's gates pass. Do not duplicate the stage protocol here.
+`;
+}
+function codexStageSkillMarkdown(stage) {
+    const skillName = stageShimSkillName(stage);
+    const skillPath = `${RUNTIME_ROOT}/skills/${STAGE_TO_SKILL_FOLDER[stage]}/SKILL.md`;
+    return `---
+name: ${skillName}
+description: Thin cclaw stage shim for /cc-${stage}. Load ${skillPath}; normal stage resume and advancement uses /cc-next.
+source: generated-by-cclaw
+---
+
+# cclaw /cc-${stage} (Codex adapter)
+
+This is a thin compatibility shim for the \`${stage}\` flow stage.
+
+Load and follow the authoritative stage skill:
+
+- \`${skillPath}\`
+
+Normal stage resume and advancement uses \`/cc-next\`. Use \`/cc-next\` to read
+\`.cclaw/state/flow-state.json\`, select the active stage, and advance only after
+that stage's gates pass. Do not duplicate the stage protocol here.
+`;
+}
 /**
  * Frontmatter `description` that triggers the skill when the user types any
  * of the classic cclaw slash-tokens. Codex's skill matcher runs on the skill
@@ -398,11 +482,12 @@ for the current hook surface and limitations.
 
 ## Honest caveats
 
-- Codex has no subagent dispatch primitive. Mandatory delegations
-  fall back to **role-switch** — announce the role, act in-session,
-  append a completed row with \`evidenceRefs\` to
-  \`.cclaw/state/delegation-log.json\`. Silent auto-waiver is disabled
-  (v0.33+).
+- Codex has native parallel subagents. cclaw writes project custom agents
+  under \`.codex/agents/*.toml\`; ask Codex to spawn the relevant cclaw
+  agent(s) by name, wait for their results, write evidence into the active
+  artifact, then append completed delegation rows with \`fulfillmentMode:
+  "isolated"\`. Use role-switch only if this Codex build has subagents
+  unavailable or disabled, and then include non-empty \`evidenceRefs\`.
 - Codex's \`PreToolUse\` / \`PostToolUse\` hooks currently only intercept
   the \`Bash\` tool. \`Write\`, \`Edit\`, \`WebSearch\`, and MCP tool calls
   are **not** gated by hooks — use \`cclaw doctor --explain\` for what cclaw
@@ -432,6 +517,9 @@ async function writeCommandKindShims(commandDir, harness) {
     for (const shim of UTILITY_SHIMS) {
         await writeFileSafe(path.join(commandDir, shim.fileName), utilityShimContent(harness, shim.command, shim.skillFolder, shim.commandFile));
     }
+    for (const stage of FLOW_STAGES) {
+        await writeFileSafe(path.join(commandDir, stageShimFileName(stage)), stageShimContent(harness, stage));
+    }
     for (const legacy of LEGACY_HARNESS_SHIMS) {
         const legacyPath = path.join(commandDir, legacy);
         try {
@@ -448,6 +536,9 @@ async function writeSkillKindShims(commandDir) {
     for (const shim of UTILITY_SHIMS) {
         await writeFileSafe(path.join(commandDir, shim.skillName, "SKILL.md"), codexSkillMarkdown(shim.command, shim.skillName, shim.skillFolder, shim.commandFile));
     }
+    for (const stage of FLOW_STAGES) {
+        await writeFileSafe(path.join(commandDir, stageShimSkillName(stage), "SKILL.md"), codexStageSkillMarkdown(stage));
+    }
 }
 /**
  * Legacy codex surfaces cclaw wrote before v0.39.0 that Codex CLI never
@@ -505,12 +596,57 @@ async function cleanupLegacyCodexSurfaces(projectRoot) {
         // directory absent or non-empty
     }
 }
-async function syncAgentFiles(projectRoot) {
+function codexAgentToml(agent) {
+    const instructions = `${agent.body}\n\n${enhancedAgentInstruction(agent.name)}`.trim();
+    const sandboxMode = agent.tools.some((tool) => ["Write", "Edit", "Bash"].includes(tool))
+        ? "workspace-write"
+        : "read-only";
+    return [
+        `name = ${JSON.stringify(agent.name)}`,
+        `description = ${JSON.stringify(agent.description)}`,
+        `sandbox_mode = ${JSON.stringify(sandboxMode)}`,
+        'developer_instructions = """',
+        instructions.replace(/"""/gu, '\"\"\"'),
+        '"""',
+        ""
+    ].join("\n");
+}
+function opencodeAgentMarkdown(agent) {
+    const editPermission = agent.tools.some((tool) => ["Write", "Edit"].includes(tool)) ? "ask" : "deny";
+    const bashPermission = agent.tools.includes("Bash") ? "ask" : "deny";
+    return `---
+description: ${JSON.stringify(agent.description)}
+mode: subagent
+permission:
+  edit: ${editPermission}
+  bash: ${bashPermission}
+---
+
+${agentMarkdown(agent)}`;
+}
+function enhancedAgentInstruction(agentName) {
+    return `You are the cclaw ${agentName} subagent. Follow the parent prompt as the task boundary, produce evidence suitable for .cclaw/state/delegation-log.json, and do not recursively orchestrate other agents unless the parent explicitly asks.`;
+}
+async function syncAgentFiles(projectRoot, harnesses) {
     const agentsDir = path.join(projectRoot, RUNTIME_ROOT, "agents");
     await ensureDir(agentsDir);
     for (const agent of CCLAW_AGENTS) {
         await writeFileSafe(path.join(agentsDir, `${agent.name}.md`), agentMarkdown(agent));
     }
+    if (harnesses.includes("opencode")) {
+        const opencodeAgentsDir = path.join(projectRoot, ".opencode/agents");
+        await ensureDir(opencodeAgentsDir);
+        for (const agent of CCLAW_AGENTS) {
+            await writeFileSafe(path.join(opencodeAgentsDir, `${agent.name}.md`), opencodeAgentMarkdown(agent));
+        }
+    }
+    if (harnesses.includes("codex")) {
+        const codexAgentsDir = path.join(projectRoot, ".codex/agents");
+        await ensureDir(codexAgentsDir);
+        for (const agent of CCLAW_AGENTS) {
+            await writeFileSafe(path.join(codexAgentsDir, `${agent.name}.toml`), codexAgentToml(agent));
+        }
+    }
 }
 export async function syncHarnessShims(projectRoot, harnesses) {
     // Legacy codex cleanup is unconditional — even installs that never enabled
@@ -529,6 +665,6 @@ export async function syncHarnessShims(projectRoot, harnesses) {
             await writeCommandKindShims(commandDir, harness);
         }
     }
-    await syncAgentFiles(projectRoot);
+    await syncAgentFiles(projectRoot, harnesses);
     await syncAgentsMd(projectRoot, harnesses);
 }

package/dist/install.js

@@ -6,6 +6,7 @@ import { CCLAW_VERSION, FLOW_VERSION, REQUIRED_DIRS, RUNTIME_ROOT } from "./cons
 import { writeConfig, createDefaultConfig, readConfig, configPath, detectLanguageRulePacks, detectAdvancedKeys } from "./config.js";
 import { learnSkillMarkdown } from "./content/learnings.js";
 import { nextCommandContract, nextCommandSkillMarkdown } from "./content/next-command.js";
+import { stageCommandShimMarkdown } from "./content/stage-command.js";
 import { ideateCommandContract, ideateCommandSkillMarkdown } from "./content/ideate-command.js";
 import { startCommandContract, startCommandSkillMarkdown } from "./content/start-command.js";
 import { viewCommandContract, viewCommandSkillMarkdown } from "./content/view-command.js";
@@ -443,6 +444,9 @@ async function writeEntryCommands(projectRoot) {
     await writeFileSafe(runtimePath(projectRoot, "commands", "next.md"), nextCommandContract());
     await writeFileSafe(runtimePath(projectRoot, "commands", "ideate.md"), ideateCommandContract());
     await writeFileSafe(runtimePath(projectRoot, "commands", "view.md"), viewCommandContract());
+    for (const stage of FLOW_STAGES) {
+        await writeFileSafe(runtimePath(projectRoot, "commands", `${stage}.md`), stageCommandShimMarkdown(stage));
+    }
 }
 function toObject(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -547,11 +551,20 @@ function mergeOpenCodePluginConfig(existingDoc, pluginRelPath) {
     if (!normalized.has(pluginRelPath)) {
         pluginsRaw.push(pluginRelPath);
     }
-    const changed = !normalized.has(pluginRelPath) || !Array.isArray(root.plugin);
+    const permission = toObject(root.permission) ?? {};
+    const permissionChanged = permission.question !== "allow";
+    const changed = !normalized.has(pluginRelPath) ||
+        !Array.isArray(root.plugin) ||
+        permissionChanged ||
+        !toObject(root.permission);
     return {
         merged: {
             ...root,
-            plugin: pluginsRaw
+            plugin: pluginsRaw,
+            permission: {
+                ...permission,
+                question: "allow"
+            }
         },
         changed
     };
@@ -933,7 +946,6 @@ async function cleanLegacyArtifacts(projectRoot) {
         await removeBestEffort(legacyPlugin);
     }
     for (const legacyRuntimeFile of [
-        ...FLOW_STAGES.map((stage) => runtimePath(projectRoot, "commands", `${stage}.md`)),
         ...DEPRECATED_COMMAND_FILES.map((file) => runtimePath(projectRoot, "commands", file)),
         ...DEPRECATED_SKILL_FILES.map((segments) => runtimePath(projectRoot, "skills", ...segments)),
         ...DEPRECATED_STATE_FILES.map((file) => runtimePath(projectRoot, "state", file)),
@@ -1248,7 +1260,7 @@ export async function uninstallCclaw(projectRoot) {
     try {
         const entries = await fs.readdir(codexSkillsRoot);
         for (const entry of entries) {
-            if (/^(?:cclaw-)?cc(?:-(?:next|view|ops|ideate))?$/u.test(entry)) {
+            if (/^(?:cclaw-)?cc(?:-(?:next|view|ops|ideate|brainstorm|scope|design|spec|plan|tdd|review|ship))?$/u.test(entry)) {
                 await fs.rm(path.join(codexSkillsRoot, entry), { recursive: true, force: true });
             }
         }
@@ -1258,6 +1270,17 @@ export async function uninstallCclaw(projectRoot) {
     }
     await removeIfEmpty(codexSkillsRoot);
     await removeIfEmpty(path.join(projectRoot, ".agents"));
+    const managedAgentNames = [
+        "planner",
+        "reviewer",
+        "security-reviewer",
+        "test-author",
+        "doc-updater"
+    ];
+    for (const agentName of managedAgentNames) {
+        await removeBestEffort(path.join(projectRoot, ".opencode/agents", `${agentName}.md`));
+        await removeBestEffort(path.join(projectRoot, ".codex/agents", `${agentName}.toml`));
+    }
     for (const pluginPath of [
         path.join(projectRoot, ".opencode/plugins/viby-plugin.mjs"),
         path.join(projectRoot, ".opencode/plugins/opencode-plugin.mjs"),
@@ -1284,8 +1307,10 @@ export async function uninstallCclaw(projectRoot) {
         ".cursor/rules",
         ".cursor/commands",
         ".cursor",
+        ".codex/agents",
         ".codex/commands",
         ".codex",
+        ".opencode/agents",
         ".opencode/plugins",
         ".opencode/commands",
         ".opencode"

package/package.json

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