cclaw-cli 0.48.15 → 0.48.16

package/dist/content/flow-map.js

@@ -118,6 +118,11 @@ Hook-driven guards respect the \`strictness\` field in
 
 Override per-session with \`CCLAW_STRICTNESS=advisory|strict\`.
 
+Hook wiring itself comes from a **single manifest** (\`src/content/hook-manifest.ts\`):
+the per-harness documents at \`.claude/hooks/hooks.json\`, \`.cursor/hooks.json\`,
+\`.codex/hooks.json\` are all derived from it. Inspect the live bindings with
+\`cclaw internal hook-manifest\` (add \`--json\` for machine-readable output).
+
 ## When in doubt
 
 1. Read \`${RUNTIME_ROOT}/state/flow-state.json\` to know where you are.

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

@@ -1,4 +1,9 @@
 import type { HarnessId } from "../types.js";
-export declare const HOOK_SEMANTIC_EVENTS: readonly ["session_rehydrate", "pre_tool_prompt_guard", "pre_tool_workflow_guard", "post_tool_context_monitor", "stop_checkpoint", "precompact_digest"];
-export type HookSemanticEvent = (typeof HOOK_SEMANTIC_EVENTS)[number];
+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,47 +1,31 @@
-export const HOOK_SEMANTIC_EVENTS = [
-    "session_rehydrate",
-    "pre_tool_prompt_guard",
-    "pre_tool_workflow_guard",
-    "post_tool_context_monitor",
-    "stop_checkpoint",
-    "precompact_digest"
-];
-export const HOOK_EVENTS_BY_HARNESS = {
-    claude: {
-        session_rehydrate: "SessionStart matcher startup|resume|clear|compact",
-        pre_tool_prompt_guard: "PreToolUse -> prompt-guard",
-        pre_tool_workflow_guard: "PreToolUse -> workflow-guard",
-        post_tool_context_monitor: "PostToolUse -> context-monitor",
-        stop_checkpoint: "Stop -> stop-checkpoint",
-        precompact_digest: "PreCompact -> pre-compact"
-    },
-    cursor: {
-        session_rehydrate: "sessionStart/sessionResume/sessionClear/sessionCompact",
-        pre_tool_prompt_guard: "preToolUse -> prompt-guard",
-        pre_tool_workflow_guard: "preToolUse -> workflow-guard",
-        post_tool_context_monitor: "postToolUse -> context-monitor",
-        stop_checkpoint: "stop -> stop-checkpoint",
-        precompact_digest: "sessionCompact -> pre-compact"
-    },
-    opencode: {
-        session_rehydrate: "plugin event handlers + transform rehydration",
-        pre_tool_prompt_guard: "plugin tool.execute.before -> prompt-guard",
-        pre_tool_workflow_guard: "plugin tool.execute.before -> workflow-guard",
-        post_tool_context_monitor: "plugin tool.execute.after -> context-monitor",
-        stop_checkpoint: "plugin session.idle -> stop-checkpoint",
-        precompact_digest: "plugin session.compacted -> pre-compact"
-    },
-    codex: {
-        // Codex CLI v0.114+ exposes lifecycle hooks via `.codex/hooks.json`,
-        // gated by `[features] codex_hooks = true` in `~/.codex/config.toml`.
-        // SessionStart, Stop, and UserPromptSubmit fire for every turn;
-        // PreToolUse/PostToolUse are **Bash-only** (Write/Edit/WebSearch/MCP
-        // calls do not trigger them). `precompact_digest` is unmapped —
-        // Codex has no PreCompact event; cclaw covers it via `/cc-ops retro`.
-        session_rehydrate: "SessionStart matcher startup|resume",
-        pre_tool_prompt_guard: "PreToolUse matcher Bash -> prompt-guard (plus UserPromptSubmit for non-Bash prompts)",
-        pre_tool_workflow_guard: "PreToolUse matcher Bash -> workflow-guard (Bash-only)",
-        post_tool_context_monitor: "PostToolUse matcher Bash -> context-monitor (Bash-only)",
-        stop_checkpoint: "Stop -> stop-checkpoint"
-    }
+import { HOOK_MANIFEST_HARNESSES, semanticEventCoverage } from "./hook-manifest.js";
+export { HOOK_SEMANTIC_EVENTS } from "./hook-manifest.js";
+function isManifestHarness(value) {
+    return HOOK_MANIFEST_HARNESSES.includes(value);
+}
+/**
+ * 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",
+    pre_tool_prompt_guard: "plugin tool.execute.before -> prompt-guard",
+    pre_tool_workflow_guard: "plugin tool.execute.before -> workflow-guard",
+    post_tool_context_monitor: "plugin tool.execute.after -> context-monitor",
+    stop_checkpoint: "plugin session.idle -> stop-checkpoint",
+    precompact_digest: "plugin session.compacted -> pre-compact"
 };
+/**
+ * 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
+});
+void isManifestHarness;

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

@@ -0,0 +1,82 @@
+/**
+ * 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 + doctor),
+ *  - 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", "prompt-guard", "workflow-guard", "context-monitor", "stop-checkpoint", "pre-compact", "verify-current-state"];
+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;
+    /**
+     * 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" (e.g. pre-compact must run before session-start
+     * on cursor `sessionCompact`). 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
+     * (e.g. `verify-current-state` on codex is a supplementary guard,
+     * not a top-level semantic event).
+     */
+    semantic: HookSemanticEvent | null;
+    bindings: Partial<Record<HookManifestHarness, HookBinding[]>>;
+}
+export declare const HOOK_SEMANTIC_EVENTS: readonly ["session_rehydrate", "pre_tool_prompt_guard", "pre_tool_workflow_guard", "post_tool_context_monitor", "stop_checkpoint", "precompact_digest"];
+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;
+    }>;
+}
+/**
+ * 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 by
+ * the doctor's `harness-gaps.json` synthesis.
+ */
+export declare function semanticEventCoverage(harness: HookManifestHarness): Partial<Record<HookSemanticEvent, string>>;

package/dist/content/hook-manifest.js

@@ -0,0 +1,208 @@
+/**
+ * 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 + doctor),
+ *  - 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 const HOOK_MANIFEST_HARNESSES = ["claude", "cursor", "codex"];
+export const HOOK_HANDLERS = [
+    "session-start",
+    "prompt-guard",
+    "workflow-guard",
+    "context-monitor",
+    "stop-checkpoint",
+    "pre-compact",
+    "verify-current-state"
+];
+export const HOOK_SEMANTIC_EVENTS = [
+    "session_rehydrate",
+    "pre_tool_prompt_guard",
+    "pre_tool_workflow_guard",
+    "post_tool_context_monitor",
+    "stop_checkpoint",
+    "precompact_digest"
+];
+export const HOOK_MANIFEST = [
+    {
+        handler: "session-start",
+        description: "Rehydrate flow state, refresh Ralph Loop + compound readiness, emit bootstrap digest.",
+        semantic: "session_rehydrate",
+        bindings: {
+            claude: [{ event: "SessionStart", matcher: "startup|resume|clear|compact" }],
+            cursor: [
+                { event: "sessionStart" },
+                { event: "sessionResume" },
+                { event: "sessionClear" },
+                { event: "sessionCompact" }
+            ],
+            codex: [{ event: "SessionStart", matcher: "startup|resume" }]
+        }
+    },
+    {
+        handler: "prompt-guard",
+        description: "Stage-aware prompt gate (iron-laws + strictness).",
+        semantic: "pre_tool_prompt_guard",
+        bindings: {
+            claude: [{ event: "PreToolUse", matcher: "*" }],
+            cursor: [{ event: "preToolUse", matcher: "*" }],
+            codex: [
+                { event: "UserPromptSubmit" },
+                { event: "PreToolUse", matcher: "Bash|bash" }
+            ]
+        }
+    },
+    {
+        handler: "workflow-guard",
+        description: "TDD and workflow gate on Write/Edit/Bash style tool invocations.",
+        semantic: "pre_tool_workflow_guard",
+        bindings: {
+            claude: [{ event: "PreToolUse", matcher: "Write|Edit|MultiEdit|NotebookEdit|Bash" }],
+            cursor: [{ event: "preToolUse", matcher: "*" }],
+            codex: [
+                { event: "UserPromptSubmit" },
+                { event: "PreToolUse", matcher: "Bash|bash" }
+            ]
+        }
+    },
+    {
+        handler: "context-monitor",
+        description: "Post-tool context usage + stage signal monitor.",
+        semantic: "post_tool_context_monitor",
+        bindings: {
+            claude: [{ event: "PostToolUse", matcher: "*" }],
+            cursor: [{ event: "postToolUse", matcher: "*" }],
+            codex: [{ event: "PostToolUse", matcher: "Bash|bash" }]
+        }
+    },
+    {
+        handler: "stop-checkpoint",
+        description: "Persist checkpoint with stage + run context on session stop.",
+        semantic: "stop_checkpoint",
+        bindings: {
+            claude: [{ event: "Stop", timeout: 10 }],
+            cursor: [{ event: "stop", timeout: 10 }],
+            codex: [{ event: "Stop", timeout: 10 }]
+        }
+    },
+    {
+        handler: "pre-compact",
+        description: "Write pre-compact digest (Claude+Cursor have a native event; Codex has no PreCompact — covered by `/cc-ops retro`).",
+        semantic: "precompact_digest",
+        bindings: {
+            claude: [{ event: "PreCompact", matcher: "manual|auto", timeout: 10 }],
+            // pre-compact must capture the digest BEFORE session-start
+            // rehydrates on cursor `sessionCompact`.
+            cursor: [{ event: "sessionCompact", priority: -10 }]
+        }
+    },
+    {
+        handler: "verify-current-state",
+        description: "Supplementary codex guard that runs on UserPromptSubmit to assert the live state matches the flow.",
+        semantic: null,
+        bindings: {
+            codex: [{ event: "UserPromptSubmit" }]
+        }
+    }
+];
+/** Sanity: every harness in HOOK_MANIFEST_HARNESSES must be a HarnessId. */
+const _harnessIdCheck = HOOK_MANIFEST_HARNESSES;
+void _harnessIdCheck;
+/**
+ * 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 function groupBindingsByEvent(harness) {
+    const order = [];
+    const byEvent = new Map();
+    let seq = 0;
+    for (const spec of HOOK_MANIFEST) {
+        const bindings = spec.bindings[harness];
+        if (!bindings)
+            continue;
+        for (const binding of bindings) {
+            let group = byEvent.get(binding.event);
+            if (!group) {
+                group = { event: binding.event, entries: [] };
+                byEvent.set(binding.event, group);
+                order.push(binding.event);
+            }
+            group.entries.push({
+                handler: spec.handler,
+                ...(binding.matcher !== undefined ? { matcher: binding.matcher } : {}),
+                ...(binding.timeout !== undefined ? { timeout: binding.timeout } : {}),
+                priority: binding.priority ?? 0,
+                seq: seq++
+            });
+        }
+    }
+    return order.map((event) => {
+        const group = byEvent.get(event);
+        const sorted = [...group.entries].sort((a, b) => {
+            if (a.priority !== b.priority)
+                return a.priority - b.priority;
+            return a.seq - b.seq;
+        });
+        return {
+            event: group.event,
+            entries: sorted.map(({ priority: _p, seq: _s, ...entry }) => entry)
+        };
+    });
+}
+/** Distinct harness-native event names covered by the manifest. */
+export function requiredEventsFor(harness) {
+    const seen = new Set();
+    const ordered = [];
+    for (const spec of HOOK_MANIFEST) {
+        for (const binding of spec.bindings[harness] ?? []) {
+            if (seen.has(binding.event))
+                continue;
+            seen.add(binding.event);
+            ordered.push(binding.event);
+        }
+    }
+    return ordered;
+}
+/**
+ * Human-readable per-harness semantic coverage used by docs and by
+ * the doctor's `harness-gaps.json` synthesis.
+ */
+export function semanticEventCoverage(harness) {
+    const out = {};
+    for (const spec of HOOK_MANIFEST) {
+        if (spec.semantic === null)
+            continue;
+        const bindings = spec.bindings[harness];
+        if (!bindings || bindings.length === 0)
+            continue;
+        out[spec.semantic] = describeBindings(bindings);
+    }
+    return out;
+}
+function describeBindings(bindings) {
+    return bindings
+        .map((binding) => {
+        const pieces = [binding.event];
+        if (binding.matcher)
+            pieces.push(`matcher=${binding.matcher}`);
+        if (binding.timeout)
+            pieces.push(`timeout=${binding.timeout}s`);
+        return pieces.join(" ");
+    })
+        .join(" | ");
+}

package/dist/content/observe.d.ts

@@ -1,3 +1,19 @@
+import { type HookHandlerId, type HookManifestHarness } from "./hook-manifest.js";
 export declare function claudeHooksJsonWithObservation(): string;
 export declare function cursorHooksJsonWithObservation(): string;
 export declare function codexHooksJsonWithObservation(): string;
+/**
+ * Public accessor so diagnostic CLIs and tests can inspect the
+ * manifest without importing the private generator helpers.
+ */
+export declare function hookManifestSnapshot(): Array<{
+    harness: HookManifestHarness;
+    events: Array<{
+        event: string;
+        entries: Array<{
+            handler: HookHandlerId;
+            matcher?: string;
+            timeout?: number;
+        }>;
+    }>;
+}>;

package/dist/content/observe.js

@@ -1,4 +1,5 @@
 import { RUNTIME_ROOT } from "../constants.js";
+import { HOOK_MANIFEST, groupBindingsByEvent } from "./hook-manifest.js";
 function hookDispatcherCommand(hookName) {
     // RUNTIME_ROOT is a relative path (".cclaw") that currently contains no
     // whitespace, so quoting is unnecessary inside the JSON-encoded command
@@ -6,139 +7,83 @@ function hookDispatcherCommand(hookName) {
     // JSON.stringify to survive spaces.
     return `node ${RUNTIME_ROOT}/hooks/run-hook.mjs ${hookName}`;
 }
+/**
+ * Claude / Codex share the same outer envelope: each event is an
+ * array of `{matcher?, hooks: [{type: "command", command, timeout?}]}`
+ * objects. Entries with the same `matcher` are merged into a single
+ * outer entry so we emit one `{matcher: "..."}` block with multiple
+ * inner hook commands.
+ */
+function buildClaudeLikeEvents(harness) {
+    const out = {};
+    for (const group of groupBindingsByEvent(harness)) {
+        const mergedByMatcher = new Map();
+        const order = [];
+        for (const entry of group.entries) {
+            const matcherKey = entry.matcher ?? "__no_matcher__";
+            let bucket = mergedByMatcher.get(matcherKey);
+            if (!bucket) {
+                bucket = {
+                    ...(entry.matcher !== undefined ? { matcher: entry.matcher } : {}),
+                    hooks: []
+                };
+                mergedByMatcher.set(matcherKey, bucket);
+                order.push(matcherKey);
+            }
+            const hookEntry = {
+                type: "command",
+                command: hookDispatcherCommand(entry.handler),
+                ...(entry.timeout !== undefined ? { timeout: entry.timeout } : {})
+            };
+            bucket.hooks.push(hookEntry);
+        }
+        out[group.event] = order.map((key) => mergedByMatcher.get(key));
+    }
+    return out;
+}
+/**
+ * Cursor uses a flat shape: each event maps directly to an array of
+ * `{command, matcher?, timeout?}` entries — no inner `hooks` array.
+ */
+function buildCursorEvents() {
+    const out = {};
+    for (const group of groupBindingsByEvent("cursor")) {
+        out[group.event] = group.entries.map((entry) => ({
+            command: hookDispatcherCommand(entry.handler),
+            ...(entry.matcher !== undefined ? { matcher: entry.matcher } : {}),
+            ...(entry.timeout !== undefined ? { timeout: entry.timeout } : {})
+        }));
+    }
+    return out;
+}
 export function claudeHooksJsonWithObservation() {
     return JSON.stringify({
         cclawHookSchemaVersion: 1,
-        hooks: {
-            SessionStart: [{
-                    matcher: "startup|resume|clear|compact",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("session-start")
-                        }]
-                }],
-            PreToolUse: [{
-                    matcher: "*",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("prompt-guard")
-                        }]
-                }, {
-                    matcher: "Write|Edit|MultiEdit|NotebookEdit|Bash",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("workflow-guard")
-                        }]
-                }],
-            PostToolUse: [{
-                    matcher: "*",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("context-monitor")
-                        }]
-                }],
-            Stop: [{
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("stop-checkpoint"),
-                            timeout: 10
-                        }]
-                }],
-            PreCompact: [{
-                    matcher: "manual|auto",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("pre-compact"),
-                            timeout: 10
-                        }]
-                }]
-        }
+        hooks: buildClaudeLikeEvents("claude")
     }, null, 2);
 }
 export function cursorHooksJsonWithObservation() {
     return JSON.stringify({
         cclawHookSchemaVersion: 1,
         version: 1,
-        hooks: {
-            sessionStart: [{
-                    command: hookDispatcherCommand("session-start")
-                }],
-            sessionResume: [{
-                    command: hookDispatcherCommand("session-start")
-                }],
-            sessionClear: [{
-                    command: hookDispatcherCommand("session-start")
-                }],
-            sessionCompact: [{
-                    command: hookDispatcherCommand("pre-compact")
-                }, {
-                    command: hookDispatcherCommand("session-start")
-                }],
-            preToolUse: [{
-                    matcher: "*",
-                    command: hookDispatcherCommand("prompt-guard")
-                }, {
-                    matcher: "*",
-                    command: hookDispatcherCommand("workflow-guard")
-                }],
-            postToolUse: [{
-                    matcher: "*",
-                    command: hookDispatcherCommand("context-monitor")
-                }],
-            stop: [{
-                    command: hookDispatcherCommand("stop-checkpoint"),
-                    timeout: 10
-                }]
-        }
+        hooks: buildCursorEvents()
     }, null, 2);
 }
 export function codexHooksJsonWithObservation() {
     return JSON.stringify({
         cclawHookSchemaVersion: 1,
-        hooks: {
-            SessionStart: [{
-                    matcher: "startup|resume",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("session-start")
-                        }]
-                }],
-            UserPromptSubmit: [{
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("prompt-guard")
-                        }, {
-                            type: "command",
-                            command: hookDispatcherCommand("workflow-guard")
-                        }, {
-                            type: "command",
-                            command: hookDispatcherCommand("verify-current-state")
-                        }]
-                }],
-            PreToolUse: [{
-                    matcher: "Bash|bash",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("prompt-guard")
-                        }, {
-                            type: "command",
-                            command: hookDispatcherCommand("workflow-guard")
-                        }]
-                }],
-            PostToolUse: [{
-                    matcher: "Bash|bash",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("context-monitor")
-                        }]
-                }],
-            Stop: [{
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("stop-checkpoint"),
-                            timeout: 10
-                        }]
-                }]
-        }
+        hooks: buildClaudeLikeEvents("codex")
     }, null, 2);
 }
+/**
+ * Public accessor so diagnostic CLIs and tests can inspect the
+ * manifest without importing the private generator helpers.
+ */
+export function hookManifestSnapshot() {
+    return (HOOK_MANIFEST.length === 0
+        ? ["claude", "cursor", "codex"]
+        : ["claude", "cursor", "codex"]).map((harness) => ({
+        harness,
+        events: groupBindingsByEvent(harness)
+    }));
+}

package/dist/internal/advance-stage.js

@@ -13,6 +13,7 @@ import { appendKnowledge } from "../knowledge-store.js";
 import { readFlowState, writeFlowState } from "../runs.js";
 import { FLOW_STAGES } from "../types.js";
 import { runCompoundReadinessCommand } from "./compound-readiness.js";
+import { runHookManifestCommand } from "./hook-manifest.js";
 import { runEnvelopeValidateCommand } from "./envelope-validate.js";
 import { runKnowledgeDigestCommand } from "./knowledge-digest.js";
 import { runTddLoopStatusCommand } from "./tdd-loop-status.js";
@@ -674,7 +675,7 @@ async function runHookCommand(projectRoot, args, io) {
 export async function runInternalCommand(projectRoot, argv, io) {
     const [subcommand, ...tokens] = argv;
     if (!subcommand) {
-        io.stderr.write("cclaw internal requires a subcommand: advance-stage | verify-flow-state-diff | verify-current-state | knowledge-digest | envelope-validate | tdd-red-evidence | tdd-loop-status | compound-readiness | hook\n");
+        io.stderr.write("cclaw internal requires a subcommand: advance-stage | verify-flow-state-diff | verify-current-state | knowledge-digest | envelope-validate | tdd-red-evidence | tdd-loop-status | compound-readiness | hook-manifest | hook\n");
         return 1;
     }
     try {
@@ -702,10 +703,13 @@ export async function runInternalCommand(projectRoot, argv, io) {
         if (subcommand === "compound-readiness") {
             return await runCompoundReadinessCommand(projectRoot, tokens, io);
         }
+        if (subcommand === "hook-manifest") {
+            return await runHookManifestCommand(projectRoot, tokens, io);
+        }
         if (subcommand === "hook") {
             return await runHookCommand(projectRoot, parseHookArgs(tokens), io);
         }
-        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | verify-flow-state-diff | verify-current-state | knowledge-digest | envelope-validate | tdd-red-evidence | tdd-loop-status | compound-readiness | hook\n`);
+        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | verify-flow-state-diff | verify-current-state | knowledge-digest | envelope-validate | tdd-red-evidence | tdd-loop-status | compound-readiness | hook-manifest | hook\n`);
         return 1;
     }
     catch (err) {

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

@@ -0,0 +1,16 @@
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+/**
+ * `cclaw internal hook-manifest` — diagnostic command that prints
+ * the resolved manifest. Primary use cases:
+ *
+ *  - debugging "which handler fires for event X on harness Y",
+ *  - migration tooling that needs a machine-readable view,
+ *  - parity verification between the source-of-truth manifest and
+ *    per-harness generated documents.
+ */
+export declare function runHookManifestCommand(_projectRoot: string, argv: string[], io: InternalIo): Promise<number>;
+export {};

package/dist/internal/hook-manifest.js

@@ -0,0 +1,77 @@
+import { HOOK_MANIFEST, HOOK_MANIFEST_HARNESSES, groupBindingsByEvent, requiredEventsFor } from "../content/hook-manifest.js";
+function parseArgs(tokens) {
+    const args = { json: false };
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        if (token === "--json")
+            args.json = true;
+        else if (token === "--harness") {
+            const value = tokens[i + 1];
+            if (value !== "claude" && value !== "cursor" && value !== "codex") {
+                throw new Error(`--harness must be one of claude|cursor|codex, got ${String(value)}`);
+            }
+            args.harness = value;
+            i += 1;
+        }
+        else {
+            throw new Error(`Unknown hook-manifest flag: ${token}`);
+        }
+    }
+    return args;
+}
+/**
+ * `cclaw internal hook-manifest` — diagnostic command that prints
+ * the resolved manifest. Primary use cases:
+ *
+ *  - debugging "which handler fires for event X on harness Y",
+ *  - migration tooling that needs a machine-readable view,
+ *  - parity verification between the source-of-truth manifest and
+ *    per-harness generated documents.
+ */
+export async function runHookManifestCommand(_projectRoot, argv, io) {
+    const args = parseArgs(argv);
+    const harnesses = args.harness ? [args.harness] : [...HOOK_MANIFEST_HARNESSES];
+    if (args.json) {
+        const payload = {
+            handlers: HOOK_MANIFEST.map((spec) => ({
+                handler: spec.handler,
+                description: spec.description,
+                semantic: spec.semantic,
+                bindings: spec.bindings
+            })),
+            byHarness: Object.fromEntries(harnesses.map((harness) => [
+                harness,
+                {
+                    requiredEvents: requiredEventsFor(harness),
+                    events: groupBindingsByEvent(harness)
+                }
+            ]))
+        };
+        io.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        return 0;
+    }
+    const lines = [];
+    lines.push("cclaw hook manifest");
+    for (const harness of harnesses) {
+        lines.push("");
+        lines.push(`## ${harness}`);
+        const groups = groupBindingsByEvent(harness);
+        if (groups.length === 0) {
+            lines.push("  (no bindings)");
+            continue;
+        }
+        for (const group of groups) {
+            lines.push(`  ${group.event}:`);
+            for (const entry of group.entries) {
+                const parts = [entry.handler];
+                if (entry.matcher)
+                    parts.push(`matcher=${entry.matcher}`);
+                if (entry.timeout)
+                    parts.push(`timeout=${entry.timeout}s`);
+                lines.push(`    - ${parts.join(" ")}`);
+            }
+        }
+    }
+    io.stdout.write(`${lines.join("\n")}\n`);
+    return 0;
+}

package/package.json

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