cclaw-cli 0.51.21 → 0.51.23

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" &&
@@ -134,11 +174,7 @@ export function harnessTier(harnessId) {
         capabilities.hookSurface === "full") {
         return "tier1";
     }
-    if (capabilities.hookSurface === "full" ||
-        capabilities.hookSurface === "plugin" ||
-        capabilities.hookSurface === "limited" ||
-        capabilities.nativeSubagentDispatch === "generic" ||
-        capabilities.nativeSubagentDispatch === "partial") {
+    if (capabilities.hookSurface !== "none" || capabilities.nativeSubagentDispatch !== "none") {
         return "tier2";
     }
     return "tier3";
@@ -227,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\`.
@@ -340,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
@@ -402,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
@@ -436,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 {
@@ -452,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
@@ -509,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
@@ -533,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";
@@ -34,10 +35,17 @@ const OPENCODE_PLUGIN_REL_PATH = ".opencode/plugins/cclaw-plugin.mjs";
 const CURSOR_RULE_REL_PATH = ".cursor/rules/cclaw-workflow.mdc";
 const GIT_HOOK_MANAGED_MARKER = "cclaw-managed-git-hook";
 const GIT_HOOK_RUNTIME_REL_DIR = `${RUNTIME_ROOT}/hooks/git`;
+const INIT_SENTINEL_FILE = ".init-in-progress";
 const execFileAsync = promisify(execFile);
 function runtimePath(projectRoot, ...segments) {
     return path.join(projectRoot, RUNTIME_ROOT, ...segments);
 }
+async function writeInitSentinel(projectRoot, operation) {
+    const sentinelPath = runtimePath(projectRoot, "state", INIT_SENTINEL_FILE);
+    await ensureDir(path.dirname(sentinelPath));
+    await writeFileSafe(sentinelPath, `${JSON.stringify({ operation, startedAt: new Date().toISOString() }, null, 2)}\n`);
+    return sentinelPath;
+}
 async function removeBestEffort(targetPath, recursive = false) {
     try {
         await fs.rm(targetPath, { recursive, force: true });
@@ -436,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)) {
@@ -540,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
     };
@@ -653,6 +673,54 @@ async function backupHookFile(projectRoot, hookFilePath, rawContent) {
     await pruneOldHookBackups(backupsDir);
     return backupPath;
 }
+function normalizeHookCommandForDedupe(command) {
+    return command.trim().replace(/\s+/gu, " ").replace(/\\/gu, "/");
+}
+function dedupeHookEntryByCommand(entry, seenCommands) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        return entry;
+    }
+    const obj = entry;
+    let changed = false;
+    if (typeof obj.command === "string") {
+        const normalized = normalizeHookCommandForDedupe(obj.command);
+        if (seenCommands.has(normalized)) {
+            return undefined;
+        }
+        seenCommands.add(normalized);
+    }
+    if (Array.isArray(obj.hooks)) {
+        const hooks = [];
+        for (const nested of obj.hooks) {
+            const deduped = dedupeHookEntryByCommand(nested, seenCommands);
+            if (deduped !== undefined) {
+                hooks.push(deduped);
+            }
+            else {
+                changed = true;
+            }
+        }
+        if (hooks.length !== obj.hooks.length) {
+            changed = true;
+        }
+        if (hooks.length === 0 && typeof obj.command !== "string") {
+            return undefined;
+        }
+        return changed ? { ...obj, hooks } : entry;
+    }
+    return entry;
+}
+function dedupeHookEntriesByCommand(entries) {
+    const seenCommands = new Set();
+    const deduped = [];
+    for (const entry of entries) {
+        const next = dedupeHookEntryByCommand(entry, seenCommands);
+        if (next !== undefined) {
+            deduped.push(next);
+        }
+    }
+    return deduped;
+}
 function mergeHookDocuments(existingDoc, generatedDoc) {
     const generatedRoot = toObject(generatedDoc) ?? {};
     const generatedHooks = toObject(generatedRoot.hooks) ?? {};
@@ -664,7 +732,7 @@ function mergeHookDocuments(existingDoc, generatedDoc) {
         const existingEntries = existingHooks[eventName];
         if (Array.isArray(generatedEntries)) {
             const preservedEntries = Array.isArray(existingEntries) ? existingEntries : [];
-            mergedHooks[eventName] = [...generatedEntries, ...preservedEntries];
+            mergedHooks[eventName] = dedupeHookEntriesByCommand([...generatedEntries, ...preservedEntries]);
             continue;
         }
         // Defensive: malformed generated event payload must not wipe user hooks.
@@ -878,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)),
@@ -944,26 +1011,34 @@ async function cleanStaleFiles(projectRoot) {
     // Keep user-owned custom assets under .cclaw/agents and .cclaw/skills.
     // Legacy managed removals happen in cleanLegacyArtifacts() with explicit paths.
 }
-async function materializeRuntime(projectRoot, config, forceStateReset) {
-    const harnesses = config.harnesses;
-    await ensureStructure(projectRoot);
-    await cleanLegacyArtifacts(projectRoot);
-    await cleanStaleFiles(projectRoot);
-    await Promise.all([
-        writeEntryCommands(projectRoot),
-        writeSkills(projectRoot, config),
-        writeArtifactTemplates(projectRoot),
-        writeRulebook(projectRoot)
-    ]);
-    await writeState(projectRoot, config, forceStateReset);
-    await ensureRunSystem(projectRoot, { createIfMissing: false });
-    await ensureKnowledgeStore(projectRoot);
-    await writeHooks(projectRoot, config);
-    await syncDisabledHarnessArtifacts(projectRoot, harnesses);
-    await syncManagedGitHooks(projectRoot, config);
-    await syncHarnessShims(projectRoot, harnesses);
-    await writeCursorWorkflowRule(projectRoot, harnesses);
-    await ensureGitignore(projectRoot);
+async function materializeRuntime(projectRoot, config, forceStateReset, operation = "sync") {
+    const sentinelPath = await writeInitSentinel(projectRoot, operation);
+    try {
+        const harnesses = config.harnesses;
+        await ensureStructure(projectRoot);
+        await cleanLegacyArtifacts(projectRoot);
+        await cleanStaleFiles(projectRoot);
+        await Promise.all([
+            writeEntryCommands(projectRoot),
+            writeSkills(projectRoot, config),
+            writeArtifactTemplates(projectRoot),
+            writeRulebook(projectRoot)
+        ]);
+        await writeState(projectRoot, config, forceStateReset);
+        await ensureRunSystem(projectRoot, { createIfMissing: false });
+        await ensureKnowledgeStore(projectRoot);
+        await writeHooks(projectRoot, config);
+        await syncDisabledHarnessArtifacts(projectRoot, harnesses);
+        await syncManagedGitHooks(projectRoot, config);
+        await syncHarnessShims(projectRoot, harnesses);
+        await writeCursorWorkflowRule(projectRoot, harnesses);
+        await ensureGitignore(projectRoot);
+        await fs.unlink(sentinelPath).catch(() => undefined);
+    }
+    catch (error) {
+        // Leave the sentinel in place so doctor can surface the interrupted run.
+        throw error;
+    }
 }
 export async function initCclaw(options) {
     const baseConfig = createDefaultConfig(options.harnesses, options.track);
@@ -978,7 +1053,7 @@ export async function initCclaw(options) {
     // and only appear in the on-disk file when the user sets them explicitly
     // or a non-default value was detected (e.g. languageRulePacks).
     await writeConfig(options.projectRoot, config, { mode: "minimal" });
-    await materializeRuntime(options.projectRoot, config, true);
+    await materializeRuntime(options.projectRoot, config, true, "init");
 }
 export async function syncCclaw(projectRoot) {
     const configExists = await exists(configPath(projectRoot));
@@ -996,7 +1071,7 @@ export async function syncCclaw(projectRoot) {
         await writeConfig(projectRoot, defaultConfig);
         config = defaultConfig;
     }
-    await materializeRuntime(projectRoot, config, false);
+    await materializeRuntime(projectRoot, config, false, "sync");
 }
 /**
  * Refresh generated files in `.cclaw/` without touching user-authored
@@ -1020,7 +1095,7 @@ export async function upgradeCclaw(projectRoot) {
         mode: "minimal",
         advancedKeysPresent
     });
-    await materializeRuntime(projectRoot, upgraded, false);
+    await materializeRuntime(projectRoot, upgraded, false, "upgrade");
 }
 function stripManagedHookCommands(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -1185,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 });
             }
         }
@@ -1195,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"),
@@ -1221,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"