cclaw-cli 7.7.1 → 8.1.0

package/dist/codex-feature-flag.js

@@ -1,193 +0,0 @@
-/**
- * Manage the `codex_hooks` feature flag in `~/.codex/config.toml`.
- *
- * Codex CLI ≥ v0.114 (Mar 2026) exposes lifecycle hooks via
- * `.codex/hooks.json`, but the hooks engine is inert unless the user has
- * opted into it with:
- *
- * ```toml
- * [features]
- * codex_hooks = true
- * ```
- *
- * in `$CODEX_HOME/config.toml` (default: `~/.codex/config.toml`).
- * cclaw init/sync can prompt the user to flip this flag for them; sync/runtime diagnostics report the concrete repair when it is missing;
- * this module owns the detection / mutation code so the prompt logic in
- * `cli.ts` stays small and testable.
- *
- * The TOML mutations here are intentionally surgical — we never reparse
- * or rewrite the whole document. A deliberately narrow regex based
- * approach lets the function stay dependency-free and preserves the
- * user's comments, whitespace, and custom key ordering.
- */
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-/**
- * Absolute path of the Codex config file. Respects `$CODEX_HOME` when
- * present (the only override Codex CLI documents); falls back to
- * `~/.codex/config.toml` otherwise.
- */
-export function codexConfigPath(env = process.env) {
-    const codexHome = env.CODEX_HOME && env.CODEX_HOME.trim().length > 0
-        ? env.CODEX_HOME
-        : path.join(os.homedir(), ".codex");
-    return path.join(codexHome, "config.toml");
-}
-/**
- * Inspect a TOML document and decide which of the five canonical states
- * it represents. Comments and blank lines are ignored. Only the first
- * `[features]` section is considered — duplicates are technically invalid
- * TOML and Codex rejects them, so cclaw does not try to be clever there.
- */
-export function classifyCodexHooksFlag(toml) {
-    if (toml === null) {
-        return "missing-file";
-    }
-    const lines = toml.split(/\r?\n/);
-    let inFeaturesSection = false;
-    let sawFeaturesHeader = false;
-    for (const rawLine of lines) {
-        const stripped = stripTomlComment(rawLine).trim();
-        if (stripped.length === 0)
-            continue;
-        const headerMatch = /^\[\s*([A-Za-z0-9_.-]+)\s*\]$/u.exec(stripped);
-        if (headerMatch) {
-            const section = headerMatch[1];
-            if (section === "features") {
-                inFeaturesSection = true;
-                sawFeaturesHeader = true;
-            }
-            else {
-                inFeaturesSection = false;
-            }
-            continue;
-        }
-        if (inFeaturesSection) {
-            const keyMatch = /^codex_hooks\s*=\s*(.*)$/u.exec(stripped);
-            if (keyMatch) {
-                const value = keyMatch[1].trim().toLowerCase();
-                return value === "true" ? "enabled" : "disabled";
-            }
-        }
-    }
-    if (sawFeaturesHeader)
-        return "missing-key";
-    return "missing-section";
-}
-function stripTomlComment(line) {
-    // Naive but sufficient for our narrow use case: we only read cclaw's
-    // own writes back, and cclaw never emits `=` after a `#` inside a
-    // string literal in config.toml. If a user has complex string values
-    // with `#` inside them, worst case we trip `classifyCodexHooksFlag`
-    // and prompt them again — non-destructive.
-    const hashIndex = line.indexOf("#");
-    return hashIndex === -1 ? line : line.slice(0, hashIndex);
-}
-/**
- * Return a TOML document with `[features] codex_hooks = true` set.
- * Preserves all other content verbatim:
- *   - If the document lacks a `[features]` section, we append one at the
- *     end of the file (separated by a blank line).
- *   - If `[features]` exists without `codex_hooks`, we insert the key
- *     immediately after the header.
- *   - If `codex_hooks` exists with any non-`true` value, we rewrite
- *     just that line.
- *   - If the flag is already `true`, the input is returned unchanged.
- */
-export function patchCodexHooksFlag(toml) {
-    const initial = toml ?? "";
-    const state = classifyCodexHooksFlag(toml);
-    if (state === "enabled") {
-        return { updated: initial, changed: false };
-    }
-    if (state === "missing-file" || state === "missing-section") {
-        const prefix = initial.length === 0
-            ? ""
-            : initial.endsWith("\n") ? initial : `${initial}\n`;
-        const separator = initial.trim().length === 0 ? "" : "\n";
-        const block = `${separator}[features]\ncodex_hooks = true\n`;
-        return { updated: `${prefix}${block}`, changed: true };
-    }
-    if (state === "missing-key") {
-        const updated = insertKeyInFeaturesSection(initial);
-        return { updated, changed: true };
-    }
-    const updated = replaceCodexHooksLineInFeaturesSection(initial);
-    return { updated, changed: true };
-}
-function insertKeyInFeaturesSection(toml) {
-    // Walk into `[features]`, remember the index of the last key / non-blank
-    // line inside that section, and splice `codex_hooks = true` immediately
-    // after it. This keeps the inserted key adjacent to existing features,
-    // never stranded after a blank line or pushed down past a later section
-    // header. If `[features]` is empty, we insert right after its header.
-    const lines = toml.split(/\r?\n/);
-    let inFeaturesSection = false;
-    let featuresHeaderIndex = -1;
-    let lastFeatureKeyIndex = -1;
-    for (let index = 0; index < lines.length; index += 1) {
-        const rawLine = lines[index];
-        const stripped = stripTomlComment(rawLine).trim();
-        const headerMatch = /^\[\s*([A-Za-z0-9_.-]+)\s*\]$/u.exec(stripped);
-        if (headerMatch) {
-            if (inFeaturesSection)
-                break;
-            if (headerMatch[1] === "features") {
-                inFeaturesSection = true;
-                featuresHeaderIndex = index;
-                lastFeatureKeyIndex = index;
-            }
-            continue;
-        }
-        if (inFeaturesSection && stripped.length > 0) {
-            lastFeatureKeyIndex = index;
-        }
-    }
-    if (featuresHeaderIndex === -1) {
-        // caller should have short-circuited before getting here; defensive
-        return toml;
-    }
-    lines.splice(lastFeatureKeyIndex + 1, 0, "codex_hooks = true");
-    const joined = lines.join("\n");
-    return joined.endsWith("\n") ? joined : `${joined}\n`;
-}
-function replaceCodexHooksLineInFeaturesSection(toml) {
-    const lines = toml.split(/\r?\n/);
-    let inFeaturesSection = false;
-    for (let index = 0; index < lines.length; index += 1) {
-        const rawLine = lines[index];
-        const stripped = stripTomlComment(rawLine).trim();
-        const headerMatch = /^\[\s*([A-Za-z0-9_.-]+)\s*\]$/u.exec(stripped);
-        if (headerMatch) {
-            inFeaturesSection = headerMatch[1] === "features";
-            continue;
-        }
-        if (inFeaturesSection && /^codex_hooks\s*=/u.test(stripped)) {
-            const indent = /^\s*/u.exec(rawLine)?.[0] ?? "";
-            lines[index] = `${indent}codex_hooks = true`;
-        }
-    }
-    const joined = lines.join("\n");
-    return joined.endsWith("\n") ? joined : `${joined}\n`;
-}
-/**
- * Read the Codex config, return `null` when the file does not exist.
- * All other read errors propagate so callers can surface a useful
- * message instead of silently degrading.
- */
-export async function readCodexConfig(configPath) {
-    try {
-        return await fs.readFile(configPath, "utf8");
-    }
-    catch (err) {
-        if (err.code === "ENOENT") {
-            return null;
-        }
-        throw err;
-    }
-}
-export async function writeCodexConfig(configPath, content) {
-    await fs.mkdir(path.dirname(configPath), { recursive: true });
-    await fs.writeFile(configPath, content, "utf8");
-}

