cclaw-cli 0.46.3 → 0.46.5

package/dist/content/hooks.d.ts

@@ -11,10 +11,11 @@ export interface HookRuntimeOptions {
 export declare const RUNTIME_SHELL_DETECT_ROOT = "HARNESS=\"codex\"\nif [ -n \"${CLAUDE_PROJECT_DIR:-}\" ]; then\n  HARNESS=\"claude\"\nelif [ -n \"${CURSOR_PROJECT_DIR:-}\" ] || [ -n \"${CURSOR_PROJECT_ROOT:-}\" ]; then\n  HARNESS=\"cursor\"\nelif [ -n \"${OPENCODE_PROJECT_DIR:-}\" ] || [ -n \"${OPENCODE_PROJECT_ROOT:-}\" ]; then\n  HARNESS=\"opencode\"\nfi\n\nROOT=\"\"\nfor candidate in \"${CCLAW_PROJECT_ROOT:-}\" \"${CLAUDE_PROJECT_DIR:-}\" \"${CURSOR_PROJECT_DIR:-}\" \"${CURSOR_PROJECT_ROOT:-}\" \"${OPENCODE_PROJECT_DIR:-}\" \"${OPENCODE_PROJECT_ROOT:-}\" \"${PWD:-}\"; do\n  if [ -n \"$candidate\" ] && [ -d \"$candidate/.cclaw\" ]; then\n    ROOT=\"$candidate\"\n    break\n  fi\ndone\nif [ -z \"$ROOT\" ]; then\n  ROOT=\"${CCLAW_PROJECT_ROOT:-${CLAUDE_PROJECT_DIR:-${CURSOR_PROJECT_DIR:-${CURSOR_PROJECT_ROOT:-${OPENCODE_PROJECT_DIR:-${OPENCODE_PROJECT_ROOT:-${PWD}}}}}}}\"\nfi";
 export declare function sessionStartScript(_options?: HookRuntimeOptions): string;
 export declare function stopCheckpointScript(): string;
+export declare function runHookDispatcherScript(): string;
 export declare function stageCompleteScript(): string;
 export declare function preCompactScript(): string;
 export { claudeHooksJsonWithObservation as claudeHooksJson } from "./observe.js";
 export { cursorHooksJsonWithObservation as cursorHooksJson } from "./observe.js";
 export { codexHooksJsonWithObservation as codexHooksJson } from "./observe.js";
-export declare function opencodePluginJs(_options?: HookRuntimeOptions): string;
+export { opencodePluginJs } from "./opencode-plugin.js";
 export declare function hooksAgentsMdBlock(): string;

package/dist/content/hooks.js

@@ -769,6 +769,56 @@ case "$HARNESS" in
 esac
 `;
 }
+export function runHookDispatcherScript() {
+    return `#!/usr/bin/env bash
+# cclaw hook dispatcher — generated by cclaw sync
+# Single entrypoint used by harness hook JSON wiring.
+set -euo pipefail
+
+${DETECT_ROOT}
+
+if [ "$#" -lt 1 ]; then
+  printf 'Usage: bash ${RUNTIME_ROOT}/hooks/run-hook.cmd <session-start|stop-checkpoint|pre-compact|prompt-guard|workflow-guard|context-monitor>\\n' >&2
+  exit 1
+fi
+
+HOOK_NAME="$1"
+shift || true
+
+case "$HOOK_NAME" in
+  session-start|session-start.sh)
+    HOOK_FILE="session-start.sh"
+    ;;
+  stop-checkpoint|stop-checkpoint.sh)
+    HOOK_FILE="stop-checkpoint.sh"
+    ;;
+  pre-compact|pre-compact.sh)
+    HOOK_FILE="pre-compact.sh"
+    ;;
+  prompt-guard|prompt-guard.sh)
+    HOOK_FILE="prompt-guard.sh"
+    ;;
+  workflow-guard|workflow-guard.sh)
+    HOOK_FILE="workflow-guard.sh"
+    ;;
+  context-monitor|context-monitor.sh)
+    HOOK_FILE="context-monitor.sh"
+    ;;
+  *)
+    printf '[cclaw] run-hook: unsupported hook "%s".\\n' "$HOOK_NAME" >&2
+    exit 1
+    ;;
+esac
+
+HOOK_PATH="$ROOT/${RUNTIME_ROOT}/hooks/$HOOK_FILE"
+if [ ! -f "$HOOK_PATH" ]; then
+  printf '[cclaw] run-hook: hook script not found at %s\\n' "$HOOK_PATH" >&2
+  exit 1
+fi
+
+exec bash "$HOOK_PATH" "$@"
+`;
+}
 export function stageCompleteScript() {
     return `#!/usr/bin/env bash
 # cclaw stage-complete helper — generated by cclaw sync
