cclaw-cli 0.1.0

package/dist/content/observe.js

@@ -0,0 +1,1110 @@
+/**
+ * Tool observation system — captures PreToolUse/PostToolUse events
+ * to .cclaw/observations.jsonl for continuous learning.
+ *
+ * observe.sh: reads hook JSON from stdin, extracts tool name + truncated I/O,
+ * appends a JSONL line to .cclaw/observations.jsonl.
+ *
+ * summarize-observations.sh: run at session stop, reads recent observations,
+ * identifies patterns, and appends new learnings to .cclaw/learnings.jsonl.
+ */
+import { RUNTIME_ROOT } from "../constants.js";
+import { RUNTIME_SHELL_DETECT_ROOT } from "./hooks.js";
+export function promptGuardScript() {
+    return `#!/usr/bin/env bash
+# cclaw prompt guard hook — generated by cclaw sync
+# Advisory-only guard for risky writes into ${RUNTIME_ROOT} runtime files.
+set -uo pipefail
+
+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
+
+${RUNTIME_SHELL_DETECT_ROOT}
+
+STATE_DIR="$ROOT/${RUNTIME_ROOT}/state"
+GUARD_LOG="$STATE_DIR/prompt-guard.jsonl"
+mkdir -p "$STATE_DIR" 2>/dev/null || true
+
+INPUT=$(cat 2>/dev/null || echo '{}')
+[ -n "$INPUT" ] || exit 0
+
+TOOL="unknown"
+PAYLOAD=""
+if command -v jq >/dev/null 2>&1; then
+  TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // .tool // "unknown"' 2>/dev/null || echo "unknown")
+  PAYLOAD=$(printf '%s' "$INPUT" | jq -r '.tool_input // .input // .arguments // .params // .payload // {} | tostring' 2>/dev/null || echo "")
+elif command -v python3 >/dev/null 2>&1; then
+  TOOL=$(INPUT_JSON="$INPUT" python3 - <<'PY'
+import json
+import os
+
+try:
+    value = json.loads(os.environ.get("INPUT_JSON", "{}"))
+except Exception:
+    value = {}
+tool = value.get("tool_name") or value.get("tool") or "unknown"
+print(tool if isinstance(tool, str) else "unknown")
+PY
+)
+  PAYLOAD=$(printf '%s' "$INPUT")
+else
+  PAYLOAD=$(printf '%s' "$INPUT")
+fi
+
+if [ -z "$PAYLOAD" ]; then
+  PAYLOAD=$(printf '%s' "$INPUT")
+fi
+
+PAYLOAD_LOWER=$(printf '%s' "$PAYLOAD" | tr '[:upper:]' '[:lower:]')
+TOOL_LOWER=$(printf '%s' "$TOOL" | tr '[:upper:]' '[:lower:]')
+TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || echo "")
+REASONS=""
+
+case "$TOOL_LOWER" in
+  write|edit|multiedit|delete|applypatch|runcommand|shell|terminal|execcommand)
+    if printf '%s' "$PAYLOAD_LOWER" | grep -Eq '\.cclaw/(state|artifacts|hooks|skills|commands|agents|runs|learnings)'; then
+      REASONS="write_to_cclaw_runtime"
+    fi
+    ;;
+esac
+
+if printf '%s' "$PAYLOAD_LOWER" | grep -Eq '(rm[[:space:]]+-rf[[:space:]]+\.cclaw|curl[[:space:]].*https?://|wget[[:space:]].*https?://|base64[[:space:]]+-d|eval\\(|python[[:space:]]+-c)'; then
+  if [ -n "$REASONS" ]; then
+    REASONS="$REASONS,suspicious_payload_pattern"
+  else
+    REASONS="suspicious_payload_pattern"
+  fi
+fi
+
+if [ -n "$REASONS" ]; then
+  NOTE="Cclaw advisory: potential risky write intent detected for ${RUNTIME_ROOT} runtime (\${REASONS}). Prefer installer commands or explicit confirmation before mutating runtime internals."
+  if command -v jq >/dev/null 2>&1; then
+    ENTRY=$(jq -n -c \
+      --arg ts "$TS" \
+      --arg harness "$HARNESS" \
+      --arg tool "$TOOL" \
+      --arg reasons "$REASONS" \
+      --arg note "$NOTE" \
+      '{ts:$ts,harness:$harness,tool:$tool,reasons:($reasons|split(",")),note:$note}' 2>/dev/null || echo "")
+  elif command -v python3 >/dev/null 2>&1; then
+    ENTRY=$(TS="$TS" HARNESS="$HARNESS" TOOL="$TOOL" REASONS="$REASONS" NOTE="$NOTE" python3 - <<'PY'
+import json, os
+
+ts = os.environ.get("TS") or ""
+harness = os.environ.get("HARNESS") or ""
+tool = os.environ.get("TOOL") or "unknown"
+reasons_raw = os.environ.get("REASONS") or ""
+note = os.environ.get("NOTE") or ""
+reasons = [r for r in reasons_raw.split(",") if r]
+print(json.dumps({"ts": ts, "harness": harness, "tool": tool, "reasons": reasons, "note": note}, ensure_ascii=False))
+PY
+)
+  else
+    ENTRY=""
+  fi
+
+  if [ -n "$ENTRY" ]; then
+    printf '%s\n' "$ENTRY" >> "$GUARD_LOG" 2>/dev/null || true
+  fi
+  printf '[cclaw] %s\n' "$NOTE" >&2
+fi
+
+exit 0
+`;
+}
+export function observeScript() {
+    return `#!/usr/bin/env bash
+# cclaw observe hook — generated by cclaw sync
+# Captures PreToolUse/PostToolUse events to ${RUNTIME_ROOT}/observations.jsonl
+# Reads hook JSON from stdin, extracts tool + truncated I/O, appends JSONL.
+# Always exits 0 to never block the agent.
+set -uo pipefail
+
+# Phase: "pre" or "post" passed as $1 by the hook runner
+PHASE="\${1:-post}"
+
+${RUNTIME_SHELL_DETECT_ROOT}
+
+OBS_FILE="$ROOT/${RUNTIME_ROOT}/observations.jsonl"
+STATE_FILE="$ROOT/${RUNTIME_ROOT}/state/flow-state.json"
+ACTIVITY_FILE="$ROOT/${RUNTIME_ROOT}/state/stage-activity.jsonl"
+LOCK_DIR="$ROOT/${RUNTIME_ROOT}/state/.observe.lock"
+MAX_LEN=2000
+
+# Guard: skip if disabled or observations dir missing
+[ -f "$ROOT/${RUNTIME_ROOT}/.observe-disabled" ] && exit 0
+[ -d "$ROOT/${RUNTIME_ROOT}" ] || exit 0
+mkdir -p "$ROOT/${RUNTIME_ROOT}/state" 2>/dev/null || true
+
+escape_json() {
+  local str="$1"
+  str=\${str//\\\\/\\\\\\\\}
+  str=\${str//\\"/\\\\\\"}
+  str=\${str//$'\\t'/\\\\t}
+  str=\${str//$'\\n'/\\\\n}
+  printf '%s' "$str"
+}
+
+acquire_lock() {
+  local attempt=0
+  while ! mkdir "$LOCK_DIR" 2>/dev/null; do
+    attempt=$((attempt + 1))
+    if [ "$attempt" -ge 200 ]; then
+      return 1
+    fi
+    sleep 0.02
+  done
+  return 0
+}
+
+release_lock() {
+  rmdir "$LOCK_DIR" 2>/dev/null || true
+}
+
+rotate_file() {
+  local file_path="$1"
+  local keep_lines="$2"
+  if [ ! -f "$file_path" ]; then
+    return
+  fi
+  local line_count
+  line_count=$(wc -l < "$file_path" 2>/dev/null | tr -d ' ')
+  if [ -z "$line_count" ]; then
+    return
+  fi
+  if [ "$line_count" -gt $((keep_lines * 2)) ]; then
+    local tmp_path="\${file_path}.tmp.$$"
+    if tail -n "$keep_lines" "$file_path" > "$tmp_path" 2>/dev/null; then
+      mv "$tmp_path" "$file_path" 2>/dev/null || rm -f "$tmp_path" 2>/dev/null || true
+    fi
+  fi
+}
+
+# Read stdin (hook JSON)
+INPUT=$(cat 2>/dev/null || echo '{}')
+[ -z "$INPUT" ] && exit 0
+
+# Extract fields from hook payload.
+TOOL="unknown"
+PAYLOAD=""
+if command -v jq >/dev/null 2>&1; then
+  TOOL=$(echo "$INPUT" | jq -r '.tool_name // .tool // "unknown"' 2>/dev/null || echo "unknown")
+  if [ "$PHASE" = "pre" ]; then
+    PAYLOAD=$(echo "$INPUT" | jq -r --arg max "$MAX_LEN" '.tool_input // .input // {} | tostring | .[0:($max|tonumber)]' 2>/dev/null || echo "")
+  else
+    PAYLOAD=$(echo "$INPUT" | jq -r --arg max "$MAX_LEN" '.tool_response // .tool_output // .output // .result_json // "" | tostring | .[0:($max|tonumber)]' 2>/dev/null || echo "")
+  fi
+else
+  TOOL=$(printf '%s' "$INPUT" | sed -n -E 's/.*"tool_name"[[:space:]]*:[[:space:]]*"([^"]+)".*/\\1/p' | head -1)
+  if [ -z "$TOOL" ]; then
+    TOOL=$(printf '%s' "$INPUT" | sed -n -E 's/.*"tool"[[:space:]]*:[[:space:]]*"([^"]+)".*/\\1/p' | head -1)
+  fi
+  [ -n "$TOOL" ] || TOOL="unknown"
+  PAYLOAD=$(printf '%s' "$INPUT" | cut -c1-"$MAX_LEN")
+fi
+
+TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || echo "")
+STAGE="none"
+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")
+    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_id = "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_id = value
+except Exception:
+    pass
+print(run_id)
+PY
+)
+  else
+    STAGE=$(grep -o '"currentStage"[[:space:]]*:[[:space:]]*"[^"]*"' "$STATE_FILE" 2>/dev/null | head -1 | sed 's/.*"\\([^"]*\\)"$/\\1/' || echo "none")
+    ACTIVE_RUN=$(grep -o '"activeRunId"[[:space:]]*:[[:space:]]*"[^"]*"' "$STATE_FILE" 2>/dev/null | head -1 | sed 's/.*"\\([^"]*\\)"$/\\1/' || echo "none")
+  fi
+fi
+
+# Skip observation of cclaw hooks to avoid recursion
+case "$TOOL" in
+  cclaw*|*cclaw-hook*|observe) exit 0 ;;
+esac
+
+if [ "$PHASE" = "pre" ]; then
+  EVENT="tool_start"
+else
+  EVENT="tool_complete"
+fi
+
+# Scrub potential secrets (env vars, tokens, keys) — BSD/macOS sed compatible
+PAYLOAD=$(echo "$PAYLOAD" | sed -E 's/[A-Za-z0-9_]*([Kk][Ee][Yy]|[Tt][Oo][Kk][Ee][Nn]|[Ss][Ee][Cc][Rr][Ee][Tt]|[Pp][Aa][Ss][Ss][Ww][Oo][Rr][Dd]|[Cc][Rr][Ee][Dd][Ee][Nn][Tt][Ii][Aa][Ll])[A-Za-z0-9_]*[=:][^ ",}]+/[REDACTED]/g' 2>/dev/null || echo "$PAYLOAD")
+
+# Build JSONL lines.
+if command -v jq >/dev/null 2>&1; then
+  EVENT_JSON=$(jq -n -c \\
+    --arg ts "$TS" \\
+    --arg event "$EVENT" \\
+    --arg tool "$TOOL" \\
+    --arg phase "$PHASE" \\
+    --arg stage "$STAGE" \\
+    --arg runId "$ACTIVE_RUN" \\
+    --arg payload "$PAYLOAD" \\
+    '{ts:$ts,event:$event,tool:$tool,phase:$phase,stage:$stage,runId:$runId,data:$payload}' 2>/dev/null || echo "")
+  ACTIVITY_JSON=$(jq -n -c \\
+    --arg ts "$TS" \\
+    --arg event "$EVENT" \\
+    --arg tool "$TOOL" \\
+    --arg phase "$PHASE" \\
+    --arg stage "$STAGE" \\
+    --arg runId "$ACTIVE_RUN" \\
+    '{ts:$ts,event:$event,tool:$tool,phase:$phase,stage:$stage,runId:$runId}' 2>/dev/null || echo "")
+else
+  EVENT_JSON=$(printf '{"ts":"%s","event":"%s","tool":"%s","phase":"%s","stage":"%s","runId":"%s","data":"%s"}' \\
+    "$(escape_json "$TS")" \\
+    "$(escape_json "$EVENT")" \\
+    "$(escape_json "$TOOL")" \\
+    "$(escape_json "$PHASE")" \\
+    "$(escape_json "$STAGE")" \\
+    "$(escape_json "$ACTIVE_RUN")" \\
+    "$(escape_json "$PAYLOAD")")
+  ACTIVITY_JSON=$(printf '{"ts":"%s","event":"%s","tool":"%s","phase":"%s","stage":"%s","runId":"%s"}' \\
+    "$(escape_json "$TS")" \\
+    "$(escape_json "$EVENT")" \\
+    "$(escape_json "$TOOL")" \\
+    "$(escape_json "$PHASE")" \\
+    "$(escape_json "$STAGE")" \\
+    "$(escape_json "$ACTIVE_RUN")")
+fi
+
+if acquire_lock; then
+  trap release_lock EXIT INT TERM
+  [ -n "$EVENT_JSON" ] && printf '%s\\n' "$EVENT_JSON" >> "$OBS_FILE" 2>/dev/null
+  [ -n "$ACTIVITY_JSON" ] && printf '%s\\n' "$ACTIVITY_JSON" >> "$ACTIVITY_FILE" 2>/dev/null
+  rotate_file "$OBS_FILE" 4000
+  rotate_file "$ACTIVITY_FILE" 3000
+  release_lock
+  trap - EXIT INT TERM
+fi
+
+exit 0
+`;
+}
+export function contextMonitorScript() {
+    return `#!/usr/bin/env bash
+# cclaw context monitor hook — generated by cclaw sync
+# Advisory-only context pressure warnings (best effort).
+set -uo pipefail
+
+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
+
+${RUNTIME_SHELL_DETECT_ROOT}
+
+STATE_DIR="$ROOT/${RUNTIME_ROOT}/state"
+MONITOR_STATE="$STATE_DIR/context-monitor.json"
+WARNINGS_FILE="$STATE_DIR/context-warnings.jsonl"
+mkdir -p "$STATE_DIR" 2>/dev/null || true
+
+INPUT=$(cat 2>/dev/null || echo '{}')
+[ -n "$INPUT" ] || exit 0
+
+REMAINING_PERCENT=""
+if command -v python3 >/dev/null 2>&1; then
+  REMAINING_PERCENT=$(INPUT_JSON="$INPUT" python3 - <<'PY'
+import json
+import os
+from typing import Any
+
+raw = os.environ.get("INPUT_JSON", "{}")
+try:
+    payload = json.loads(raw)
+except Exception:
+    print("")
+    raise SystemExit(0)
+
+def pick(path: list[str]) -> Any:
+    node: Any = payload
+    for key in path:
+        if not isinstance(node, dict):
+            return None
+        node = node.get(key)
+    return node
+
+def as_percent(value: Any, invert: bool = False):
+    if not isinstance(value, (int, float)):
+        return None
+    number = float(value)
+    if number <= 1.0:
+        number *= 100.0
+    if invert:
+        number = 100.0 - number
+    if number < 0:
+        number = 0.0
+    if number > 100:
+        number = 100.0
+    return number
+
+candidates = [
+    (["context", "remaining_percent"], False),
+    (["context", "remainingPercent"], False),
+    (["context_usage", "remaining_percent"], False),
+    (["context_usage", "remainingPercent"], False),
+    (["contextUsage", "remainingPercent"], False),
+    (["context_window", "remaining_percent"], False),
+    (["remaining_context_percent"], False),
+    (["remainingContextPercent"], False),
+    (["remaining_context_ratio"], False),
+    (["remainingContextRatio"], False),
+    (["context", "used_percent"], True),
+    (["context", "usedPercent"], True),
+    (["context_usage", "used_percent"], True),
+    (["context_usage", "usedPercent"], True),
+    (["contextUsage", "usedPercent"], True),
+    (["context_window", "used_ratio"], True),
+    (["context_window", "usedRatio"], True),
+]
+
+for path, invert in candidates:
+    value = pick(path)
+    percent = as_percent(value, invert=invert)
+    if percent is not None:
+        print(f"{percent:.2f}")
+        raise SystemExit(0)
+
+print("")
+PY
+)
+fi
+
+[ -n "$REMAINING_PERCENT" ] || exit 0
+
+BAND="none"
+if awk "BEGIN { exit !($REMAINING_PERCENT <= 20) }"; then
+  BAND="critical"
+elif awk "BEGIN { exit !($REMAINING_PERCENT <= 35) }"; then
+  BAND="warning"
+fi
+
+[ "$BAND" != "none" ] || exit 0
+
+LAST_BAND="none"
+if [ -f "$MONITOR_STATE" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    LAST_BAND=$(jq -r '.lastBand // "none"' "$MONITOR_STATE" 2>/dev/null || echo "none")
+  elif command -v python3 >/dev/null 2>&1; then
+    LAST_BAND=$(python3 - "$MONITOR_STATE" <<'PY'
+import json
+import sys
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as handle:
+        value = json.load(handle)
+    band = value.get("lastBand")
+    if isinstance(band, str):
+        print(band)
+    else:
+        print("none")
+except Exception:
+    print("none")
+PY
+)
+  fi
+fi
+
+TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || echo "")
+if [ "$BAND" != "$LAST_BAND" ]; then
+  NOTE="Cclaw advisory: context remaining is \${REMAINING_PERCENT}% (\${BAND}). Consider checkpointing or compacting soon."
+  if command -v jq >/dev/null 2>&1; then
+    ENTRY=$(jq -n -c \
+      --arg ts "$TS" \
+      --arg harness "$HARNESS" \
+      --arg band "$BAND" \
+      --arg remaining "$REMAINING_PERCENT" \
+      --arg note "$NOTE" \
+      '{ts:$ts,harness:$harness,band:$band,remainingPercent:($remaining|tonumber),note:$note}' 2>/dev/null || echo "")
+  else
+    ENTRY=$(printf '{"ts":"%s","harness":"%s","band":"%s","remainingPercent":"%s","note":"%s"}' "$TS" "$HARNESS" "$BAND" "$REMAINING_PERCENT" "$NOTE")
+  fi
+
+  if [ -n "$ENTRY" ]; then
+    printf '%s\n' "$ENTRY" >> "$WARNINGS_FILE" 2>/dev/null || true
+  fi
+  printf '[cclaw] %s\n' "$NOTE" >&2
+fi
+
+TMP_STATE="$MONITOR_STATE.tmp.$$"
+if command -v jq >/dev/null 2>&1; then
+  jq -n \
+    --arg ts "$TS" \
+    --arg band "$BAND" \
+    --arg remaining "$REMAINING_PERCENT" \
+    --arg harness "$HARNESS" \
+    '{lastUpdated:$ts,lastBand:$band,lastRemainingPercent:($remaining|tonumber),harness:$harness}' > "$TMP_STATE" 2>/dev/null || true
+else
+  printf '{\n  "lastUpdated": "%s",\n  "lastBand": "%s",\n  "lastRemainingPercent": %s,\n  "harness": "%s"\n}\n' \
+    "$TS" "$BAND" "$REMAINING_PERCENT" "$HARNESS" > "$TMP_STATE" 2>/dev/null || true
+fi
+if [ -s "$TMP_STATE" ]; then
+  mv "$TMP_STATE" "$MONITOR_STATE" 2>/dev/null || rm -f "$TMP_STATE" 2>/dev/null || true
+fi
+
+exit 0
+`;
+}
+export function summarizeObservationsRuntimeModule() {
+    return `#!/usr/bin/env node
+import fs from "node:fs";
+
+const [, , observationsPath, learningsPath, timestampArg] = process.argv;
+
+function readTailText(filePath, maxBytes = 524288) {
+  let fd;
+  try {
+    fd = fs.openSync(filePath, "r");
+    const size = fs.fstatSync(fd).size;
+    if (!Number.isFinite(size) || size <= 0) return "";
+    const bytesToRead = Math.min(size, maxBytes);
+    const buffer = Buffer.allocUnsafe(bytesToRead);
+    fs.readSync(fd, buffer, 0, bytesToRead, size - bytesToRead);
+    return buffer.toString("utf8");
+  } catch {
+    return "";
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // ignore
+      }
+    }
+  }
+}
+
+function readTailLines(filePath, maxLines, maxBytes = 524288) {
+  const raw = readTailText(filePath, maxBytes).trim();
+  if (!raw) return [];
+  return raw.split(/\\r?\\n/).slice(-maxLines);
+}
+
+function writeAppend(filePath, lines) {
+  if (!lines.length) return;
+  try {
+    fs.appendFileSync(filePath, lines.join("\\n") + "\\n", "utf8");
+  } catch {
+    // advisory-only runtime path
+  }
+}
+
+function parseLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function toText(value) {
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return "";
+  }
+}
+
+const keyPattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const errorPattern = /(error|fail|timeout|exception)/i;
+const timestamp = timestampArg || new Date().toISOString();
+const observationLines = readTailLines(observationsPath, 4000, 1024 * 1024);
+const learningLines = readTailLines(learningsPath, 6000, 1024 * 1024);
+
+const observations = observationLines
+  .map(parseLine)
+  .filter(Boolean);
+
+if (observations.length < 5) {
+  process.exit(0);
+}
+
+const toolUsage = new Map();
+const toolErrors = new Map();
+const stageErrors = new Map();
+const longPayload = new Map();
+
+for (const obs of observations) {
+  const toolRaw = typeof obs.tool === "string" ? obs.tool : "unknown";
+  const stageRaw = typeof obs.stage === "string" ? obs.stage : "none";
+  const tool = toolRaw.trim().replace(/[^A-Za-z0-9._-]+/g, "-") || "unknown";
+  const stage = stageRaw.trim().replace(/[^A-Za-z0-9._-]+/g, "-") || "none";
+  const payload = toText(obs.data);
+  toolUsage.set(tool, (toolUsage.get(tool) || 0) + 1);
+  if (payload.length >= 1500) {
+    longPayload.set(tool, (longPayload.get(tool) || 0) + 1);
+  }
+  if (obs.event === "tool_complete" && errorPattern.test(payload)) {
+    toolErrors.set(tool, (toolErrors.get(tool) || 0) + 1);
+    stageErrors.set(stage, (stageErrors.get(stage) || 0) + 1);
+  }
+}
+
+const candidates = [];
+
+for (const [tool, errors] of toolErrors.entries()) {
+  if (errors < 3) continue;
+  candidates.push({
+    ts: timestamp,
+    skill: "observation",
+    type: "pitfall",
+    key: "frequent-errors-" + tool,
+    insight: "Tool " + tool + " produced " + errors + " error-like completions in a single session; add a preflight checklist before using it.",
+    confidence: Math.min(9, 4 + Math.floor(errors / 2)),
+    source: "observed"
+  });
+}
+
+for (const [tool, total] of toolUsage.entries()) {
+  if (total < 8) continue;
+  const errors = toolErrors.get(tool) || 0;
+  if (errors > Math.max(1, Math.floor(total * 0.15))) continue;
+  candidates.push({
+    ts: timestamp,
+    skill: "observation",
+    type: "pattern",
+    key: "reliable-tool-" + tool,
+    insight: "Tool " + tool + " was used " + total + " times with low failure rate; prefer it as a first option for similar tasks.",
+    confidence: Math.min(8, 3 + Math.floor(total / 3)),
+    source: "observed"
+  });
+}
+
+for (const [stage, errors] of stageErrors.entries()) {
+  if (stage === "none" || errors < 4) continue;
+  candidates.push({
+    ts: timestamp,
+    skill: "observation",
+    type: "pitfall",
+    key: "stage-hotspot-" + stage,
+    insight: "Stage " + stage + " produced " + errors + " error-like tool completions in one session; add stage-specific checks before execution.",
+    confidence: Math.min(8, 3 + Math.floor(errors / 2)),
+    source: "observed"
+  });
+}
+
+for (const [tool, count] of longPayload.entries()) {
+  if (count < 3) continue;
+  candidates.push({
+    ts: timestamp,
+    skill: "observation",
+    type: "preference",
+    key: "truncate-heavy-payloads-" + tool,
+    insight: "Tool " + tool + " produced large payloads repeatedly; summarize outputs earlier to avoid context pressure.",
+    confidence: Math.min(7, 3 + Math.floor(count / 2)),
+    source: "observed"
+  });
+}
+
+const valid = [];
+const bestCandidate = new Map();
+for (const candidate of candidates) {
+  if (typeof candidate.key !== "string" || !keyPattern.test(candidate.key)) continue;
+  if (typeof candidate.insight !== "string" || candidate.insight.trim().length < 16) continue;
+  if (!Number.isInteger(candidate.confidence) || candidate.confidence < 1 || candidate.confidence > 10) continue;
+  const token = candidate.key + ":" + candidate.type;
+  const current = bestCandidate.get(token);
+  if (!current || candidate.confidence > current.confidence) {
+    bestCandidate.set(token, candidate);
+  }
+}
+for (const value of bestCandidate.values()) {
+  valid.push(value);
+}
+
+const bestExisting = new Map();
+for (const line of learningLines) {
+  const parsed = parseLine(line);
+  if (!parsed) continue;
+  if (typeof parsed.key !== "string" || typeof parsed.type !== "string") continue;
+  if (typeof parsed.confidence !== "number" || !Number.isInteger(parsed.confidence)) continue;
+  const token = parsed.key + ":" + parsed.type;
+  const current = bestExisting.get(token) || 0;
+  if (parsed.confidence > current) {
+    bestExisting.set(token, parsed.confidence);
+  }
+}
+
+const appended = [];
+for (const candidate of valid) {
+  const token = candidate.key + ":" + candidate.type;
+  const current = bestExisting.get(token) || 0;
+  if (candidate.confidence > current) {
+    appended.push(JSON.stringify(candidate));
+    bestExisting.set(token, candidate.confidence);
+  }
+}
+
+writeAppend(learningsPath, appended);
+process.exit(0);
+`;
+}
+export function summarizeObservationsScript() {
+    return `#!/usr/bin/env bash
+# cclaw stop-summarize hook — generated by cclaw sync
+# Analyzes recent observations and creates learnings entries.
+# Runs as part of the stop hook chain.
+set -uo pipefail
+
+${RUNTIME_SHELL_DETECT_ROOT}
+
+OBS_FILE="$ROOT/${RUNTIME_ROOT}/observations.jsonl"
+LEARNINGS_FILE="$ROOT/${RUNTIME_ROOT}/learnings.jsonl"
+ACTIVITY_FILE="$ROOT/${RUNTIME_ROOT}/state/stage-activity.jsonl"
+LOCK_DIR="$ROOT/${RUNTIME_ROOT}/state/.observe.lock"
+mkdir -p "$ROOT/${RUNTIME_ROOT}/state" 2>/dev/null || true
+[ -f "$LEARNINGS_FILE" ] || : > "$LEARNINGS_FILE" 2>/dev/null || true
+
+# Guard
+[ -f "$OBS_FILE" ] || exit 0
+[ -s "$OBS_FILE" ] || exit 0
+
+acquire_lock() {
+  local attempt=0
+  while ! mkdir "$LOCK_DIR" 2>/dev/null; do
+    attempt=$((attempt + 1))
+    if [ "$attempt" -ge 200 ]; then
+      return 1
+    fi
+    sleep 0.02
+  done
+  return 0
+}
+
+release_lock() {
+  rmdir "$LOCK_DIR" 2>/dev/null || true
+}
+
+rotate_file() {
+  local file_path="$1"
+  local keep_lines="$2"
+  if [ ! -f "$file_path" ]; then
+    return
+  fi
+  local line_count
+  line_count=$(wc -l < "$file_path" 2>/dev/null | tr -d ' ')
+  if [ -z "$line_count" ]; then
+    return
+  fi
+  if [ "$line_count" -gt $((keep_lines * 2)) ]; then
+    local tmp_path="\${file_path}.tmp.$$"
+    if tail -n "$keep_lines" "$file_path" > "$tmp_path" 2>/dev/null; then
+      mv "$tmp_path" "$file_path" 2>/dev/null || rm -f "$tmp_path" 2>/dev/null || true
+    fi
+  fi
+}
+
+acquire_lock || exit 0
+trap release_lock EXIT INT TERM
+
+# Count observations in this session
+OBS_COUNT=$(wc -l < "$OBS_FILE" 2>/dev/null | tr -d ' ')
+[ "$OBS_COUNT" -lt 5 ] && exit 0
+
+TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || echo "")
+RUNTIME_SUMMARIZER="$ROOT/${RUNTIME_ROOT}/hooks/summarize-observations.mjs"
+if command -v node >/dev/null 2>&1 && [ -f "$RUNTIME_SUMMARIZER" ]; then
+  node "$RUNTIME_SUMMARIZER" "$OBS_FILE" "$LEARNINGS_FILE" "$TS" >/dev/null 2>&1 || true
+elif command -v python3 >/dev/null 2>&1; then
+  python3 - "$OBS_FILE" "$LEARNINGS_FILE" "$TS" <<'PY' >/dev/null 2>&1
+import json
+import re
+import sys
+from collections import Counter
+from pathlib import Path
+
+obs_path = Path(sys.argv[1])
+learnings_path = Path(sys.argv[2])
+timestamp = sys.argv[3]
+
+error_pattern = re.compile(r"(error|fail)", re.IGNORECASE)
+key_pattern = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+
+observations = []
+for line in obs_path.read_text(encoding="utf-8").splitlines():
+    line = line.strip()
+    if not line:
+        continue
+    try:
+        value = json.loads(line)
+    except Exception:
+        continue
+    if isinstance(value, dict):
+        observations.append(value)
+
+if len(observations) < 5:
+    raise SystemExit(0)
+
+tool_counts: Counter[str] = Counter()
+error_counts: Counter[str] = Counter()
+stage_error_counts: Counter[str] = Counter()
+
+for event in observations:
+    tool = event.get("tool")
+    if not isinstance(tool, str) or not tool:
+        tool = "unknown"
+    stage = event.get("stage")
+    if not isinstance(stage, str) or not stage:
+        stage = "none"
+
+    tool_counts[tool] += 1
+
+    payload = event.get("data")
+    if isinstance(payload, str):
+        payload_text = payload
+    else:
+        try:
+            payload_text = json.dumps(payload, ensure_ascii=False)
+        except Exception:
+            payload_text = ""
+
+    if event.get("event") == "tool_complete" and error_pattern.search(payload_text):
+        error_counts[tool] += 1
+        stage_error_counts[stage] += 1
+
+candidates: list[dict[str, object]] = []
+if error_counts:
+    top_tool, top_count = error_counts.most_common(1)[0]
+    if top_count >= 3:
+        candidates.append({
+            "ts": timestamp,
+            "skill": "observation",
+            "type": "pitfall",
+            "key": f"frequent-errors-{top_tool}",
+            "insight": f"Tool {top_tool} had {top_count} error-like outputs in one session; add a preflight checklist before using it.",
+            "confidence": min(9, 4 + (top_count // 2)),
+            "source": "observed"
+        })
+
+if tool_counts:
+    top_tool, top_total = tool_counts.most_common(1)[0]
+    if top_total >= 8 and error_counts.get(top_tool, 0) <= 1:
+        candidates.append({
+            "ts": timestamp,
+            "skill": "observation",
+            "type": "pattern",
+            "key": f"reliable-tool-{top_tool}",
+            "insight": f"Tool {top_tool} was used {top_total} times with low failure rate; prefer it as first option for similar tasks.",
+            "confidence": min(8, 3 + (top_total // 3)),
+            "source": "observed"
+        })
+
+if stage_error_counts:
+    top_stage, top_stage_count = stage_error_counts.most_common(1)[0]
+    if top_stage != "none" and top_stage_count >= 4:
+        candidates.append({
+            "ts": timestamp,
+            "skill": "observation",
+            "type": "pitfall",
+            "key": f"stage-hotspot-{top_stage}",
+            "insight": f"Stage {top_stage} produced {top_stage_count} error-like tool completions in one session; stage-specific guardrails are needed.",
+            "confidence": min(8, 3 + (top_stage_count // 2)),
+            "source": "observed"
+        })
+
+def is_valid(entry: dict[str, object]) -> bool:
+    ts = entry.get("ts")
+    key = entry.get("key")
+    insight = entry.get("insight")
+    conf = entry.get("confidence")
+    typ = entry.get("type")
+    source = entry.get("source")
+
+    if not isinstance(ts, str) or not ts:
+        return False
+    if not isinstance(key, str) or not key_pattern.match(key):
+        return False
+    if not isinstance(insight, str) or len(insight.strip()) < 16:
+        return False
+    if not isinstance(conf, int) or conf < 1 or conf > 10:
+        return False
+    if typ not in {"pitfall", "pattern", "preference"}:
+        return False
+    if source not in {"observed", "user-stated"}:
+        return False
+    return True
+
+best_existing: dict[str, int] = {}
+if learnings_path.exists():
+    for line in learnings_path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            entry = json.loads(line)
+        except Exception:
+            continue
+        if not isinstance(entry, dict):
+            continue
+        key = entry.get("key")
+        typ = entry.get("type")
+        conf = entry.get("confidence")
+        if isinstance(key, str) and isinstance(typ, str) and isinstance(conf, int):
+            token = f"{key}:{typ}"
+            best_existing[token] = max(best_existing.get(token, 0), conf)
+
+appended: list[str] = []
+with learnings_path.open("a", encoding="utf-8") as handle:
+    for candidate in candidates:
+        if not is_valid(candidate):
+            continue
+        token = f"{candidate['key']}:{candidate['type']}"
+        confidence = int(candidate["confidence"])
+        if confidence <= best_existing.get(token, 0):
+            continue
+        handle.write(json.dumps(candidate, ensure_ascii=False) + "\\n")
+        best_existing[token] = confidence
+        appended.append(str(candidate["key"]))
+
+raise SystemExit(0)
+PY
+elif command -v jq >/dev/null 2>&1; then
+  ERROR_PATTERNS=$(jq -r 'select(.event=="tool_complete") | select(.data | test("error|Error|ERROR|fail|Fail|FAIL"; "g")) | .tool' "$OBS_FILE" 2>/dev/null | sort | uniq -c | sort -rn | head -3)
+  if [ -n "$ERROR_PATTERNS" ]; then
+    TOP_ERROR_TOOL=$(echo "$ERROR_PATTERNS" | head -1 | awk '{print $2}')
+    TOP_ERROR_COUNT=$(echo "$ERROR_PATTERNS" | head -1 | awk '{print $1}')
+    if [ "$TOP_ERROR_COUNT" -ge 3 ]; then
+      CANDIDATE=$(jq -n -c \\
+        --arg ts "$TS" \\
+        --arg tool "$TOP_ERROR_TOOL" \\
+        --arg count "$TOP_ERROR_COUNT" \\
+        '{ts:$ts,skill:"observation",type:"pitfall",key:("frequent-errors-"+$tool),insight:("Tool "+$tool+" had "+$count+" error-like outputs in one session; add a preflight checklist before using it."),confidence:(5 + (($count|tonumber) / 2 | floor)),source:"observed"}' 2>/dev/null || echo "")
+      if [ -n "$CANDIDATE" ]; then
+        CANDIDATE=$(echo "$CANDIDATE" | jq -c 'if .confidence > 10 then .confidence = 10 else . end' 2>/dev/null || echo "")
+      fi
+
+      if [ -n "$CANDIDATE" ]; then
+        CANDIDATE_OK=$(echo "$CANDIDATE" | jq -r '
+          (.ts|type=="string") and
+          (.key|type=="string") and
+          (.type|type=="string") and
+          (.insight|type=="string" and (length >= 16)) and
+          (.confidence|type=="number" and . >= 1 and . <= 10) and
+          (.source|type=="string")
+        ' 2>/dev/null || echo "false")
+        if [ "$CANDIDATE_OK" = "true" ]; then
+          CANDIDATE_KEY=$(echo "$CANDIDATE" | jq -r '.key' 2>/dev/null || echo "")
+          CANDIDATE_TYPE=$(echo "$CANDIDATE" | jq -r '.type' 2>/dev/null || echo "")
+          CANDIDATE_CONF=$(echo "$CANDIDATE" | jq -r '.confidence' 2>/dev/null || echo "0")
+          EXISTING_CONF=$(jq -r --arg key "$CANDIDATE_KEY" --arg type "$CANDIDATE_TYPE" '
+            select(.key == $key and .type == $type) | (.confidence // 0)
+          ' "$LEARNINGS_FILE" 2>/dev/null | sort -nr | head -1)
+          [ -n "$EXISTING_CONF" ] || EXISTING_CONF=0
+          if [ "$CANDIDATE_CONF" -gt "$EXISTING_CONF" ]; then
+            printf '%s\\n' "$CANDIDATE" >> "$LEARNINGS_FILE" 2>/dev/null || true
+          fi
+        fi
+      fi
+    fi
+  fi
+fi
+
+# Archive observations (rotate to prevent unbounded growth)
+ARCHIVE_DIR="$ROOT/${RUNTIME_ROOT}/observations.archive"
+mkdir -p "$ARCHIVE_DIR" 2>/dev/null
+ARCHIVE_FILE="$ARCHIVE_DIR/$(date -u +"%Y%m%d-%H%M%S").jsonl"
+cp "$OBS_FILE" "$ARCHIVE_FILE" 2>/dev/null || true
+: > "$OBS_FILE" 2>/dev/null || true
+
+# Retain only the most recent 30 archives.
+ARCHIVE_LIST=$(ls -1t "$ARCHIVE_DIR"/*.jsonl 2>/dev/null || true)
+COUNT=0
+for file in $ARCHIVE_LIST; do
+  COUNT=$((COUNT + 1))
+  if [ "$COUNT" -gt 30 ]; then
+    rm -f "$file" 2>/dev/null || true
+  fi
+done
+
+# Keep stage activity bounded by line count.
+rotate_file "$ACTIVITY_FILE" 2000
+
+release_lock
+trap - EXIT INT TERM
+
+exit 0
+`;
+}
+/**
+ * Updated hooks.json generators with PreToolUse/PostToolUse observation.
+ */
+export function claudeHooksJsonWithObservation() {
+    return JSON.stringify({
+        hooks: {
+            SessionStart: [{
+                    matcher: "startup|resume|clear|compact",
+                    hooks: [{
+                            type: "command",
+                            command: `bash ${RUNTIME_ROOT}/hooks/session-start.sh`
+                        }]
+                }],
+            PreToolUse: [{
+                    matcher: "*",
+                    hooks: [{
+                            type: "command",
+                            command: `bash ${RUNTIME_ROOT}/hooks/prompt-guard.sh`
+                        }, {
+                            type: "command",
+                            command: `bash ${RUNTIME_ROOT}/hooks/observe.sh pre`
+                        }]
+                }],
+            PostToolUse: [{
+                    matcher: "*",
+                    hooks: [{
+                            type: "command",
+                            command: `bash ${RUNTIME_ROOT}/hooks/context-monitor.sh`
+                        }, {
+                            type: "command",
+                            command: `bash ${RUNTIME_ROOT}/hooks/observe.sh post`
+                        }]
+                }],
+            Stop: [{
+                    hooks: [
+                        {
+                            type: "command",
+                            command: `bash ${RUNTIME_ROOT}/hooks/summarize-observations.sh`,
+                            timeout: 15
+                        },
+                        {
+                            type: "command",
+                            command: `bash ${RUNTIME_ROOT}/hooks/stop-checkpoint.sh`,
+                            timeout: 10
+                        }
+                    ]
+                }]
+        }
+    }, null, 2);
+}
+export function cursorHooksJsonWithObservation() {
+    return JSON.stringify({
+        version: 1,
+        hooks: {
+            sessionStart: [{
+                    command: `${RUNTIME_ROOT}/hooks/session-start.sh`
+                }],
+            sessionResume: [{
+                    command: `${RUNTIME_ROOT}/hooks/session-start.sh`
+                }],
+            sessionClear: [{
+                    command: `${RUNTIME_ROOT}/hooks/session-start.sh`
+                }],
+            sessionCompact: [{
+                    command: `${RUNTIME_ROOT}/hooks/session-start.sh`
+                }],
+            preToolUse: [{
+                    matcher: "*",
+                    command: `${RUNTIME_ROOT}/hooks/prompt-guard.sh`
+                }, {
+                    matcher: "*",
+                    command: `${RUNTIME_ROOT}/hooks/observe.sh pre`
+                }],
+            postToolUse: [{
+                    matcher: "*",
+                    command: `${RUNTIME_ROOT}/hooks/context-monitor.sh`
+                }, {
+                    matcher: "*",
+                    command: `${RUNTIME_ROOT}/hooks/observe.sh post`
+                }],
+            stop: [
+                { command: `${RUNTIME_ROOT}/hooks/summarize-observations.sh`, timeout: 15 },
+                { command: `${RUNTIME_ROOT}/hooks/stop-checkpoint.sh`, timeout: 10 }
+            ]
+        }
+    }, null, 2);
+}
+export function codexHooksJsonWithObservation() {
+    return JSON.stringify({
+        hooks: {
+            SessionStart: [{
+                    matcher: "startup|resume|clear|compact",
+                    hooks: [{
+                            type: "command",
+                            command: `bash ${RUNTIME_ROOT}/hooks/session-start.sh`,
+                            statusMessage: "Loading cclaw flow state"
+                        }]
+                }],
+            PreToolUse: [{
+                    matcher: "*",
+                    hooks: [{
+                            type: "command",
+                            command: `bash ${RUNTIME_ROOT}/hooks/prompt-guard.sh`
+                        }, {
+                            type: "command",
+                            command: `bash ${RUNTIME_ROOT}/hooks/observe.sh pre`
+                        }]
+                }],
+            PostToolUse: [{
+                    matcher: "*",
+                    hooks: [{
+                            type: "command",
+                            command: `bash ${RUNTIME_ROOT}/hooks/context-monitor.sh`
+                        }, {
+                            type: "command",
+                            command: `bash ${RUNTIME_ROOT}/hooks/observe.sh post`
+                        }]
+                }],
+            Stop: [{
+                    hooks: [
+                        {
+                            type: "command",
+                            command: `bash ${RUNTIME_ROOT}/hooks/summarize-observations.sh`,
+                            timeout: 15
+                        },
+                        {
+                            type: "command",
+                            command: `bash ${RUNTIME_ROOT}/hooks/stop-checkpoint.sh`,
+                            timeout: 10
+                        }
+                    ]
+                }]
+        }
+    }, null, 2);
+}