package/dist/content/closeout-guidance.d.ts

@@ -1,14 +0,0 @@
-/**
- * Shared post-ship closeout wording.
- *
- * Keep closeout chain and ship substate language in one place across command
- * contracts, skills, and stage/docs surfaces.
- */
-export declare const CLOSEOUT_CHAIN = "post_ship_review -> archive";
-export declare const CLOSEOUT_SUBSTATE_KEY = "closeout.shipSubstate";
-export declare function closeoutChainInline(): string;
-export declare function closeoutSubstateInline(): string;
-export declare function closeoutNextCommandGuidance(): string;
-export declare function closeoutSubstateProtocolBullets(): string;
-export declare function closeoutFlowMapSentence(): string;
-export declare function closeoutProtocolBehaviorSentence(): string;

package/dist/content/closeout-guidance.js

@@ -1,44 +0,0 @@
-/**
- * Shared post-ship closeout wording.
- *
- * Keep closeout chain and ship substate language in one place across command
- * contracts, skills, and stage/docs surfaces.
- */
-export const CLOSEOUT_CHAIN = "post_ship_review -> archive";
-export const CLOSEOUT_SUBSTATE_KEY = "closeout.shipSubstate";
-export function closeoutChainInline() {
-    return `\`${CLOSEOUT_CHAIN}\``;
-}
-export function closeoutSubstateInline() {
-    return `\`${CLOSEOUT_SUBSTATE_KEY}\``;
-}
-export function closeoutNextCommandGuidance() {
-    return `After ship completes, the closeout chain ${closeoutChainInline()} runs automatically, driven by ${closeoutSubstateInline()}. Continue through \`/cc\`; do not branch into \`ce:compound\`, a separate operations router, or a one-off closeout command. Ralph Loop may be mentioned only as tdd carry-forward context when it explains the next \`/cc\` move; it is not part of compound/archive routing.`;
-}
-export function closeoutSubstateProtocolBullets() {
-    return `When \`currentStage === "ship"\`, route by **${closeoutSubstateInline()}**:
-  - \`"idle"\` or missing -> outcome: initialize closeout by setting
-    ${closeoutSubstateInline()} = \`"post_ship_review"\`, then continue \`/cc\`
-    into the in-stage retro protocol (draft + one structured accept/edit/no changes ask).
-  - \`"post_ship_review"\` -> outcome: execute the unified post-ship closeout leg
-    (retro acceptance/edit/no changes + in-stage compound scan, not \`ce:compound\`)
-    and advance toward archive readiness:
-    read \`.cclaw/state/compound-readiness.json\` plus the relevant tail of
-    \`.cclaw/knowledge.jsonl\`, assess overlap before adding duplicate knowledge,
-    separate bug-track learnings (turn into rules/tests/remediation) from
-    knowledge-track learnings (durable project/process guidance), and refresh stale
-    guidance in place instead of introducing extra lineage metadata. Optionally ask
-    whether to scan Cursor/Claude/Codex
-    session transcripts for matching historical learnings; only do it after opt-in.
-    Ask **one** structured question (apply / no changes) per candidate cluster or a
-    single accept-all / no-changes choice, then advance substate.
-  - \`"ready_to_archive"\` -> outcome: continue \`/cc\` so the runtime archive step
-    executes, snapshots, and resets active state.
-  - \`"archived"\` (transient) -> outcome: report "run archived" and stop (flow complete).`;
-}
-export function closeoutFlowMapSentence() {
-    return `The first stage names are the critical path. \`post_ship_review\` and \`archive\` are post-ship closeout substates under ${closeoutSubstateInline()}, not separate stage schemas or commands. Continue them with \`/cc\`; do not route compound closeout through \`ce:compound\`.`;
-}
-export function closeoutProtocolBehaviorSentence() {
-    return `Keep decision, completion, and preamble discipline inline: ask only decision-changing questions, verify gates before advancing, and keep context compact. After \`ship\`, keep using \`/cc\` through ${closeoutChainInline()}; do not route normal closeout through \`ce:compound\` or a separate operations command. Inside \`post_ship_review\`, assess overlap before appending knowledge: refresh recurring bug-track learnings as actionable rules/tests and keep knowledge-track learnings as durable process/project guidance without extra lineage metadata.`;
-}

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