@@ -952,293 +1002,7 @@ export { codexHooksJsonWithObservation as codexHooksJson } from "./observe.js";
 // ---------------------------------------------------------------------------
 // OpenCode plugin — JS module
 // ---------------------------------------------------------------------------
-export function opencodePluginJs(_options = {}) {
-    return `// cclaw OpenCode plugin — generated by cclaw sync
-import { existsSync, mkdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-
-export default function cclawPlugin(ctx) {
-  const root = ctx.directory || process.cwd();
-  const runtimeDir = join(root, "${RUNTIME_ROOT}");
-  const stateDir = join(runtimeDir, "state");
-  const flowStatePath = join(stateDir, "flow-state.json");
-  const checkpointPath = join(stateDir, "checkpoint.json");
-  const activityPath = join(stateDir, "stage-activity.jsonl");
-  const contextWarningsPath = join(stateDir, "context-warnings.jsonl");
-  const contextModePath = join(stateDir, "context-mode.json");
-  const contextsDir = join(runtimeDir, "contexts");
-  const sessionDigestPath = join(stateDir, "session-digest.md");
-  const knowledgePath = join(runtimeDir, "knowledge.jsonl");
-  const knowledgeDigestPath = join(stateDir, "knowledge-digest.md");
-  const metaSkillPath = join(runtimeDir, "skills/${META_SKILL_NAME}/SKILL.md");
-
-  function ensureRuntimeDirs() {
-    try {
-      mkdirSync(runtimeDir, { recursive: true });
-    } catch {
-      // ignore
-    }
-    try {
-      mkdirSync(stateDir, { recursive: true });
-    } catch {
-      // ignore
-    }
-  }
-
-  function readFlowState() {
-    try {
-      const raw = readFileSync(flowStatePath, "utf8");
-      const state = JSON.parse(raw);
-      return {
-        stage: typeof state.currentStage === "string" ? state.currentStage : "none",
-        completed: Array.isArray(state.completedStages) ? state.completedStages.length : 0,
-        activeRunId: typeof state.activeRunId === "string" ? state.activeRunId : "none"
-      };
-    } catch {
-      return { stage: "none", completed: 0, activeRunId: "none" };
-    }
-  }
-
-  function readFileText(filePath) {
-    try {
-      return readFileSync(filePath, "utf8");
-    } catch {
-      return "";
-    }
-  }
-
-  function readTailLines(filePath, maxLines) {
-    const text = readFileText(filePath).trim();
-    if (!text) return [];
-    return text.split(/\\r?\\n/).slice(-maxLines);
-  }
-
-  function readCheckpointSummary() {
-    try {
-      const raw = readFileText(checkpointPath);
-      if (!raw) return "";
-      const cp = JSON.parse(raw);
-      return \`Checkpoint: stage=\${cp.stage || "none"}, status=\${cp.status || "unknown"}, run=\${cp.runId || "none"}, at=\${cp.timestamp || "unknown"}\`;
-    } catch {
-      return "";
-    }
-  }
-
-  function readContextMode() {
-    let mode = "default";
-    try {
-      const parsed = JSON.parse(readFileText(contextModePath));
-      if (parsed && typeof parsed.activeMode === "string" && parsed.activeMode.trim().length > 0) {
-        mode = parsed.activeMode.trim();
-      }
-    } catch {
-      // keep default
-    }
-    const guidePath = join(contextsDir, mode + ".md");
-    const guide = existsSync(guidePath) ? "${RUNTIME_ROOT}/contexts/" + mode + ".md" : "";
-    return { mode, guide };
-  }
-
-  function readRecentActivity() {
-    try {
-      const lines = readTailLines(activityPath, 5);
-      if (lines.length === 0) return [];
-      return lines
-        .map((line) => {
-          try {
-            return JSON.parse(line);
-          } catch {
-            return null;
-          }
-        })
-        .filter(Boolean)
-        .map((entry) => \`- \${entry.ts || "unknown"} [\${entry.phase || "unknown"}] \${entry.tool || "unknown"} (stage=\${entry.stage || "unknown"}, run=\${entry.runId || "none"})\`);
-    } catch {
-      return [];
-    }
-  }
-
-  function readLatestContextWarning() {
-    try {
-      const line = readTailLines(contextWarningsPath, 1)[0];
-      if (!line) return "";
-      try {
-        const parsed = JSON.parse(line);
-        if (parsed && typeof parsed.note === "string") return parsed.note;
-      } catch {
-        // non-json fallback
-      }
-      return line;
-    } catch {
-      return "";
-    }
-  }
-
-  function readKnowledgeDigest() {
-    const digest = readFileText(knowledgeDigestPath).trim();
-    if (!digest) {
-      return readTailLines(knowledgePath, 12);
-    }
-    return digest
-      .split(/\\r?\\n/)
-      .map((line) => line.trim())
-      .filter((line) => line.length > 0)
-      .filter((line) => !line.startsWith("#"));
-  }
-
-  function buildBootstrap() {
-    const flow = readFlowState();
-    const parts = [
-      \`cclaw loaded. Flow: stage=\${flow.stage} (\${flow.completed}/8 completed, run=\${flow.activeRunId}). Active artifacts: ${RUNTIME_ROOT}/artifacts/\`
-    ];
-    const contextMode = readContextMode();
-    parts.push(
-      contextMode.guide
-        ? \`Context mode: \${contextMode.mode} (guide: \${contextMode.guide})\`
-        : \`Context mode: \${contextMode.mode}\`
-    );
-
-    const checkpoint = readCheckpointSummary();
-    if (checkpoint) parts.push(checkpoint);
-
-    const digest = readFileText(sessionDigestPath).trim();
-    if (digest) parts.push("Last session:", digest);
-
-    const activity = readRecentActivity();
-    if (activity.length > 0) parts.push("Recent stage activity:", ...activity);
-
-    const warning = readLatestContextWarning();
-    if (warning) parts.push("Latest context warning:", warning);
-
-    const knowledge = readKnowledgeDigest();
-    if (knowledge.length > 0) parts.push("Knowledge digest (top relevant entries):", ...knowledge);
-
-    parts.push(
-      "If you discover a non-obvious rule or pattern, append one strict-schema JSON line to .cclaw/knowledge.jsonl using type: rule, pattern, lesson, or compound."
-    );
-
-    const meta = readFileText(metaSkillPath).trim();
-    if (meta) parts.push("", meta);
-    return parts.join("\\n");
-  }
-
-  let bootstrapCache = "";
-
-  function refreshBootstrapCache() {
-    bootstrapCache = buildBootstrap();
-  }
-
-  function getBootstrap() {
-    if (!bootstrapCache) refreshBootstrapCache();
-    return bootstrapCache;
-  }
-
-  async function runHookScript(scriptFileName, payload = {}) {
-    const { spawnSync } = await import("node:child_process");
-    const scriptPath = join(root, "${RUNTIME_ROOT}/hooks/" + scriptFileName);
-    const input = typeof payload === "string" ? payload : JSON.stringify(payload ?? {});
-    try {
-      const result = spawnSync("bash", [scriptPath], {
-        cwd: root,
-        timeout: 20000,
-        stdio: ["pipe", "ignore", "ignore"],
-        input
-      });
-      return typeof result.status === "number" ? result.status === 0 : false;
-    } catch {
-      return false;
-    }
-  }
-
-  function normalizeToolPayload(input, output) {
-    if (typeof output === "undefined") return input ?? {};
-    return { input: input ?? {}, output: output ?? {} };
-  }
-
-  function resolveEventType(payload) {
-    if (typeof payload === "string") return payload;
-    if (payload && typeof payload === "object") {
-      if (typeof payload.type === "string") return payload.type;
-      if (typeof payload.name === "string") return payload.name;
-      if (payload.event && typeof payload.event === "object") {
-        if (typeof payload.event.type === "string") return payload.event.type;
-        if (typeof payload.event.name === "string") return payload.event.name;
-      }
-    }
-    return "";
-  }
-
-  function resolveEventData(payload) {
-    if (payload && typeof payload === "object" && payload.event && typeof payload.event === "object") {
-      return payload.event;
-    }
-    return payload;
-  }
-
-  ensureRuntimeDirs();
-
-  return {
-    event: async (payload) => {
-      const eventType = resolveEventType(payload);
-      const eventData = resolveEventData(payload);
-      if (
-        eventType === "session.created" ||
-        eventType === "session.resumed" ||
-        eventType === "session.compacted" ||
-        eventType === "session.cleared"
-      ) {
-        // Avoid writing directly to stdout in lifecycle hooks because it can
-        // interfere with OpenCode TUI rendering. Bootstrap is injected via
-        // the system transform hook instead.
-        refreshBootstrapCache();
-      }
-      if (eventType === "session.idle") {
-        await runHookScript("stop-checkpoint.sh", { loop_count: 0 });
-      }
-      if (eventType === "tool.execute.before") {
-        const toolPayload = normalizeToolPayload(eventData, undefined);
-        const promptOk = await runHookScript("prompt-guard.sh", toolPayload);
-        const workflowOk = await runHookScript("workflow-guard.sh", toolPayload);
-        if (!promptOk || !workflowOk) {
-          throw new Error(
-            "cclaw OpenCode guard blocked tool.execute.before (prompt/workflow guard non-zero exit)."
-          );
-        }
-      }
-      if (eventType === "tool.execute.after") {
-        const toolPayload = normalizeToolPayload(eventData, undefined);
-        await runHookScript("context-monitor.sh", toolPayload);
-      }
-    },
-    "tool.execute.before": async (input, output) => {
-      const payload = normalizeToolPayload(input, output);
-      const promptOk = await runHookScript("prompt-guard.sh", payload);
-      const workflowOk = await runHookScript("workflow-guard.sh", payload);
-      if (!promptOk || !workflowOk) {
-        throw new Error(
-          "cclaw OpenCode guard blocked tool.execute.before (prompt/workflow guard non-zero exit)."
-        );
-      }
-    },
-    "tool.execute.after": async (input, output) => {
-      const payload = normalizeToolPayload(input, output);
-      await runHookScript("context-monitor.sh", payload);
-    },
-    "experimental.chat.system.transform": (payload) => {
-      const bootstrap = getBootstrap();
-      if (typeof payload === "string") {
-        return payload.includes("cclaw loaded.") ? payload : \`\${payload}\\n\\n\${bootstrap}\`;
-      }
-      if (payload && typeof payload === "object" && typeof payload.system === "string") {
-        if (payload.system.includes("cclaw loaded.")) return payload;
-        return { ...payload, system: \`\${payload.system}\\n\\n\${bootstrap}\` };
-      }
-      return payload;
-    }
-  };
-}
-`;
-}
+export { opencodePluginJs } from "./opencode-plugin.js";
 // ---------------------------------------------------------------------------
 // AGENTS.md block for hooks
 // ---------------------------------------------------------------------------

