cclaw-cli 0.51.22 → 0.51.24

package/dist/doctor.js

@@ -18,11 +18,13 @@ 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";
 import { LANGUAGE_RULE_PACK_DIR, LANGUAGE_RULE_PACK_FILES, LEGACY_LANGUAGE_RULE_PACK_FOLDERS } from "./content/utility-skills.js";
 import { validateHookDocument } from "./hook-schema.js";
+import { HOOK_EVENTS_BY_HARNESS } from "./content/hook-events.js";
 import { validateKnowledgeEntry } from "./knowledge-store.js";
 import { readSeedShelf } from "./content/seed-shelf.js";
 import { evaluateRetroGate } from "./retro-gate.js";
@@ -289,17 +291,27 @@ 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, "oh-my-opencode.jsonc"),
+        path.join(projectRoot, "oh-my-openagent.jsonc"),
         path.join(projectRoot, ".opencode/opencode.json"),
-        path.join(projectRoot, ".opencode/opencode.jsonc")
+        path.join(projectRoot, ".opencode/opencode.jsonc"),
+        path.join(projectRoot, ".opencode/oh-my-opencode.jsonc"),
+        path.join(projectRoot, ".opencode/oh-my-openagent.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 +321,130 @@ 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."
+    };
+}
+function codexFlagInactiveDetail(configPath, state, error) {
+    if (state === "enabled") {
+        return `codex_hooks feature flag is enabled in ${configPath}; Codex hooks are active.`;
+    }
+    if (state === "read-error") {
+        return `Codex hooks are inactive: could not read ${configPath} (${error instanceof Error ? error.message : String(error)}).`;
+    }
+    if (state === "missing-file") {
+        return `Codex hooks are inactive: ${configPath} does not exist; .codex/hooks.json is ignored until [features] codex_hooks = true is configured.`;
+    }
+    if (state === "missing-section") {
+        return `Codex hooks are inactive: ${configPath} has no [features] section; add codex_hooks = true to activate configured hooks.`;
+    }
+    if (state === "missing-key") {
+        return `Codex hooks are inactive: ${configPath} is missing codex_hooks under [features]; add codex_hooks = true to activate configured hooks.`;
+    }
+    return `Codex hooks are inactive: ${configPath} sets codex_hooks to a non-true value; set codex_hooks = true under [features].`;
+}
+function hookCommandsWithMatchers(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const out = [];
+    for (const item of value) {
+        const obj = toObject(item);
+        if (!obj)
+            continue;
+        const matcher = typeof obj.matcher === "string" ? obj.matcher : undefined;
+        if (typeof obj.command === "string") {
+            out.push({ command: obj.command, matcher });
+        }
+        const nested = hookCommandsWithMatchers(obj.hooks);
+        for (const child of nested) {
+            out.push({ ...child, matcher: child.matcher ?? matcher });
+        }
+    }
+    return out;
+}
+function commandHasHandler(entries, handler) {
+    return entries.some((entry) => entry.command.includes(`run-hook.cmd ${handler}`) || entry.command.includes(`run-hook.mjs ${handler}`));
+}
+function codexBashOnly(entries, handler) {
+    const matches = entries.filter((entry) => entry.command.includes(`run-hook.cmd ${handler}`) || entry.command.includes(`run-hook.mjs ${handler}`));
+    return matches.length > 0 && matches.every((entry) => entry.matcher === "Bash|bash");
+}
+function codexStructuralWiringCheck(codexHooks) {
+    const problems = [];
+    const expectedSession = HOOK_EVENTS_BY_HARNESS.codex.session_rehydrate;
+    if (expectedSession !== "SessionStart matcher=startup|resume") {
+        problems.push("semantic session_rehydrate mapping must remain SessionStart matcher=startup|resume");
+    }
+    const session = hookCommandsWithMatchers(codexHooks.SessionStart);
+    if (!commandHasHandler(session, "session-start") || !session.some((entry) => entry.matcher === "startup|resume")) {
+        problems.push("SessionStart must run session-start with matcher startup|resume");
+    }
+    const userPrompt = hookCommandsWithMatchers(codexHooks.UserPromptSubmit);
+    if (!commandHasHandler(userPrompt, "prompt-guard")) {
+        problems.push("UserPromptSubmit must run prompt-guard");
+    }
+    if (!commandHasHandler(userPrompt, "verify-current-state")) {
+        problems.push("UserPromptSubmit must run verify-current-state");
+    }
+    const pre = hookCommandsWithMatchers(codexHooks.PreToolUse);
+    if (!codexBashOnly(pre, "prompt-guard")) {
+        problems.push("PreToolUse prompt-guard must be Bash-only matcher Bash|bash");
+    }
+    if (!codexBashOnly(pre, "workflow-guard")) {
+        problems.push("PreToolUse workflow-guard must be Bash-only matcher Bash|bash");
+    }
+    const post = hookCommandsWithMatchers(codexHooks.PostToolUse);
+    if (!codexBashOnly(post, "context-monitor")) {
+        problems.push("PostToolUse context-monitor must be Bash-only matcher Bash|bash");
+    }
+    const stop = hookCommandsWithMatchers(codexHooks.Stop);
+    if (!commandHasHandler(stop, "stop-handoff")) {
+        problems.push("Stop must run stop-handoff");
+    }
+    return problems.length === 0
+        ? { ok: true, details: "Codex hook events, matchers, and manifest semantic mappings are structurally valid" }
+        : { ok: false, details: problems.join("; ") };
 }
 async function initRecoveryCheck(projectRoot) {
     const sentinelPath = path.join(projectRoot, RUNTIME_ROOT, "state", ".init-in-progress");
@@ -667,7 +792,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 +800,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 +1079,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,36 +1087,50 @@ 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.`
+        });
+        const codexStructural = codexStructuralWiringCheck(codexHooks);
+        checks.push({
+            name: "hook:wiring:codex:structure",
+            ok: codexStructural.ok,
+            details: codexStructural.details
         });
-        // Feature flag warning: Codex ignores `.codex/hooks.json` unless the
-        // user has `[features] codex_hooks = true` in `~/.codex/config.toml`.
-        // Advisory warning — not a hard failure, because the skills still
-        // work without the flag.
+        // Codex ignores `.codex/hooks.json` unless the user has
+        // `[features] codex_hooks = true` in `~/.codex/config.toml`.
         const codexConfig = codexConfigPath();
-        let featureFlagNote = "";
+        let codexFlagState = "read-error";
+        let codexFlagReadError;
         try {
             const content = await readCodexConfig(codexConfig);
-            const state = classifyCodexHooksFlag(content);
-            featureFlagNote =
-                state === "enabled"
-                    ? `codex_hooks feature flag is enabled in ${codexConfig}`
-                    : state === "missing-file"
-                        ? `warning: ${codexConfig} does not exist; .codex/hooks.json will be ignored until you create it with \`[features]\\ncodex_hooks = true\\n\`.`
-                        : state === "missing-section"
-                            ? `warning: ${codexConfig} has no [features] section; add \`[features]\\ncodex_hooks = true\\n\` to enable cclaw hooks.`
-                            : state === "missing-key"
-                                ? `warning: ${codexConfig} is missing the codex_hooks key under [features]. Add \`codex_hooks = true\` to enable cclaw hooks.`
-                                : `warning: ${codexConfig} sets codex_hooks to a non-true value; set \`codex_hooks = true\` under [features] to enable cclaw hooks.`;
+            codexFlagState = classifyCodexHooksFlag(content);
         }
         catch (err) {
-            featureFlagNote = `warning: could not read ${codexConfig}: ${err instanceof Error ? err.message : String(err)}`;
+            codexFlagReadError = err;
         }