@@ -1 +0,0 @@
-export declare function diffSubcommandMarkdown(): string;

package/dist/content/diff-command.js

@@ -1,43 +0,0 @@
-import { RUNTIME_ROOT } from "../constants.js";
-function flowStatePath() {
-    return `${RUNTIME_ROOT}/state/flow-state.json`;
-}
-function delegationLogPath() {
-    return `${RUNTIME_ROOT}/state/delegation-log.json`;
-}
-function retroArtifactPath() {
-    return `${RUNTIME_ROOT}/artifacts/09-retro.md`;
-}
-export function diffSubcommandMarkdown() {
-    return `# /cc-view diff
-
-## HARD-GATE
-
-Never mutate state from \`/cc-view diff\`. It is a read-only inspection command.
-
-## Protocol
-
-1. Read \`${flowStatePath()}\`.
-2. Read \`${delegationLogPath()}\` (missing → treat as empty list).
-3. Inspect git diff for \`${flowStatePath()}\`, \`${delegationLogPath()}\`, and \`${retroArtifactPath()}\`.
-4. Build deltas for:
-   - stage, completed/skipped/stale sets,
-   - current-stage gate arrays (\`passed\`, \`blocked\`),
-   - \`closeout.shipSubstate\` transitions (\`from -> to\`),
-   - \`closeout.retroDraftedAt\` / \`retroAcceptedAt\` / \`retroSkipped\` flips,
-   - \`closeout.compoundPromoted\` / \`compoundSkipped\` / \`compoundCompletedAt\` flips,
-   - per-agent \`fulfillmentMode\` changes visible in delegation diffs,
-   - appearance or removal of \`${retroArtifactPath()}\` on disk.
-5. If git has no baseline for these files, print \`baseline: unavailable (read-only mode)\`.
-6. Print a compact diff map with explicit \`+\`, \`-\`, and \`->\` markers.
-
-## Validation
-
-- Diff output must be deterministic for identical states ("no visible changes").
-- The command must not create or update any \`.cclaw/state/*.snapshot*\` file.
-- Do not suppress removed values; removals are first-class evidence.
-- Closeout diff lines must use the same \`shipSubstate\` vocabulary as the
-  state machine (\`idle\` / \`post_ship_review\` /
-  \`ready_to_archive\` / \`archived\`).
-`;
-}

package/dist/content/harness-doc.d.ts

@@ -1 +0,0 @@
-export declare function harnessIntegrationDocMarkdown(): string;

package/dist/content/harness-doc.js