package/dist/content/observe.d.ts

@@ -19,9 +19,6 @@ export declare function observeScript(): string;
 export declare function contextMonitorScript(): string;
 export declare function summarizeObservationsRuntimeModule(): string;
 export declare function summarizeObservationsScript(): string;
-/**
- * Updated hooks.json generators with PreToolUse/PostToolUse observation.
- */
 export declare function claudeHooksJsonWithObservation(): string;
 export declare function cursorHooksJsonWithObservation(): string;
 /**

package/dist/content/observe.js

@@ -1808,6 +1808,9 @@ exit 0
 /**
  * Updated hooks.json generators with PreToolUse/PostToolUse observation.
  */
+function hookDispatcherCommand(scriptName) {
+    return `bash ${RUNTIME_ROOT}/hooks/run-hook.cmd ${scriptName}`;
+}
 export function claudeHooksJsonWithObservation() {
     return JSON.stringify({
         cclawHookSchemaVersion: 1,
@@ -1816,30 +1819,30 @@ export function claudeHooksJsonWithObservation() {
                     matcher: "startup|resume|clear|compact",
                     hooks: [{
                             type: "command",
-                            command: `bash ${RUNTIME_ROOT}/hooks/session-start.sh`
+                            command: hookDispatcherCommand("session-start.sh")
                         }]
                 }],
             PreToolUse: [{
                     matcher: "*",
                     hooks: [{
                             type: "command",
-                            command: `bash ${RUNTIME_ROOT}/hooks/prompt-guard.sh`
+                            command: hookDispatcherCommand("prompt-guard.sh")
                         }, {
                             type: "command",
-                            command: `bash ${RUNTIME_ROOT}/hooks/workflow-guard.sh`
+                            command: hookDispatcherCommand("workflow-guard.sh")
                         }]
                 }],
             PostToolUse: [{
                     matcher: "*",
                     hooks: [{
                             type: "command",
-                            command: `bash ${RUNTIME_ROOT}/hooks/context-monitor.sh`
+                            command: hookDispatcherCommand("context-monitor.sh")
                         }]
                 }],
             Stop: [{
                     hooks: [{
                             type: "command",
-                            command: `bash ${RUNTIME_ROOT}/hooks/stop-checkpoint.sh`,
+                            command: hookDispatcherCommand("stop-checkpoint.sh"),
                             timeout: 10
                         }]
                 }],
@@ -1847,7 +1850,7 @@ export function claudeHooksJsonWithObservation() {
                     matcher: "manual|auto",
                     hooks: [{
                             type: "command",
-                            command: `bash ${RUNTIME_ROOT}/hooks/pre-compact.sh`,
+                            command: hookDispatcherCommand("pre-compact.sh"),
                             timeout: 10
                         }]
                 }]
@@ -1860,31 +1863,31 @@ export function cursorHooksJsonWithObservation() {
         version: 1,
         hooks: {
             sessionStart: [{
-                    command: `bash ${RUNTIME_ROOT}/hooks/session-start.sh`
+                    command: hookDispatcherCommand("session-start.sh")
                 }],
             sessionResume: [{
-                    command: `bash ${RUNTIME_ROOT}/hooks/session-start.sh`
+                    command: hookDispatcherCommand("session-start.sh")
                 }],
             sessionClear: [{
-                    command: `bash ${RUNTIME_ROOT}/hooks/session-start.sh`
+                    command: hookDispatcherCommand("session-start.sh")
                 }],
             sessionCompact: [{
-                    command: `bash ${RUNTIME_ROOT}/hooks/pre-compact.sh`
+                    command: hookDispatcherCommand("pre-compact.sh")
                 }, {
-                    command: `bash ${RUNTIME_ROOT}/hooks/session-start.sh`
+                    command: hookDispatcherCommand("session-start.sh")
                 }],
             preToolUse: [{
                     matcher: "*",
-                    command: `bash ${RUNTIME_ROOT}/hooks/prompt-guard.sh`
+                    command: hookDispatcherCommand("prompt-guard.sh")
                 }, {
                     matcher: "*",
-                    command: `bash ${RUNTIME_ROOT}/hooks/workflow-guard.sh`
+                    command: hookDispatcherCommand("workflow-guard.sh")
                 }],
             postToolUse: [{
                     matcher: "*",
-                    command: `bash ${RUNTIME_ROOT}/hooks/context-monitor.sh`
+                    command: hookDispatcherCommand("context-monitor.sh")
                 }],
-            stop: [{ command: `bash ${RUNTIME_ROOT}/hooks/stop-checkpoint.sh`, timeout: 10 }]
+            stop: [{ command: hookDispatcherCommand("stop-checkpoint.sh"), timeout: 10 }]
         }
     }, null, 2);
 }