+        const featureFlagNote = codexFlagInactiveDetail(codexConfig, codexFlagState, codexFlagReadError);
+        const featureFlagOk = codexFlagState === "enabled";
         checks.push({
             name: "warning:codex:feature_flag",
-            ok: true,
-            details: featureFlagNote
+            ok: featureFlagOk,
+            details: featureFlagNote,
+            summary: featureFlagOk
+                ? "Codex hooks are active."
+                : "Codex hooks are inactive; configured hooks will be ignored.",
+            fix: "Set `[features] codex_hooks = true` in the Codex config or run cclaw init/sync with Codex flag repair.",
+            docRef: "docs/harnesses.md"
         });
+        if (parsedConfig?.strictness === "strict") {
+            checks.push({
+                name: "hook:codex:feature_flag_active",
+                ok: featureFlagOk,
+                details: featureFlagNote,
+                summary: featureFlagOk
+                    ? "Codex hooks are active for strict runtime enforcement."
+                    : "Codex hooks are inactive; strict Codex hook enforcement is not ready.",
+                fix: "Set `[features] codex_hooks = true` in the Codex config so strict Codex hooks can run.",
+                docRef: "docs/harnesses.md"
+            });
+        }
         // Legacy `.codex/commands/*` must not linger from older cclaw installs.
         // (The `.codex/hooks.json` path is now managed and is validated above,
         // so there is no longer a legacy_hooks_json warning.)
@@ -1074,6 +1224,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/flow-state.d.ts

@@ -63,6 +63,7 @@ export interface CloseoutState {
     retroSkipReason?: string;
     compoundCompletedAt?: string;
     compoundSkipped?: boolean;
+    compoundSkipReason?: string;
     compoundPromoted: number;
 }
 export declare function createInitialCloseoutState(): CloseoutState;

package/dist/flow-state.js

@@ -42,6 +42,7 @@ export function createInitialCloseoutState() {
         retroSkipReason: undefined,
         compoundCompletedAt: undefined,
         compoundSkipped: undefined,
+        compoundSkipReason: undefined,
         compoundPromoted: 0
     };
 }

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);
 }