@@ -1,65 +0,0 @@
-import { DELEGATION_DISPATCH_SURFACES, DELEGATION_DISPATCH_SURFACE_PATH_PREFIXES } from "../delegation.js";
-import { harnessDelegationRecipes } from "../harness-adapters.js";
-/**
- * One-line description per `--dispatch-surface` enum value. Sourced from
- * `src/delegation.ts::DELEGATION_DISPATCH_SURFACES` so the generated doc
- * stays in lockstep with the runtime enum. Add a new key here whenever a
- * new surface is introduced upstream — TypeScript's `Record` enforces it.
- */
-const DISPATCH_SURFACE_DESCRIPTIONS = {
-    "claude-task": "Claude Code native Task launch against `.claude/agents/<agent-name>.md`; fulfillmentMode: `isolated`.",
-    "cursor-task": "Cursor generic Task/Subagent dispatch against `.cclaw/agents/<agent-name>.md` with a role prompt; fulfillmentMode: `generic-dispatch`. Requires non-empty `evidenceRefs` on completion.",
-    "opencode-agent": "OpenCode native subagent (`@<agent-name>` or Task) against `.opencode/agents/<agent-name>.md`; fulfillmentMode: `isolated`.",
-    "codex-agent": "OpenAI Codex CLI native custom agent against `.codex/agents/<agent-name>.toml`; fulfillmentMode: `isolated`.",
-    "generic-task": "Generic Task dispatch against `.cclaw/agents/<agent-name>.md` for harnesses without a vendor-specific surface; fulfillmentMode: `generic-dispatch`.",
-    "role-switch": "In-session role-switch fallback when no isolated dispatch surface is available. No agent-definition-path prefix is enforced; completion requires non-empty `evidenceRefs`. fulfillmentMode: `role-switch`.",
-    "manual": "Out-of-band manual dispatch (e.g. operator hand-off, external ticketing system). The agent-definition-path is intentionally free-form; recorded for audit only."
-};
-function dispatchSurfaceTableMarkdown() {
-    const rows = DELEGATION_DISPATCH_SURFACES
-        .map((surface) => {
-        const prefixes = DELEGATION_DISPATCH_SURFACE_PATH_PREFIXES[surface];
-        const prefixCell = prefixes.length === 0
-            ? "(any)"
-            : prefixes.map((prefix) => `\`${prefix}\``).join(", ");
-        return `| \`${surface}\` | ${DISPATCH_SURFACE_DESCRIPTIONS[surface]} | ${prefixCell} |`;
-    })
-        .join("\n");
-    return `### Dispatch surfaces (\`--dispatch-surface\` enum)\n\nGenerated from \`src/delegation.ts::DELEGATION_DISPATCH_SURFACES\` and \`DELEGATION_DISPATCH_SURFACE_PATH_PREFIXES\`. Any surface not in this table is rejected by \`.cclaw/hooks/delegation-record.mjs\` with a non-zero exit. The deprecated \`task\` surface is **not** in this enum.\n\n| Surface | Purpose | Allowed agent-definition-path prefixes |\n|---|---|---|\n${rows}\n`;
-}
-function perHarnessRecipeMarkdown() {
-    const recipes = harnessDelegationRecipes();
-    const rows = recipes
-        .map((recipe) => `| \`${recipe.harnessId}\` | \`${recipe.dispatchSurface}\` | \`${recipe.agentDefinitionExample}\` | ${recipe.fulfillmentMode} | scheduled -> launched -> acknowledged -> completed (reuse \`<span-id>\` + \`<dispatch-id>\`; \`--ack-ts=<iso-ts>\` for completed isolated/generic) |`)
-        .join("\n");
-    const examples = recipes
-        .map((recipe) => `**${recipe.harnessId}**:\n\n` + recipe.lifecycleCommands.map((cmd) => `    ${cmd}`).join("\n"))
-        .join("\n\n");
-    return `\n\n## Per-Harness Lifecycle Recipe\n\n| Harness | Surface | Agent definition path | fulfillmentMode | Lifecycle |\n|---|---|---|---|---|\n${rows}\n\nNeutral placeholder tokens only: \`<agent-name>\`, \`<stage>\`, \`<run-id>\`, \`<span-id>\`, \`<dispatch-id>\`, \`<agent-def-path>\`, \`<iso-ts>\`, \`<artifact-anchor>\`. See \`docs/quality-gates.md\` for stage-by-stage gate mapping.\n\nThe four shipped harnesses (\`claude\`, \`cursor\`, \`opencode\`, \`codex\`) each ship with a canonical primary surface in the table above. Repair hints: \`npx cclaw-cli sync\` safely regenerates shims/plugins/agents; Codex also needs \`[features] codex_hooks = true\`; OpenCode needs \`opencode.json(.c)\` plugin registration; role-switch completions require evidenceRefs. The remaining enum values \`generic-task\`, \`role-switch\`, and \`manual\` are documented in the dispatch-surface table below and are available to any harness as fallback paths when the primary surface is unavailable.\n\n${examples}\n\n${dispatchSurfaceTableMarkdown()}\n\n### Legacy ledger upgrade\n\nPre-v3 ledger entries that lack a recorded \`dispatchSurface\` are tagged \`fulfillmentMode: "legacy-inferred"\` on read. Stage-complete blocks completion until those rows are re-recorded with the v3 helper:\n\n    node .cclaw/hooks/delegation-record.mjs \\\n      --rerecord \\\n      --span-id=<span-id> \\\n      --dispatch-id=<dispatch-id> \\\n      --dispatch-surface=<surface> \\\n      --agent-definition-path=<agent-def-path> \\\n      --ack-ts=<iso-ts> \\\n      --completed-ts=<iso-ts> \\\n      --json\n\n\`--dispatch-surface\` must be one of the values listed in the dispatch-surface table above (the enum is generated verbatim from \`src/delegation.ts::DELEGATION_DISPATCH_SURFACES\`). Surfaces must align with the allowed agent-definition-path prefixes shown alongside each surface; \`role-switch\` and \`manual\` accept any path. The deprecated \`task\` surface is rejected.\n\n`;
-}
-function hookLayeringSectionMarkdown() {
-    return `## Hook layering
-
-Hook behavior is intentionally split into three layers so docs, generation, and runtime checks stay in sync:
-
-| Layer | Source of truth | Responsibility |
-|---|---|---|
-| 1) Manifest projection | \`src/content/hook-manifest.ts\` | Canonical handler/event map per harness. This is the authoring surface for new handlers or reroutes. |
-| 2) JSON schema descriptors | \`src/hook-schemas/*.json\` + \`src/hook-schema.ts\` descriptor map | Declares required harness-native event arrays and schema version for each harness document. |
-| 3) Runtime TS validation | \`src/hook-schema.ts::validateHookDocument\` + sync hook checks | Validates generated hook JSON shape/required events and reports actionable diagnostics. |
-
-Flow:
-1. Manifest defines handler bindings.
-2. Hook documents are generated from manifest projections.
-3. Schema descriptors + TS validators enforce structure at sync time.
-`;
-}
-export function harnessIntegrationDocMarkdown() {
-    const head = "# Harness Integration Matrix\n\nGenerated from `src/harness-adapters.ts` capabilities and hook event mappings.";
-    return [
-        head + " For the end-to-end subagent dispatch model, proof sequence, controller/worker responsibilities, and future roadmap, see [`docs/subagent-flow.md`](./subagent-flow.md).\n\n## Capability tiers\n\n| Harness | ID | Tier | declaredSupport | runtimeLaunch | Fallback | proofRequired | proofSource | Hook surface | Structured ask |\n|---|---|---|---|---|---|---|---|---|---|\n| Claude Code | `claude` | `tier1` (full native automation) | full | native Task launch | native | spanId+dispatchId or workerRunId+ACK | `.cclaw/state/delegation-events.jsonl` + ledger | full | AskUserQuestion |\n| Cursor | `cursor` | `tier2` (supported with fallback paths) | generic | generic Task/Subagent role prompt | generic-dispatch | spanId+dispatchId/evidenceRefs | events + artifact evidenceRefs | full | AskQuestion |\n| OpenCode | `opencode` | `tier2` hooks, native dispatch declared | full | prompt-level launch via Task / `@agent` against `.opencode/agents` | native | spanId+dispatchId+ackTs+completedTs | `.opencode/agents/<agent>.md` + events | plugin | question |\n| OpenAI Codex | `codex` | `tier2` hooks, native dispatch declared | full | prompt-level request to spawn `.codex/agents` custom agents | native | spanId+dispatchId+ackTs+completedTs | `.codex/agents/<agent>.toml` + events | limited | request_user_input |\n",
-        perHarnessRecipeMarkdown(),
-        hookLayeringSectionMarkdown(),
-        "\nFallback legend:\n\n- `native` \u2014 first-class named subagent dispatch (Claude).\n- `generic-dispatch` \u2014 generic Task dispatcher mapped to cclaw roles (Cursor).\n- `role-switch` \u2014 degraded fallback for a runtime where declared native/generic dispatch is unavailable; explicit role headers, artifact outputs, and non-empty delegation-log evidenceRefs are required.\n- `waiver` \u2014 no parity path; reserved for harnesses that cannot role-switch (none shipped).\n\n## Stage-Aware Native Dispatch Workflow\n\nOpenCode and Codex receive generated native isolated subagents. Use them before considering role-switch fallback:\n\n1. Use the active stage skill's generated dispatch table as the source of truth.\n2. OpenCode: invoke `.opencode/agents/<agent>.md` via Task or `@<agent>`; Codex: ask Codex to spawn `.codex/agents/<agent>.toml` by name, in parallel when lanes are independent.\n3. Load `.cclaw/agents/<agent>.md`, execute only that role's stage task, and write outputs into the active stage artifact.\n4. Append `.cclaw/state/delegation-events.jsonl` for scheduled/launched/acknowledged/completed/failed/waived/stale, then mirror current state in `.cclaw/state/delegation-log.json`. The ledger is current state; the event log is proof/audit.\n5. Treat completed role-switch rows without `evidenceRefs` as unresolved; treat native isolated completion without matching `spanId` + `dispatchId`/`workerRunId` + `ackTs` + `completedTs` as fake isolated completion. Native isolated rows are not a role-switch substitute and should reflect a real dispatched worker.\n\nThis is staged agent work backed by the harness-native subagent surfaces. Role-switch remains only a degraded fallback when that surface is unavailable in the active runtime.\n\n## Parallel research dispatch semantics\n\nDesign-stage research fleet uses the same parity model:\n\n- **Claude / Cursor**: dispatch all four research lenses in one turn\n  (stack, features, architecture, pitfalls) and synthesize into\n  `.cclaw/artifacts/02a-research.md`.\n- **OpenCode / Codex**: dispatch generated native subagents for the same\n  four lenses and run independent lanes in parallel where the active runtime\n  permits. Use role-switch with evidence only as a degraded fallback.\n\n## Semantic hook event coverage\n\nRuntime Honesty 6.9.0 reduced the runtime to two dispatched handlers:\n`session-start` (rehydrate) and `stop-handoff` (clean handoff). Earlier\nreleases also generated `prompt-guard`, `workflow-guard`,\n`context-monitor`, `pre-compact`, and `verify-current-state` handlers, but\nthose entry points were unreachable via the dispatch table they shipped\nwith and have been removed.\n\n| Event | Claude | Cursor | OpenCode | Codex |\n|---|---|---|---|---|\n| `session_rehydrate` | SessionStart matcher startup|resume|clear|compact | sessionStart/sessionResume/sessionClear/sessionCompact | plugin event handlers + transform rehydration | SessionStart matcher startup|resume |\n| `stop_handoff` | Stop -> stop-handoff | stop -> stop-handoff | plugin session.idle -> stop-handoff | Stop -> stop-handoff |\n\n## Hook lifecycle aliases\n\nThe generated Node dispatcher accepts a small compatibility alias set for lifecycle names: `stop` and `stop-checkpoint` route to `stop-handoff`, and `session-rehydrate` routes to `session-start`. Rehydration remains the `session-start` responsibility after compact events. Harness JSON should still emit the canonical handler names from `src/content/hook-manifest.ts`.\n\n## Hook event casing\n\nHook keys are intentionally harness-native and must not be normalized:\n\n| Harness | ID | Event key casing |\n|---|---|---|\n| Claude Code | `claude` | PascalCase (`SessionStart`, `Stop`) |\n| Cursor | `cursor` | camelCase (`sessionStart`, `stop`) |\n| OpenCode | `opencode` | camelCase (`sessionStart`, `stop`) |\n| OpenAI Codex | `codex` | PascalCase (`SessionStart`, `Stop`) |\n\nUse the exact event names from each harness schema. Treating all hooks as one\nshared casing silently breaks generated wiring.\n\n## Interpretation\n\n- `tier1`: full native delegation + structured asks + full hook surface.\n- `tier2`: usable flow with capability gaps; mandatory delegation can require waivers.\n- Hook-level pre-tool blocking (prompt-guard / workflow-guard) was removed\n  in 6.9.0. Stage transitions are owned by the canonical CLI path\n  `node .cclaw/hooks/stage-complete.mjs <stage>`; harness sessions enforce\n  workflow discipline via the iron-laws block surfaced at session-start\n  rather than via per-tool hook interception.\n\n## Shared command contract\n\nAll harnesses receive the same utility commands:\n\n- `/cc` - flow entry and resume\n- `/cc` - stage progression and post-ship closeout\n- `/cc-idea` - idea mode for ranked repo-improvement backlog\n- `/cc-view` - read-only router for status/tree/diff\n\nRead-only subcommands:\n- `/cc-view status` - visual flow snapshot\n- `/cc-view tree` - deep flow tree (stages, artifacts, stale markers)\n- `/cc-view diff` - before/after flow-state diff map\n\nOperational work is handled by `/cc`, `/cc-idea`, `/cc-view`, and `node .cclaw/hooks/stage-complete.mjs <stage>` inside the installed harness runtime. `npx cclaw-cli` is the installer/support surface for init, sync, upgrade, and explicit/manual archive; the normal stage flow must not depend on a runtime `cclaw` binary in PATH.\n\nCritical-path stage order remains canonical:\n`brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship`\n\nEvery track then closes out through:\n`post_ship_review -> archive`\n\n## Stage -> skill folder mapping\n\n| Stage | Skill folder |\n|---|---|\n| `brainstorm` | `brainstorm` |\n| `scope` | `scope` |\n| `design` | `design` |\n| `spec` | `spec` |\n| `plan` | `plan` |\n| `tdd` | `tdd` |\n| `review` | `review` |\n| `ship` | `ship` |\n\nThis map is generated from `src/constants.ts::STAGE_TO_SKILL_FOLDER` so\nskill-path naming stays explicit and stable even when stage ids differ from\nfolder names.\n\n## Install surfaces\n\nAlways generated:\n\n- `.cclaw/commands/*.md`\n- `.cclaw/skills/*/SKILL.md`\n- `.cclaw/state/*.json|*.jsonl`\n- `AGENTS.md` managed block\n\nHarness-specific additions:\n\n- `claude`: `.claude/commands/cc*.md`, `.claude/hooks/hooks.json`\n- `cursor`: `.cursor/commands/cc*.md`, `.cursor/hooks.json`, `.cursor/rules/cclaw-workflow.mdc`\n- `opencode`: `.opencode/commands/cc*.md`, `.opencode/plugins/cclaw-plugin.mjs`, opencode plugin registration with `permission.question: \"allow\"`; set `OPENCODE_ENABLE_QUESTION_TOOL=1` for ACP clients so structured asks can route through question tooling. Sync/runtime checks validate the config permission and warn when the environment hint is absent.\n- `codex`: `.agents/skills/cc/SKILL.md`, `.agents/skills/cc-idea/SKILL.md`, `.agents/skills/cc-view/SKILL.md`, `.codex/hooks.json` (Codex CLI reads `.agents/skills/` for custom skills and consumes `.codex/hooks.json` on v0.114+ when `[features] codex_hooks = true` is set in `~/.codex/config.toml`. `.codex/commands/` and the legacy `.agents/skills/cclaw-cc*/` layout from v0.39.x are auto-cleaned on sync.)\n\n## Runtime observability\n\n- `npx cclaw-cli sync` validates shim, hook, and lifecycle surfaces against this capability model.\n- `/cc-view status` and `/cc-view tree` surface the same harness tier/fallback facts from the generated runtime metadata.\n\n## Delegation Proof Model\n\nRuntime state is split deliberately:\n\n- `.cclaw/state/delegation-log.json` is the compact current ledger used by stage gates and `/cc-view` summaries.\n- `.cclaw/state/delegation-events.jsonl` is append-only audit proof for `scheduled`, `launched`, `acknowledged`, `completed`, `failed`, `waived`, and `stale` lifecycle transitions.\n- `.cclaw/state/subagents.json` is a lightweight active-worker tracker for status/tree/sync reports.\n- `.cclaw/hooks/delegation-record.mjs` is the generated helper for lifecycle rows/events. It validates required fields and emits JSON diagnostics with `--json`.\n\nIsolated completion requires `spanId`, `dispatchId` or `workerRunId`, `dispatchSurface`, `agentDefinitionPath`, `ackTs`, `launchedTs`, and `completedTs`. Cursor/generic dispatch and role-switch also require evidence refs when artifact evidence is the proof source. Legacy inferred completions remain readable, but sync reports them as warnings because they predate event-log proof.\n\n## Reference Audit Appendix\n\nStatus meanings: `deep` = read for transferable implementation contract; `targeted` = inspected the relevant files only; `skimmed` = searched/read enough to classify; `not relevant` = intentionally excluded from implementation influence.\n\n| Reference path under `<repo-relative references dir>` | Status | Findings preserved |\n|---|---|---|\n| `evanklem-evanflow/skills/evanflow-coder-overseer/SKILL.md` | deep | Contract-first coder/overseer loop, reviewer reads code rather than worker narrative, and integration overseer pattern map cleanly onto cclaw subagent guidance. |\n| `evanklem-evanflow/agents/evanflow-coder.md` | targeted | Worker role is narrow: implement the pasted contract, avoid broad orchestration, and return evidence for overseer verification. |\n| `evanklem-evanflow/agents/evanflow-overseer.md` | targeted | Overseer validates actual code and acceptance evidence before controller marks work complete. |\n| `oh-my-codex/src/agents/native-config.ts` | deep | Native agent config shape supports explicit metadata/model/tool posture; cclaw should validate generated `.codex/agents/*.toml` shape instead of trusting file presence. |\n| `oh-my-codex/src/team/state/events.ts` and `src/team/state/workers.ts` | targeted | Append-only events plus worker state are useful as separate audit/current-state layers; cclaw mirrors that with `delegation-events.jsonl` and `subagents.json`. |\n| `oh-my-openagent/src/tools/delegate-task/tools.ts` | deep | Delegation should have an explicit dispatch surface and mode instead of relying on a prose claim that an agent was launched. |\n| `oh-my-openagent/src/tools/delegate-task/subagent-resolver.ts` | targeted | Agent discovery should be checked by sync so missing/corrupt generated agent definitions are visible before dispatch. |\n| `oh-my-openagent/src/tools/delegate-task/prompt-builder.ts` | targeted | Prompt builders should include exact invocation/return contracts; cclaw generated worker prompts now carry ACK/result schemas. |\n| `giancarloerra-socraticode/**` | skimmed | Useful for workflow/e2e and graph-oriented contract testing, but not a subagent dispatch implementation reference; no runtime pattern imported. |\n| unrelated large reference trees not named above | not relevant | Searched/skipped because they did not contain flow/subagent/harness dispatch patterns relevant to this plan. |\n"
-    ].join("");
-}

