feat(claude-ops): per-session hook logging pipeline, default off

.claude/hooks/hook-telemetry-sink.sh

@@ -1,12 +1,27 @@
 #!/usr/bin/env bash
 # Reference telemetry sink for claude-ops. Maps a hook-telemetry envelope (from
-# ANY producer, per docs/conventions/hook-telemetry) into one JSONL line in
-# .claude/observability/hook-events.jsonl — the shape the claude-observability
-# skill reads ({ts, event, hook, tool, duration_ms, exit_code, subject, status}).
+# ANY producer, per docs/conventions/hook-telemetry) into one JSONL line under
+# the log root (.observability/claude by default, project-relative; the
+# session_event_log_dir option moves it).
+#
+# Two routes, decided by the envelope's `data.session_id`:
+#   * present and well-formed: one spine-shaped line appended to
+#     sessions/<session_id>.jsonl, beside the per-session event log
+#     (session-event-log.sh); `source: "envelope"` tells the reader which
+#     producer wrote it. No lock: one file per session removes the shared
+#     write.
+#   * absent: the legacy shape ({ts, event, hook, tool, duration_ms, exit_code,
+#     subject, status}) appended to hook-events.jsonl under the same root, the
+#     shared file the observability skill has always read, under its lock.
 #
 # Field mapping: ts<-timestamp, event<-hook_event, hook<-hook, tool<-data.tool,
-# subject<-data.subject; status translates (ok->success) and exit_code derives
-# from status (error/blocked->2, else 0), since the skill keys errors on it.
+# subject<-data.subject, changed<-data.changed (when a producer sends one);
+# status translates (ok->success) and exit_code derives from status
+# (error/blocked->2, else 0), since the skill keys errors on it.
+#
+# The root carries a self-ignoring .gitignore inside a checkout, healed on the
+# first write when absent (session-log-lib.sh); a guard an operator changed is
+# respected and the write refused.
 #
 # Wire it by pointing HOOK_TELEMETRY_SINK at this script (relative path committed
 # in settings.json is the portable, team-shared form):
@@ -27,6 +42,8 @@ set -uo pipefail
 # the sibling pr-linkage-mcp-gate.sh reaching shared sources by relative path).
 # shellcheck source=../../lib/hook-utils.sh
 source "$(dirname "${BASH_SOURCE[0]}")/../../lib/hook-utils.sh"
+# shellcheck source=../../plugins/claude-ops/hooks/session-log-lib.sh
+source "$(dirname "${BASH_SOURCE[0]}")/../../plugins/claude-ops/hooks/session-log-lib.sh"
 
 INPUT=$(cat)
 [[ -n "$INPUT" ]] || exit 0