@@ -1915,13 +1918,13 @@ export function codexHooksJsonWithObservation() {
                     matcher: "startup|resume",
                     hooks: [{
                             type: "command",
-                            command: `bash ${RUNTIME_ROOT}/hooks/session-start.sh`
+                            command: hookDispatcherCommand("session-start.sh")
                         }]
                 }],
             UserPromptSubmit: [{
                     hooks: [{
                             type: "command",
-                            command: `bash ${RUNTIME_ROOT}/hooks/prompt-guard.sh`
+                            command: hookDispatcherCommand("prompt-guard.sh")
                         }, {
                             type: "command",
                             command: "bash -lc 'if command -v cclaw >/dev/null 2>&1; then cclaw internal verify-current-state --quiet >/dev/null || true; else npx -y cclaw-cli internal verify-current-state --quiet >/dev/null || true; fi'"
@@ -1931,23 +1934,23 @@ export function codexHooksJsonWithObservation() {
                     matcher: "Bash",
                     hooks: [{
                             type: "command",
-                            command: `bash ${RUNTIME_ROOT}/hooks/prompt-guard.sh`
+                            command: hookDispatcherCommand("prompt-guard.sh")
                         }, {
                             type: "command",
-                            command: `bash ${RUNTIME_ROOT}/hooks/workflow-guard.sh`
+                            command: hookDispatcherCommand("workflow-guard.sh")
                         }]
                 }],
             PostToolUse: [{
                     matcher: "Bash",
                     hooks: [{
                             type: "command",
-                            command: `bash ${RUNTIME_ROOT}/hooks/context-monitor.sh`
+                            command: hookDispatcherCommand("context-monitor.sh")
                         }]
                 }],
             Stop: [{
                     hooks: [{
                             type: "command",
-                            command: `bash ${RUNTIME_ROOT}/hooks/stop-checkpoint.sh`,
+                            command: hookDispatcherCommand("stop-checkpoint.sh"),
                             timeout: 10
                         }]
                 }]

package/dist/content/opencode-plugin.d.ts

@@ -0,0 +1 @@
+export declare function opencodePluginJs(_options?: Record<string, never>): string;

package/dist/content/opencode-plugin.js

@@ -0,0 +1,289 @@
+import { RUNTIME_ROOT } from "../constants.js";
+import { META_SKILL_NAME } from "./meta-skill.js";
+export function opencodePluginJs(_options = {}) {
+    return `// cclaw OpenCode plugin — generated by cclaw sync
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export default function cclawPlugin(ctx) {
+  const root = ctx.directory || process.cwd();
+  const runtimeDir = join(root, "${RUNTIME_ROOT}");
+  const stateDir = join(runtimeDir, "state");
+  const flowStatePath = join(stateDir, "flow-state.json");
+  const checkpointPath = join(stateDir, "checkpoint.json");
+  const activityPath = join(stateDir, "stage-activity.jsonl");
+  const contextWarningsPath = join(stateDir, "context-warnings.jsonl");
+  const contextModePath = join(stateDir, "context-mode.json");
+  const contextsDir = join(runtimeDir, "contexts");
+  const sessionDigestPath = join(stateDir, "session-digest.md");
+  const knowledgePath = join(runtimeDir, "knowledge.jsonl");
+  const knowledgeDigestPath = join(stateDir, "knowledge-digest.md");
+  const metaSkillPath = join(runtimeDir, "skills/${META_SKILL_NAME}/SKILL.md");
+
+  function ensureRuntimeDirs() {
+    try {
+      mkdirSync(runtimeDir, { recursive: true });
+    } catch {
+      // ignore
+    }
+    try {
+      mkdirSync(stateDir, { recursive: true });
+    } catch {
+      // ignore
+    }
+  }
+
+  function readFlowState() {
+    try {
+      const raw = readFileSync(flowStatePath, "utf8");
+      const state = JSON.parse(raw);
+      return {
+        stage: typeof state.currentStage === "string" ? state.currentStage : "none",
+        completed: Array.isArray(state.completedStages) ? state.completedStages.length : 0,
+        activeRunId: typeof state.activeRunId === "string" ? state.activeRunId : "none"
+      };
+    } catch {
+      return { stage: "none", completed: 0, activeRunId: "none" };
+    }
+  }
+
+  function readFileText(filePath) {
+    try {
+      return readFileSync(filePath, "utf8");
+    } catch {
+      return "";
+    }
+  }
+
+  function readTailLines(filePath, maxLines) {
+    const text = readFileText(filePath).trim();
+    if (!text) return [];
+    return text.split(/\\r?\\n/).slice(-maxLines);
+  }
+
+  function readCheckpointSummary() {
+    try {
+      const raw = readFileText(checkpointPath);
+      if (!raw) return "";
+      const cp = JSON.parse(raw);
+      return \`Checkpoint: stage=\${cp.stage || "none"}, status=\${cp.status || "unknown"}, run=\${cp.runId || "none"}, at=\${cp.timestamp || "unknown"}\`;
+    } catch {
+      return "";
+    }
+  }
+
+  function readContextMode() {
+    let mode = "default";
+    try {
+      const parsed = JSON.parse(readFileText(contextModePath));
+      if (parsed && typeof parsed.activeMode === "string" && parsed.activeMode.trim().length > 0) {
+        mode = parsed.activeMode.trim();
+      }
+    } catch {
+      // keep default
+    }
+    const guidePath = join(contextsDir, mode + ".md");
+    const guide = existsSync(guidePath) ? "${RUNTIME_ROOT}/contexts/" + mode + ".md" : "";
+    return { mode, guide };
+  }
+
+  function readRecentActivity() {
+    try {
+      const lines = readTailLines(activityPath, 5);
+      if (lines.length === 0) return [];
+      return lines
+        .map((line) => {
+          try {
+            return JSON.parse(line);
+          } catch {
+            return null;
+          }
+        })
+        .filter(Boolean)
+        .map((entry) => \`- \${entry.ts || "unknown"} [\${entry.phase || "unknown"}] \${entry.tool || "unknown"} (stage=\${entry.stage || "unknown"}, run=\${entry.runId || "none"})\`);
+    } catch {
+      return [];
+    }
+  }
+
+  function readLatestContextWarning() {
+    try {
+      const line = readTailLines(contextWarningsPath, 1)[0];
+      if (!line) return "";
+      try {
+        const parsed = JSON.parse(line);
+        if (parsed && typeof parsed.note === "string") return parsed.note;
+      } catch {
+        // non-json fallback
+      }
+      return line;
+    } catch {
+      return "";
+    }
+  }
+
+  function readKnowledgeDigest() {
+    const digest = readFileText(knowledgeDigestPath).trim();
+    if (!digest) {
+      return readTailLines(knowledgePath, 12);
+    }
+    return digest
+      .split(/\\r?\\n/)
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0)
+      .filter((line) => !line.startsWith("#"));
+  }
+
+  function buildBootstrap() {
+    const flow = readFlowState();
+    const parts = [
+      \`cclaw loaded. Flow: stage=\${flow.stage} (\${flow.completed}/8 completed, run=\${flow.activeRunId}). Active artifacts: ${RUNTIME_ROOT}/artifacts/\`
+    ];
+    const contextMode = readContextMode();
+    parts.push(
+      contextMode.guide
+        ? \`Context mode: \${contextMode.mode} (guide: \${contextMode.guide})\`
+        : \`Context mode: \${contextMode.mode}\`
+    );
+
+    const checkpoint = readCheckpointSummary();
+    if (checkpoint) parts.push(checkpoint);
+
+    const digest = readFileText(sessionDigestPath).trim();
+    if (digest) parts.push("Last session:", digest);
+
+    const activity = readRecentActivity();
+    if (activity.length > 0) parts.push("Recent stage activity:", ...activity);
+
+    const warning = readLatestContextWarning();
+    if (warning) parts.push("Latest context warning:", warning);
+
+    const knowledge = readKnowledgeDigest();
+    if (knowledge.length > 0) parts.push("Knowledge digest (top relevant entries):", ...knowledge);
+
+    parts.push(
+      "If you discover a non-obvious rule or pattern, append one strict-schema JSON line to .cclaw/knowledge.jsonl using type: rule, pattern, lesson, or compound."
+    );
+
+    const meta = readFileText(metaSkillPath).trim();
+    if (meta) parts.push("", meta);
+    return parts.join("\\n");
+  }
+
+  let bootstrapCache = "";
+
+  function refreshBootstrapCache() {
+    bootstrapCache = buildBootstrap();
+  }
+
+  function getBootstrap() {
+    if (!bootstrapCache) refreshBootstrapCache();
+    return bootstrapCache;
+  }
+
+  async function runHookScript(scriptFileName, payload = {}) {
+    const { spawnSync } = await import("node:child_process");
+    const scriptPath = join(root, "${RUNTIME_ROOT}/hooks/" + scriptFileName);
+    const input = typeof payload === "string" ? payload : JSON.stringify(payload ?? {});
+    try {
+      const result = spawnSync("bash", [scriptPath], {
+        cwd: root,
+        timeout: 20000,
+        stdio: ["pipe", "ignore", "ignore"],
+        input
+      });
+      return typeof result.status === "number" ? result.status === 0 : false;
+    } catch {
+      return false;
+    }
+  }
+
+  function normalizeToolPayload(input, output) {
+    if (typeof output === "undefined") return input ?? {};
+    return { input: input ?? {}, output: output ?? {} };
+  }
+
+  function resolveEventType(payload) {
+    if (typeof payload === "string") return payload;
+    if (payload && typeof payload === "object") {
+      if (typeof payload.type === "string") return payload.type;
+      if (typeof payload.name === "string") return payload.name;
+      if (payload.event && typeof payload.event === "object") {
+        if (typeof payload.event.type === "string") return payload.event.type;
+        if (typeof payload.event.name === "string") return payload.event.name;
+      }
+    }
+    return "";
+  }
+
+  function resolveEventData(payload) {
+    if (payload && typeof payload === "object" && payload.event && typeof payload.event === "object") {
+      return payload.event;
+    }
+    return payload;
+  }
+
+  ensureRuntimeDirs();
+
+  return {
+    event: async (payload) => {
+      const eventType = resolveEventType(payload);
+      const eventData = resolveEventData(payload);
+      if (
+        eventType === "session.created" ||
+        eventType === "session.resumed" ||
+        eventType === "session.compacted" ||
+        eventType === "session.cleared"
+      ) {
+        // Avoid writing directly to stdout in lifecycle hooks because it can
+        // interfere with OpenCode TUI rendering. Bootstrap is injected via
+        // the system transform hook instead.
+        refreshBootstrapCache();
+      }
+      if (eventType === "session.idle") {
+        await runHookScript("stop-checkpoint.sh", { loop_count: 0 });
+      }
+      if (eventType === "tool.execute.before") {
+        const toolPayload = normalizeToolPayload(eventData, undefined);
+        const promptOk = await runHookScript("prompt-guard.sh", toolPayload);
+        const workflowOk = await runHookScript("workflow-guard.sh", toolPayload);
+        if (!promptOk || !workflowOk) {
+          throw new Error(
+            "cclaw OpenCode guard blocked tool.execute.before (prompt/workflow guard non-zero exit)."
+          );
+        }
+      }
+      if (eventType === "tool.execute.after") {
+        const toolPayload = normalizeToolPayload(eventData, undefined);
+        await runHookScript("context-monitor.sh", toolPayload);
+      }
+    },
+    "tool.execute.before": async (input, output) => {
+      const payload = normalizeToolPayload(input, output);
+      const promptOk = await runHookScript("prompt-guard.sh", payload);
+      const workflowOk = await runHookScript("workflow-guard.sh", payload);
+      if (!promptOk || !workflowOk) {
+        throw new Error(
+          "cclaw OpenCode guard blocked tool.execute.before (prompt/workflow guard non-zero exit)."
+        );
+      }
+    },
+    "tool.execute.after": async (input, output) => {
+      const payload = normalizeToolPayload(input, output);
+      await runHookScript("context-monitor.sh", payload);
+    },
+    "experimental.chat.system.transform": (payload) => {
+      const bootstrap = getBootstrap();
+      if (typeof payload === "string") {
+        return payload.includes("cclaw loaded.") ? payload : \`\${payload}\\n\\n\${bootstrap}\`;
+      }
+      if (payload && typeof payload === "object" && typeof payload.system === "string") {
+        if (payload.system.includes("cclaw loaded.")) return payload;
+        return { ...payload, system: \`\${payload.system}\\n\\n\${bootstrap}\` };
+      }
+      return payload;
+    }
+  };
+}
+`;
+}

package/dist/doctor.js

@@ -622,6 +622,7 @@ export async function doctorChecks(projectRoot, options = {}) {
     for (const script of [
         "session-start.sh",
         "stop-checkpoint.sh",
+        "run-hook.cmd",
         "prompt-guard.sh",
         "workflow-guard.sh",
         "context-monitor.sh"

package/dist/install.js

@@ -23,7 +23,7 @@ import { archiveCommandContract, archiveCommandSkillMarkdown } from "./content/a
 import { rewindCommandContract, rewindCommandSkillMarkdown } from "./content/rewind-command.js";
 import { subagentDrivenDevSkill, parallelAgentsSkill } from "./content/subagents.js";
 import { sessionHooksSkillMarkdown } from "./content/session-hooks.js";
-import { sessionStartScript, stopCheckpointScript, stageCompleteScript, preCompactScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
+import { sessionStartScript, stopCheckpointScript, runHookDispatcherScript, stageCompleteScript, preCompactScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
 import { contextMonitorScript, promptGuardScript, workflowGuardScript } from "./content/observe.js";
 import { META_SKILL_NAME, usingCclawSkillMarkdown } from "./content/meta-skill.js";
 import { decisionProtocolMarkdown, completionProtocolMarkdown, ethosProtocolMarkdown } from "./content/protocols.js";
@@ -616,6 +616,7 @@ async function writeHooks(projectRoot, config) {
     await ensureDir(hooksDir);
     await writeFileSafe(path.join(hooksDir, "session-start.sh"), sessionStartScript());
     await writeFileSafe(path.join(hooksDir, "stop-checkpoint.sh"), stopCheckpointScript());
+    await writeFileSafe(path.join(hooksDir, "run-hook.cmd"), runHookDispatcherScript());
     await writeFileSafe(path.join(hooksDir, "stage-complete.sh"), stageCompleteScript());
     await writeFileSafe(path.join(hooksDir, "pre-compact.sh"), preCompactScript());
     await writeFileSafe(path.join(hooksDir, "prompt-guard.sh"), promptGuardScript({
@@ -633,6 +634,7 @@ async function writeHooks(projectRoot, config) {
         for (const script of [
             "session-start.sh",
             "stop-checkpoint.sh",
+            "run-hook.cmd",
             "stage-complete.sh",
             "pre-compact.sh",
             "prompt-guard.sh",
@@ -1263,7 +1265,8 @@ function stripManagedHookCommands(value) {
 }
 function isManagedRuntimeHookCommand(command) {
     const normalized = command.trim().replace(/\s+/gu, " ");
-    if (/(^|\s)(?:bash\s+)?(?:\.\/)?\.cclaw\/hooks\/(?:session-start|stop-checkpoint|pre-compact|prompt-guard|workflow-guard|context-monitor)\.sh(?:\s|$)/u.test(normalized)) {
+    if (/(^|\s)(?:bash\s+)?(?:\.\/)?\.cclaw\/hooks\/(?:session-start|stop-checkpoint|pre-compact|prompt-guard|workflow-guard|context-monitor)\.sh(?:\s|$)/u.test(normalized) ||
+        /(^|\s)(?:bash\s+)?(?:\.\/)?\.cclaw\/hooks\/run-hook\.cmd\s+(?:session-start|stop-checkpoint|pre-compact|prompt-guard|workflow-guard|context-monitor)(?:\.sh)?(?:\s|$)/u.test(normalized)) {
         return true;
     }
     // Codex UserPromptSubmit non-blocking state nudge:

package/package.json

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