package/dist/content/hook-events.d.ts

@@ -1,9 +0,0 @@
-import type { HarnessId } from "../types.js";
-import { type HookSemanticEvent } from "./hook-manifest.js";
-export { HOOK_SEMANTIC_EVENTS, type HookSemanticEvent } from "./hook-manifest.js";
-/**
- * Public semantic coverage map derived from `HOOK_MANIFEST` for
- * claude/cursor/codex, plus the static OpenCode descriptor. Consumers
- * should treat this as read-only.
- */
-export declare const HOOK_EVENTS_BY_HARNESS: Record<HarnessId, Partial<Record<HookSemanticEvent, string>>>;

package/dist/content/hook-events.js

@@ -1,23 +0,0 @@
-import { semanticEventCoverage } from "./hook-manifest.js";
-export { HOOK_SEMANTIC_EVENTS } from "./hook-manifest.js";
-/**
- * OpenCode is covered by the inline plugin (`opencode-plugin.ts`), not
- * by the generated `run-hook.mjs` dispatcher. We keep its semantic
- * coverage table here as an explicit descriptor, since it does not
- * flow through the hook manifest.
- */
-const OPENCODE_SEMANTIC_COVERAGE = {
-    session_rehydrate: "plugin event handlers + transform rehydration",
-    stop_handoff: "plugin session.idle -> stop-handoff"
-};
-/**
- * Public semantic coverage map derived from `HOOK_MANIFEST` for
- * claude/cursor/codex, plus the static OpenCode descriptor. Consumers
- * should treat this as read-only.
- */
-export const HOOK_EVENTS_BY_HARNESS = Object.freeze({
-    claude: semanticEventCoverage("claude"),
-    cursor: semanticEventCoverage("cursor"),
-    codex: semanticEventCoverage("codex"),
-    opencode: OPENCODE_SEMANTIC_COVERAGE
-});