@@ -42,9 +59,11 @@ command -v jq >/dev/null 2>&1 || exit 0
 mapfile -t FIELDS < <(printf '%s' "$INPUT" | jq -r '
   if (.hook and .hook_event and (.duration_ms != null) and .status)
   then (.timestamp // ""), .hook_event, .hook, (.data.tool // ""),
-       (.duration_ms | tostring), (.data.subject // ""), .status
+       (.duration_ms | tostring), (.data.subject // ""), .status,
+       (.data.session_id // "" | tostring),
+       (.data.changed | if . == true then "true" elif . == false then "false" else "" end)
   else empty end' 2>/dev/null | tr -d '\r')
-[[ "${#FIELDS[@]}" -eq 7 ]] || exit 0
+[[ "${#FIELDS[@]}" -eq 9 ]] || exit 0
 
 TS="${FIELDS[0]}"
 EVENT="${FIELDS[1]}"
@@ -53,6 +72,8 @@ TOOL="${FIELDS[3]}"
 DURATION_MS="${FIELDS[4]}"
 SUBJECT="${FIELDS[5]}"
 STATUS="${FIELDS[6]}"
+SESSION_ID="${FIELDS[7]}"
+CHANGED="${FIELDS[8]}"
 
 # Translate the envelope status to the record shape the skill reads. Known
 # values pass through (ok → success); an unrecognized value is treated as a
@@ -85,8 +106,34 @@ blocked)
 esac
 
 project_dir=$(hook::repo_root "${CLAUDE_PROJECT_DIR:-.}")
-log_dir="${project_dir%/}/.claude/observability"
-mkdir -p "$log_dir" 2>/dev/null || exit 0
+root=""
+slog_root_to root "$project_dir"
+[[ -n "$root" ]] || exit 0
+slog_guard_ok "$root" "$project_dir" || exit 0
+
+if [[ -n "$SESSION_ID" ]] && slog_valid_id "$SESSION_ID"; then
+  [[ -d "$root/sessions" ]] || mkdir -p "$root/sessions" 2>/dev/null || exit 0
+  LINE=$(MSYS_NO_PATHCONV=1 jq -nc \
+    --arg ts "$TS" \
+    --arg session_id "$SESSION_ID" \
+    --arg event "$EVENT" \
+    --arg hook "$HOOK" \
+    --arg tool "$TOOL" \
+    --argjson duration_ms "${DURATION_MS:-0}" \
+    --argjson exit_code "${EXIT_CODE:-0}" \
+    --arg subject "$SUBJECT" \
+    --arg status "$STATUS_OUT" \
+    --arg changed "$CHANGED" \
+    '{ts: $ts, session_id: $session_id, hook_event_name: $event, status: $status,
+      duration_ms: $duration_ms, source: "envelope", hook: $hook,
+      exit_code: $exit_code, subject: $subject, tool: $tool}
+     + (if $changed == "" then {} else {changed: ($changed == "true")} end)' 2>/dev/null) || exit 0
+  [[ -n "$LINE" ]] || exit 0
+  printf '%s\n' "$LINE" >>"$root/sessions/$SESSION_ID.jsonl" 2>/dev/null
+  exit 0
+fi
+
+mkdir -p "$root" 2>/dev/null || exit 0
 
 LINE=$(MSYS_NO_PATHCONV=1 jq -nc \
   --arg ts "$TS" \
@@ -102,6 +149,6 @@ LINE=$(MSYS_NO_PATHCONV=1 jq -nc \
     subject: $subject, status: $status}' 2>/dev/null) || exit 0
 [[ -n "$LINE" ]] || exit 0
 
-hook::append_jsonl "${log_dir}/hook-events.jsonl" "$LINE"
+hook::append_jsonl "${root}/hook-events.jsonl" "$LINE"
 
 exit 0

.claude/hooks/hook-telemetry-sink.test.sh

@@ -16,8 +16,14 @@ repo_root="$(cd "$here/../.." && pwd)"
 local_copy="$here/hook-telemetry-sink.sh"
 upstream="$repo_root/plugins/claude-ops/hooks/hook-telemetry-sink.sh"
 
-[[ -f "$local_copy" ]] || { echo "FAIL: missing $local_copy"; exit 1; }
-[[ -f "$upstream" ]] || { echo "FAIL: missing $upstream"; exit 1; }
+[[ -f "$local_copy" ]] || {
+  echo "FAIL: missing $local_copy"
+  exit 1
+}
+[[ -f "$upstream" ]] || {
+  echo "FAIL: missing $upstream"
+  exit 1
+}
 
 # Strip the resolution block from both: the shellcheck source directive, the
 # source line itself, and the repo-copy-only comment lines that explain it.
@@ -50,9 +56,9 @@ fi
 
 smoke_dir="$(mktemp -d)"
 trap 'rm -f "$norm_upstream" "$norm_local"; rm -rf "$smoke_dir"' EXIT
-printf '%s' '{"schema":"hook-telemetry/v1","hook":"drift-test-smoke","hook_event":"PreToolUse","duration_ms":1,"status":"ok","data":{"tool":"Bash","subject":"smoke"}}' \
-  | CLAUDE_PROJECT_DIR="$smoke_dir" bash "$local_copy"
-if [[ -s "$smoke_dir/.claude/observability/hook-events.jsonl" ]]; then
+printf '%s' '{"schema":"hook-telemetry/v1","hook":"drift-test-smoke","hook_event":"PreToolUse","duration_ms":1,"status":"ok","data":{"tool":"Bash","subject":"smoke"}}' |
+  CLAUDE_PROJECT_DIR="$smoke_dir" bash "$local_copy"
+if [[ -s "$smoke_dir/.observability/claude/hook-events.jsonl" ]]; then
   echo "PASS: sink executes and appends a record (source target resolves)"
 else
   echo "FAIL: sink ran but appended no record — source target or mapping broken"

.gitignore

@@ -13,6 +13,7 @@ Thumbs.db
 # Local-only Claude Code state
 .claude/settings.local.json
 .claude/observability/
+.observability/
 .claude/worktrees/
 # loop-lane escalation records (docs/conventions/loop-lane/README.md §2 — signal, not storage)
 .claude/lane-escalations/