cclaw-cli 0.1.0

package/dist/content/hooks.js

@@ -0,0 +1,753 @@
+/**
+ * Hook generators for all supported harnesses.
+ *
+ * SessionStart: injects using-cclaw + flow state + learnings + checkpoint/activity summary.
+ * Stop: writes checkpoint.json and reminds about flow consistency.
+ * PreToolUse/PostToolUse and summarize chain are generated in observe.ts.
+ */
+import { RUNTIME_ROOT } from "../constants.js";
+import { META_SKILL_NAME } from "./meta-skill.js";
+const ESCAPE_FN = `escape_json() {
+  local str="$1"
+  str=\${str//\\\\/\\\\\\\\}
+  str=\${str//\\"/\\\\\\"}
+  str=\${str//$'\\t'/\\\\t}
+  str=\${str//$'\\n'/\\\\n}
+  printf '%s' "$str"
+}`;
+const DETECT_ROOT = `HARNESS="codex"
+if [ -n "\${CLAUDE_PROJECT_DIR:-}" ]; then
+  HARNESS="claude"
+elif [ -n "\${CURSOR_PROJECT_DIR:-}" ] || [ -n "\${CURSOR_PROJECT_ROOT:-}" ]; then
+  HARNESS="cursor"
+elif [ -n "\${OPENCODE_PROJECT_DIR:-}" ] || [ -n "\${OPENCODE_PROJECT_ROOT:-}" ]; then
+  HARNESS="opencode"
+fi
+
+ROOT=""
+for candidate in "\${CCLAW_PROJECT_ROOT:-}" "\${CLAUDE_PROJECT_DIR:-}" "\${CURSOR_PROJECT_DIR:-}" "\${CURSOR_PROJECT_ROOT:-}" "\${OPENCODE_PROJECT_DIR:-}" "\${OPENCODE_PROJECT_ROOT:-}" "\${PWD:-}"; do
+  if [ -n "$candidate" ] && [ -d "$candidate/${RUNTIME_ROOT}" ]; then
+    ROOT="$candidate"
+    break
+  fi
+done
+if [ -z "$ROOT" ]; then
+  ROOT="\${CCLAW_PROJECT_ROOT:-\${CLAUDE_PROJECT_DIR:-\${CURSOR_PROJECT_DIR:-\${CURSOR_PROJECT_ROOT:-\${OPENCODE_PROJECT_DIR:-\${OPENCODE_PROJECT_ROOT:-\${PWD}}}}}}}"
+fi`;
+/** Shared bash preamble for generated hook scripts. */
+export const RUNTIME_SHELL_DETECT_ROOT = DETECT_ROOT;
+export function sessionStartScript() {
+    return `#!/usr/bin/env bash
+# cclaw session-start hook — generated by cclaw sync
+# Injects using-cclaw + flow status + run pointer + top learnings + checkpoint/activity summary.
+set -euo pipefail
+
+${DETECT_ROOT}
+
+STATE_FILE="$ROOT/${RUNTIME_ROOT}/state/flow-state.json"
+CHECKPOINT_FILE="$ROOT/${RUNTIME_ROOT}/state/checkpoint.json"
+ACTIVITY_FILE="$ROOT/${RUNTIME_ROOT}/state/stage-activity.jsonl"
+SUGGESTION_MEMORY_FILE="$ROOT/${RUNTIME_ROOT}/state/suggestion-memory.json"
+CONTEXT_WARNINGS_FILE="$ROOT/${RUNTIME_ROOT}/state/context-warnings.jsonl"
+LEARNINGS_FILE="$ROOT/${RUNTIME_ROOT}/learnings.jsonl"
+META_SKILL="$ROOT/${RUNTIME_ROOT}/skills/${META_SKILL_NAME}/SKILL.md"
+
+# --- Read flow state ---
+STAGE="none"
+COMPLETED="0"
+ACTIVE_RUN="none"
+if [ -f "$STATE_FILE" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    STAGE=$(jq -r '.currentStage // "none"' "$STATE_FILE" 2>/dev/null || echo "none")
+    COMPLETED=$(jq -r '(.completedStages | length) // 0' "$STATE_FILE" 2>/dev/null || echo "0")
+    ACTIVE_RUN=$(jq -r '.activeRunId // "none"' "$STATE_FILE" 2>/dev/null || echo "none")
+  else
+    if command -v python3 >/dev/null 2>&1; then
+      STAGE=$(python3 - "$STATE_FILE" <<'PY'
+import json
+import sys
+
+stage = "none"
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as fh:
+        data = json.load(fh)
+    value = data.get("currentStage")
+    if isinstance(value, str) and value:
+        stage = value
+except Exception:
+    pass
+print(stage)
+PY
+)
+      COMPLETED=$(python3 - "$STATE_FILE" <<'PY'
+import json
+import sys
+
+count = 0
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as fh:
+        data = json.load(fh)
+    value = data.get("completedStages")
+    if isinstance(value, list):
+        count = len(value)
+except Exception:
+    pass
+print(count)
+PY
+)
+      ACTIVE_RUN=$(python3 - "$STATE_FILE" <<'PY'
+import json
+import sys
+
+run = "none"
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as fh:
+        data = json.load(fh)
+    value = data.get("activeRunId")
+    if isinstance(value, str) and value:
+        run = value
+except Exception:
+    pass
+print(run)
+PY
+)
+    else
+      STAGE=$(grep -o '"currentStage"[[:space:]]*:[[:space:]]*"[^"]*"' "$STATE_FILE" 2>/dev/null | head -1 | sed 's/.*"\\([^"]*\\)"$/\\1/' || echo "none")
+      COMPLETED_RAW=$(grep -o '"completedStages"[[:space:]]*:[[:space:]]*\\[[^]]*\\]' "$STATE_FILE" 2>/dev/null | head -1 || echo "")
+      if [ -n "$COMPLETED_RAW" ]; then
+        COMPLETED=$(printf '%s' "$COMPLETED_RAW" | grep -o '"[^"]*"' | wc -l | tr -d ' ' 2>/dev/null || echo "0")
+      else
+        COMPLETED="0"
+      fi
+      ACTIVE_RUN=$(grep -o '"activeRunId"[[:space:]]*:[[:space:]]*"[^"]*"' "$STATE_FILE" 2>/dev/null | head -1 | sed 's/.*"\\([^"]*\\)"$/\\1/' || echo "none")
+    fi
+  fi
+fi
+
+# --- Checkpoint summary ---
+CHECKPOINT_SUMMARY=""
+if [ -f "$CHECKPOINT_FILE" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    CHECKPOINT_SUMMARY=$(jq -r '"Checkpoint: stage=" + (.stage // "none") + ", status=" + (.status // "unknown") + ", run=" + (.runId // "none") + ", at=" + (.timestamp // "unknown")' "$CHECKPOINT_FILE" 2>/dev/null || echo "")
+  elif command -v python3 >/dev/null 2>&1; then
+    CHECKPOINT_SUMMARY=$(python3 - "$CHECKPOINT_FILE" <<'PY'
+import json
+import sys
+
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as fh:
+        data = json.load(fh)
+    stage = data.get("stage", "none")
+    status = data.get("status", "unknown")
+    run_id = data.get("runId", "none")
+    ts = data.get("timestamp", "unknown")
+    print(f"Checkpoint: stage={stage}, status={status}, run={run_id}, at={ts}")
+except Exception:
+    print("")
+PY
+)
+  fi
+fi
+
+# --- Recent stage activity summary ---
+ACTIVITY_SUMMARY=""
+if [ -f "$ACTIVITY_FILE" ] && [ -s "$ACTIVITY_FILE" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    ACTIVITY_SUMMARY=$(tail -n 5 "$ACTIVITY_FILE" 2>/dev/null | jq -r -s '
+      map(select(type=="object"))
+      | map("- " + (.ts // "unknown") + " [" + (.phase // "unknown") + "] " + (.tool // "unknown") + " (stage=" + (.stage // "unknown") + ", run=" + (.runId // "none") + ")")
+      | join("\\n")
+    ' 2>/dev/null || echo "")
+  else
+    ACTIVITY_SUMMARY=$(tail -n 3 "$ACTIVITY_FILE" 2>/dev/null || echo "")
+  fi
+fi
+
+# --- Latest context warning ---
+CONTEXT_WARNING=""
+if [ -f "$CONTEXT_WARNINGS_FILE" ] && [ -s "$CONTEXT_WARNINGS_FILE" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    CONTEXT_WARNING=$(tail -n 1 "$CONTEXT_WARNINGS_FILE" 2>/dev/null | jq -r '.note // ""' 2>/dev/null || echo "")
+  else
+    CONTEXT_WARNING=$(tail -n 1 "$CONTEXT_WARNINGS_FILE" 2>/dev/null || echo "")
+  fi
+fi
+
+# --- Proactive stage suggestion memory (persistent opt-out) ---
+SUGGESTIONS_ENABLED="true"
+STAGE_MUTED="false"
+if [ -f "$SUGGESTION_MEMORY_FILE" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    SUGGESTIONS_ENABLED=$(jq -r 'if (.enabled // true) then "true" else "false" end' "$SUGGESTION_MEMORY_FILE" 2>/dev/null || echo "true")
+    STAGE_MUTED=$(jq -r --arg stage "$STAGE" 'if ((.mutedStages // []) | index($stage)) == null then "false" else "true" end' "$SUGGESTION_MEMORY_FILE" 2>/dev/null || echo "false")
+  elif command -v python3 >/dev/null 2>&1; then
+    SUGGESTIONS_ENABLED=$(python3 - "$SUGGESTION_MEMORY_FILE" <<'PY'
+import json
+import sys
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as handle:
+        value = json.load(handle)
+    enabled = value.get("enabled", True)
+    print("true" if enabled else "false")
+except Exception:
+    print("true")
+PY
+)
+    STAGE_MUTED=$(python3 - "$SUGGESTION_MEMORY_FILE" "$STAGE" <<'PY'
+import json
+import sys
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as handle:
+        value = json.load(handle)
+    muted = value.get("mutedStages", [])
+    print("true" if isinstance(muted, list) and sys.argv[2] in muted else "false")
+except Exception:
+    print("false")
+PY
+)
+  fi
+fi
+
+STAGE_SUGGESTION=""
+if [ "$SUGGESTIONS_ENABLED" = "true" ] && [ "$STAGE_MUTED" != "true" ]; then
+  case "$STAGE" in
+    brainstorm) STAGE_SUGGESTION="Suggestion: list 2-3 alternatives and ask a single focused clarifying question before direction lock." ;;
+    scope) STAGE_SUGGESTION="Suggestion: lock explicit in-scope/out-of-scope boundaries and choose one scope mode." ;;
+    design) STAGE_SUGGESTION="Suggestion: map failure modes per new codepath and confirm architecture boundaries before moving forward." ;;
+    spec) STAGE_SUGGESTION="Suggestion: ensure every acceptance criterion is measurable and mapped to a concrete test." ;;
+    plan) STAGE_SUGGESTION="Suggestion: group tasks into dependency waves and keep WAIT_FOR_CONFIRM pending until approval." ;;
+    test) STAGE_SUGGESTION="Suggestion: RED only in this stage — capture failing output for each selected slice." ;;
+    build) STAGE_SUGGESTION="Suggestion: apply minimal GREEN change, run full suite, then document REFACTOR notes." ;;
+    review) STAGE_SUGGESTION="Suggestion: run Layer 1 before Layer 2 and reconcile findings into 07-review-army.json." ;;
+    ship) STAGE_SUGGESTION="Suggestion: verify preflight + rollback plan before selecting exactly one finalization mode." ;;
+    *) STAGE_SUGGESTION="" ;;
+  esac
+fi
+
+if [ -n "$STAGE_SUGGESTION" ]; then
+  NOW_TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || echo "")
+  TMP_SUGGESTION_FILE="$SUGGESTION_MEMORY_FILE.tmp.$$"
+  if command -v jq >/dev/null 2>&1 && [ -f "$SUGGESTION_MEMORY_FILE" ]; then
+    jq --arg stage "$STAGE" --arg ts "$NOW_TS" '
+      .lastSuggestedStage = $stage
+      | .lastSuggestedAt = $ts
+      | .enabled = (.enabled // true)
+      | .mutedStages = (if (.mutedStages | type) == "array" then .mutedStages else [] end)
+    ' "$SUGGESTION_MEMORY_FILE" > "$TMP_SUGGESTION_FILE" 2>/dev/null || true
+  elif command -v python3 >/dev/null 2>&1; then
+    python3 - "$SUGGESTION_MEMORY_FILE" "$TMP_SUGGESTION_FILE" "$STAGE" "$NOW_TS" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+source = Path(sys.argv[1])
+target = Path(sys.argv[2])
+stage = sys.argv[3]
+ts = sys.argv[4]
+payload = {"enabled": True, "mutedStages": []}
+if source.exists():
+    try:
+        parsed = json.loads(source.read_text(encoding="utf-8"))
+        if isinstance(parsed, dict):
+            payload.update(parsed)
+    except Exception:
+        pass
+if not isinstance(payload.get("mutedStages"), list):
+    payload["mutedStages"] = []
+if not isinstance(payload.get("enabled"), bool):
+    payload["enabled"] = True
+payload["lastSuggestedStage"] = stage
+payload["lastSuggestedAt"] = ts
+target.write_text(json.dumps(payload, indent=2) + "\\n", encoding="utf-8")
+PY
+  fi
+  if [ -s "$TMP_SUGGESTION_FILE" ]; then
+    mv "$TMP_SUGGESTION_FILE" "$SUGGESTION_MEMORY_FILE" 2>/dev/null || rm -f "$TMP_SUGGESTION_FILE" 2>/dev/null || true
+  fi
+fi
+
+# --- Read meta-skill (full file) ---
+META_CONTENT=""
+if [ -f "$META_SKILL" ]; then
+  META_CONTENT=$(cat "$META_SKILL" 2>/dev/null || echo "")
+fi
+
+# --- Read top learnings with decay ---
+LEARNINGS_SUMMARY=""
+if [ -f "$LEARNINGS_FILE" ] && [ -s "$LEARNINGS_FILE" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    NOW_EPOCH=$(date +%s 2>/dev/null || echo "0")
+    LEARNINGS_SUMMARY=$(tail -n 30 "$LEARNINGS_FILE" 2>/dev/null | jq -r -s --arg now "$NOW_EPOCH" '
+      [.[] | select(.key != null)]
+      | group_by([.key, .type])
+      | map(sort_by(.ts) | last)
+      | map(
+          . as $e |
+          (if $e.source == "user-stated" then 0
+           else (try ((($now|tonumber) - ($e.ts // "" | fromdateiso8601)) / 2592000 | floor) catch 0)
+           end) as $months |
+          ($e.confidence - $months) as $eff |
+          . + {effective_confidence: (if $eff < 0 then 0 else $eff end)}
+        )
+      | sort_by(-.effective_confidence)
+      | .[0:3]
+      | map("- " + .key + " (conf " + (.effective_confidence|tostring) + "): " + .insight)
+      | join("\\n")
+    ' 2>/dev/null || echo "")
+  else
+    LEARNINGS_SUMMARY=$(tail -n 3 "$LEARNINGS_FILE" 2>/dev/null || echo "")
+  fi
+fi
+
+# --- Build context message ---
+CTX="cclaw loaded. Flow: stage=$STAGE ($COMPLETED/9 completed, run=$ACTIVE_RUN). Active run artifacts: ${RUNTIME_ROOT}/runs/$ACTIVE_RUN/artifacts/"
+if [ -n "$CHECKPOINT_SUMMARY" ]; then
+  CTX="$CTX
+$CHECKPOINT_SUMMARY"
+fi
+if [ -n "$ACTIVITY_SUMMARY" ]; then
+  CTX="$CTX
+Recent stage activity:
+$ACTIVITY_SUMMARY"
+fi
+if [ -n "$CONTEXT_WARNING" ]; then
+  CTX="$CTX
+Latest context warning:
+$CONTEXT_WARNING"
+fi
+if [ -n "$STAGE_SUGGESTION" ]; then
+  CTX="$CTX
+$STAGE_SUGGESTION
+To disable suggestions persistently set ${RUNTIME_ROOT}/state/suggestion-memory.json -> enabled=false."
+fi
+if [ -n "$LEARNINGS_SUMMARY" ]; then
+  CTX="$CTX
+Top learnings:
+$LEARNINGS_SUMMARY"
+fi
+if [ -n "$META_CONTENT" ]; then
+  CTX="$CTX
+
+$META_CONTENT"
+fi
+
+# --- Escape for JSON ---
+${ESCAPE_FN}
+MSG=$(escape_json "$CTX")
+
+# --- Output harness-specific JSON ---
+case "$HARNESS" in
+  claude)
+    printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\\n' "$MSG"
+    ;;
+  cursor)
+    printf '{"additional_context":"%s"}\\n' "$MSG"
+    ;;
+  codex)
+    printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\\n' "$MSG"
+    ;;
+  *)
+    printf '{"additional_context":"%s"}\\n' "$MSG"
+    ;;
+esac
+`;
+}
+export function stopCheckpointScript() {
+    return `#!/usr/bin/env bash
+# cclaw stop hook — generated by cclaw sync
+# Writes checkpoint state and reminds agent about flow/session consistency.
+set -euo pipefail
+
+${DETECT_ROOT}
+
+INPUT=$(cat 2>/dev/null || echo '{}')
+
+STATE_DIR="$ROOT/${RUNTIME_ROOT}/state"
+STATE_FILE="$STATE_DIR/flow-state.json"
+CHECKPOINT_FILE="$STATE_DIR/checkpoint.json"
+CHECKPOINT_TMP="$STATE_DIR/checkpoint.json.tmp.$$"
+STAGE="none"
+ACTIVE_RUN="none"
+LOOP_COUNT=""
+
+if command -v jq >/dev/null 2>&1; then
+  LOOP_COUNT=$(echo "$INPUT" | jq -r '.loop_count // 0' 2>/dev/null || echo "")
+elif command -v python3 >/dev/null 2>&1; then
+  LOOP_COUNT=$(INPUT_JSON="$INPUT" python3 - <<'PY'
+import json
+import os
+
+try:
+    data = json.loads(os.environ.get("INPUT_JSON", "{}"))
+    print(data.get("loop_count", 0))
+except Exception:
+    print("")
+PY
+)
+fi
+[ -n "$LOOP_COUNT" ] || LOOP_COUNT="0"
+
+if [ -f "$STATE_FILE" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    STAGE=$(jq -r '.currentStage // "none"' "$STATE_FILE" 2>/dev/null || echo "none")
+    ACTIVE_RUN=$(jq -r '.activeRunId // "none"' "$STATE_FILE" 2>/dev/null || echo "none")
+  elif command -v python3 >/dev/null 2>&1; then
+    STAGE=$(python3 - "$STATE_FILE" <<'PY'
+import json
+import sys
+
+stage = "none"
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as fh:
+        data = json.load(fh)
+    value = data.get("currentStage")
+    if isinstance(value, str) and value:
+        stage = value
+except Exception:
+    pass
+print(stage)
+PY
+)
+    ACTIVE_RUN=$(python3 - "$STATE_FILE" <<'PY'
+import json
+import sys
+
+run = "none"
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as fh:
+        data = json.load(fh)
+    value = data.get("activeRunId")
+    if isinstance(value, str) and value:
+        run = value
+except Exception:
+    pass
+print(run)
+PY
+)
+  fi
+fi
+
+DIRTY_STATE="unknown"
+if command -v git >/dev/null 2>&1; then
+  if git -C "$ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    if [ -n "$(git -C "$ROOT" status --porcelain 2>/dev/null)" ]; then
+      DIRTY_STATE="dirty"
+    else
+      DIRTY_STATE="clean"
+    fi
+  fi
+fi
+
+TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || echo "")
+mkdir -p "$STATE_DIR" 2>/dev/null || true
+CHECKPOINT_WRITTEN=0
+
+cleanup_checkpoint_tmp() {
+  rm -f "$CHECKPOINT_TMP" 2>/dev/null || true
+}
+trap cleanup_checkpoint_tmp EXIT INT TERM
+
+if command -v jq >/dev/null 2>&1; then
+  EXISTING_JSON="{}"
+  if [ -f "$CHECKPOINT_FILE" ]; then
+    EXISTING_JSON=$(jq -c '.' "$CHECKPOINT_FILE" 2>/dev/null || echo "{}")
+  fi
+
+  if jq -n \
+    --argjson existing "$EXISTING_JSON" \
+    --arg stage "$STAGE" \
+    --arg run "$ACTIVE_RUN" \
+    --arg ts "$TS" \
+    --arg dirty "$DIRTY_STATE" \
+    --arg harness "$HARNESS" \
+    '
+      ($existing | if type == "object" then . else {} end) as $base
+      | $base + {
+          stage: $stage,
+          runId: $run,
+          status: (if (($base.status // "") | tostring | length) > 0 then ($base.status | tostring) else "in_progress" end),
+          dirtyState: $dirty,
+          lastCompletedStep: (if ($base.lastCompletedStep | type) == "string" then $base.lastCompletedStep else "" end),
+          remainingSteps: (if ($base.remainingSteps | type) == "array" then $base.remainingSteps else [] end),
+          blockers: (if ($base.blockers | type) == "array" then $base.blockers else [] end),
+          harness: $harness,
+          timestamp: $ts
+        }
+    ' > "$CHECKPOINT_TMP" 2>/dev/null; then
+    if mv "$CHECKPOINT_TMP" "$CHECKPOINT_FILE" 2>/dev/null; then
+      CHECKPOINT_WRITTEN=1
+    fi
+  fi
+fi
+
+if [ "$CHECKPOINT_WRITTEN" -eq 0 ] && command -v python3 >/dev/null 2>&1; then
+  if python3 - "$CHECKPOINT_FILE" "$CHECKPOINT_TMP" "$STAGE" "$ACTIVE_RUN" "$DIRTY_STATE" "$HARNESS" "$TS" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+checkpoint_path, checkpoint_tmp_path, stage, run_id, dirty_state, harness, ts = sys.argv[1:8]
+checkpoint_file = Path(checkpoint_path)
+checkpoint_tmp_file = Path(checkpoint_tmp_path)
+payload = {}
+if checkpoint_file.exists():
+    try:
+        current = json.loads(checkpoint_file.read_text(encoding="utf-8"))
+        if isinstance(current, dict):
+            payload = dict(current)
+    except Exception:
+        payload = {}
+
+payload["stage"] = stage
+payload["runId"] = run_id
+payload["dirtyState"] = dirty_state
+payload["harness"] = harness
+payload["timestamp"] = ts
+if not isinstance(payload.get("status"), str) or not payload["status"].strip():
+    payload["status"] = "in_progress"
+if not isinstance(payload.get("lastCompletedStep"), str):
+    payload["lastCompletedStep"] = ""
+if not isinstance(payload.get("remainingSteps"), list):
+    payload["remainingSteps"] = []
+if not isinstance(payload.get("blockers"), list):
+    payload["blockers"] = []
+
+try:
+    checkpoint_tmp_file.write_text(json.dumps(payload, indent=2) + "\\n", encoding="utf-8")
+except Exception:
+    raise SystemExit(1)
+PY
+  then
+    if mv "$CHECKPOINT_TMP" "$CHECKPOINT_FILE" 2>/dev/null; then
+      CHECKPOINT_WRITTEN=1
+    fi
+  fi
+fi
+
+if [ "$CHECKPOINT_WRITTEN" -eq 0 ]; then
+  printf '{\n  "stage": "%s",\n  "runId": "%s",\n  "status": "in_progress",\n  "dirtyState": "%s",\n  "lastCompletedStep": "",\n  "remainingSteps": [],\n  "blockers": [],\n  "harness": "%s",\n  "timestamp": "%s"\n}\n' \
+    "$STAGE" "$ACTIVE_RUN" "$DIRTY_STATE" "$HARNESS" "$TS" > "$CHECKPOINT_TMP" 2>/dev/null || true
+  if [ -s "$CHECKPOINT_TMP" ] && mv "$CHECKPOINT_TMP" "$CHECKPOINT_FILE" 2>/dev/null; then
+    CHECKPOINT_WRITTEN=1
+  fi
+fi
+
+cleanup_checkpoint_tmp
+trap - EXIT INT TERM
+
+CHECKPOINT_NOTE="Checkpoint updated at ${RUNTIME_ROOT}/state/checkpoint.json."
+if [ "$CHECKPOINT_WRITTEN" -eq 0 ]; then
+  CHECKPOINT_NOTE="Checkpoint update failed. Review ${RUNTIME_ROOT}/state/checkpoint.json manually."
+fi
+
+# --- Escape for JSON ---
+${ESCAPE_FN}
+MSG=$(escape_json "Cclaw: session ending (stage=$STAGE, run=$ACTIVE_RUN). $CHECKPOINT_NOTE Before stopping: (1) confirm flow-state reflects reality, (2) ensure artifact changes match active run intent, (3) log reusable learnings, (4) commit or revert pending changes.")
+
+# --- Output harness-specific JSON ---
+case "$HARNESS" in
+  claude)
+    printf '{"systemMessage":"%s"}\\n' "$MSG"
+    ;;
+  cursor)
+    if [ "\${LOOP_COUNT:-0}" -eq 0 ]; then
+      printf '{"followup_message":"%s"}\\n' "$MSG"
+    else
+      printf '{}\\n'
+    fi
+    ;;
+  codex)
+    printf '{"systemMessage":"%s"}\\n' "$MSG"
+    ;;
+  *)
+    printf '{"systemMessage":"%s"}\\n' "$MSG"
+    ;;
+esac
+`;
+}
+// ---------------------------------------------------------------------------
+// hooks.json generators — NOW use observe.ts versions with PreToolUse/PostToolUse
+// These are kept as fallbacks for when observation is disabled.
+// ---------------------------------------------------------------------------
+export { claudeHooksJsonWithObservation as claudeHooksJson } from "./observe.js";
+export { cursorHooksJsonWithObservation as cursorHooksJson } from "./observe.js";
+export { codexHooksJsonWithObservation as codexHooksJson } from "./observe.js";
+// ---------------------------------------------------------------------------
+// OpenCode plugin — JS module
+// ---------------------------------------------------------------------------
+export function opencodePluginJs() {
+    return `// cclaw OpenCode plugin — generated by cclaw sync
+import { closeSync, fstatSync, openSync, readFileSync, readSync } from "node:fs";
+import { join } from "node:path";
+
+export default function cclawPlugin(ctx) {
+  const root = ctx.directory || process.cwd();
+  const checkpointPath = join(root, "${RUNTIME_ROOT}/state/checkpoint.json");
+  const activityPath = join(root, "${RUNTIME_ROOT}/state/stage-activity.jsonl");
+
+  function readFlowState() {
+    try {
+      const raw = readFileSync(join(root, "${RUNTIME_ROOT}/state/flow-state.json"), "utf8");
+      const state = JSON.parse(raw);
+      return {
+        stage: state.currentStage || "none",
+        completed: (state.completedStages || []).length,
+        activeRunId: state.activeRunId || "none",
+      };
+    } catch {
+      return { stage: "none", completed: 0, activeRunId: "none" };
+    }
+  }
+
+  function readMetaSkill() {
+    try {
+      return readFileSync(join(root, "${RUNTIME_ROOT}/skills/${META_SKILL_NAME}/SKILL.md"), "utf8");
+    } catch {
+      return "";
+    }
+  }
+
+  function readTailText(filePath, maxBytes = 65536) {
+    let fd;
+    try {
+      fd = openSync(filePath, "r");
+      const size = fstatSync(fd).size;
+      if (!Number.isFinite(size) || size <= 0) return "";
+      const bytesToRead = Math.min(size, maxBytes);
+      const buffer = Buffer.allocUnsafe(bytesToRead);
+      readSync(fd, buffer, 0, bytesToRead, size - bytesToRead);
+      return buffer.toString("utf8");
+    } catch {
+      return "";
+    } finally {
+      if (fd !== undefined) {
+        try {
+          closeSync(fd);
+        } catch {
+          // ignore
+        }
+      }
+    }
+  }
+
+  function readTailLines(filePath, maxLines, maxBytes = 65536) {
+    const raw = readTailText(filePath, maxBytes).trim();
+    if (!raw) return [];
+    return raw.split(/\\r?\\n/).slice(-maxLines);
+  }
+
+  function readTopLearnings() {
+    try {
+      const lines = readTailLines(join(root, "${RUNTIME_ROOT}/learnings.jsonl"), 30, 65536);
+      if (lines.length === 0) return [];
+      const entries = lines.map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+      const deduped = new Map();
+      for (const e of entries) {
+        const key = e.key + ":" + e.type;
+        if (!deduped.has(key) || e.ts > deduped.get(key).ts) deduped.set(key, e);
+      }
+      const now = Date.now();
+      return [...deduped.values()]
+        .map(e => {
+          const months = e.source === "user-stated" ? 0 : Math.floor((now - new Date(e.ts).getTime()) / (30 * 86400000));
+          const eff = Math.max(0, e.confidence - months);
+          return { ...e, effective_confidence: eff };
+        })
+        .sort((a, b) => b.effective_confidence - a.effective_confidence)
+        .slice(0, 3);
+    } catch {
+      return [];
+    }
+  }
+
+  function readCheckpointSummary() {
+    try {
+      const raw = readFileSync(checkpointPath, "utf8");
+      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 readRecentActivity() {
+    try {
+      const lines = readTailLines(activityPath, 5, 32768);
+      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 buildBootstrap() {
+    const { stage, completed, activeRunId } = readFlowState();
+    const meta = readMetaSkill();
+    const learnings = readTopLearnings();
+    const checkpoint = readCheckpointSummary();
+    const activity = readRecentActivity();
+    const parts = [\`cclaw loaded. Flow: stage=\${stage} (\${completed}/9 completed, run=\${activeRunId}). Active run artifacts: ${RUNTIME_ROOT}/runs/\${activeRunId}/artifacts/\`];
+    if (checkpoint) parts.push(checkpoint);
+    if (activity.length > 0) parts.push("Recent stage activity:", ...activity);
+    if (learnings.length > 0) {
+      parts.push("Top learnings:");
+      for (const l of learnings) parts.push(\`- \${l.key} (conf \${l.effective_confidence}): \${l.insight}\`);
+    }
+    if (meta) parts.push("", meta);
+    return parts.join("\\n");
+  }
+
+  function emitBootstrap() {
+    console.log(buildBootstrap());
+  }
+
+  return {
+    "session.created": emitBootstrap,
+    "session.resumed": emitBootstrap,
+    "session.compacted": emitBootstrap,
+    "session.cleared": emitBootstrap,
+    "experimental.chat.system.transform": (payload) => {
+      const bootstrap = buildBootstrap();
+      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;
+    },
+  };
+}
+`;
+}
+// ---------------------------------------------------------------------------
+// AGENTS.md block for hooks
+// ---------------------------------------------------------------------------
+export function hooksAgentsMdBlock() {
+    return `### Hooks (real lifecycle integration)
+
+Cclaw generates real hook integrations across harnesses:
+- **Claude/Cursor/Codex:** lifecycle rehydration + PreToolUse/PostToolUse + Stop
+- **OpenCode:** session lifecycle + system transform rehydration in plugin
+
+| Harness | Hook file | Events |
+|---------|-----------|--------|
+| Claude Code | \`.claude/hooks/hooks.json\` | SessionStart(startup/resume/clear/compact), PreToolUse, PostToolUse, Stop |
+| Cursor | \`.cursor/hooks.json\` | sessionStart/sessionResume/sessionClear/sessionCompact, preToolUse, postToolUse, stop |
+| Codex | \`.codex/hooks.json\` | SessionStart(startup/resume/clear/compact), PreToolUse, PostToolUse, Stop |
+| OpenCode | \`${RUNTIME_ROOT}/hooks/opencode-plugin.mjs\` | session.created/resumed/compacted/cleared + system transform |
+
+Hook state files:
+- \`${RUNTIME_ROOT}/state/stage-activity.jsonl\`
+- \`${RUNTIME_ROOT}/state/checkpoint.json\`
+
+Disable observation: \`touch ${RUNTIME_ROOT}/.observe-disabled\`
+`;
+}