package/dist/content/hook-manifest.d.ts

@@ -1,81 +0,0 @@
-/**
- * Canonical operational manifest for cclaw hooks.
- *
- * This is the **single source of truth** for:
- *
- *  - the per-harness JSON generators in `./observe.ts`
- *    (claude/cursor/codex hook documents),
- *  - the semantic coverage map in `./hook-events.ts` (docs + sync/runtime checks),
- *  - the `requiredEvents` list embedded in `src/hook-schemas/*.v1.json`
- *    (enforced by a parity test).
- *
- * When adding a new hook handler or rerouting an existing one, edit
- * this file and let the downstream modules rebuild from it. Never
- * hard-code a `SessionStart`, `PreToolUse`, etc. mapping outside of
- * this manifest.
- *
- * OpenCode is deliberately out of scope here: its plugin
- * (`opencode-plugin.ts`) implements the handlers inline rather than
- * dispatching through `run-hook.mjs`, so its coverage is tracked
- * separately in `HOOK_EVENTS_BY_HARNESS`.
- */
-export declare const HOOK_MANIFEST_HARNESSES: readonly ["claude", "cursor", "codex"];
-export type HookManifestHarness = (typeof HOOK_MANIFEST_HARNESSES)[number];
-export declare const HOOK_HANDLERS: readonly ["session-start", "stop-handoff"];
-export type HookHandlerId = (typeof HOOK_HANDLERS)[number];
-export interface HookBinding {
-    /**
-     * Harness-native event name (exact string; PascalCase for
-     * claude/codex, camelCase for cursor). Do not normalize casing.
-     */
-    event: string;
-    matcher?: string;
-    timeout?: number;
-    /** Optional harness UI status line while this hook runs. */
-    statusMessage?: string;
-    /**
-     * Within a single (harness, event) group, entries are sorted by
-     * `priority` ASC, ties broken by manifest-declaration order. Use
-     * this to express "this handler must run BEFORE/AFTER that handler
-     * on the same event". Default `0`.
-     */
-    priority?: number;
-}
-export interface HookHandlerSpec {
-    handler: HookHandlerId;
-    description: string;
-    /**
-     * Semantic event id used by `HOOK_EVENTS_BY_HARNESS` / docs.
-     * `null` means this handler contributes no semantic coverage row.
-     */
-    semantic: HookSemanticEvent | null;
-    bindings: Partial<Record<HookManifestHarness, HookBinding[]>>;
-}
-export declare const HOOK_SEMANTIC_EVENTS: readonly ["session_rehydrate", "stop_handoff"];
-export type HookSemanticEvent = (typeof HOOK_SEMANTIC_EVENTS)[number];
-export declare const HOOK_MANIFEST: readonly HookHandlerSpec[];
-export interface EventGroup {
-    event: string;
-    /**
-     * Entries sorted by (priority ASC, declaration order). Default
-     * priority is 0. Stable — ties preserve manifest order.
-     */
-    entries: Array<{
-        handler: HookHandlerId;
-        matcher?: string;
-        timeout?: number;
-        statusMessage?: string;
-    }>;
-}
-/**
- * Group manifest bindings by harness-native event name. This is the
- * core projection that observe.ts generators consume to emit the
- * harness-specific JSON document.
- */
-export declare function groupBindingsByEvent(harness: HookManifestHarness): EventGroup[];
-/** Distinct harness-native event names covered by the manifest. */
-export declare function requiredEventsFor(harness: HookManifestHarness): string[];
-/**
- * Human-readable per-harness semantic coverage used by docs and sync/runtime diagnostics.
- */
-export declare function semanticEventCoverage(harness: HookManifestHarness): Partial<Record<HookSemanticEvent, string>>;