@rulemetric/hooks 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulemetric/hooks",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "publishConfig": {
     "access": "public"
   },

package/scripts/_ensure-session.sh

@@ -138,6 +138,16 @@ _rulemetric_ensure_session() {
     org_id_arg=$(jq -n --arg v "$RULEMETRIC_ORG_ID" '$v')
   fi
 
+  # Multi-session-run attribution (Task 3.1). RULEMETRIC_RUN_ID is injected
+  # into the spawned session's env by the launcher when this session is part
+  # of a fanned-out run. The API validates ownership and silently nulls a
+  # bad/unowned runId, so capture never breaks. Encode `null` when unset —
+  # normal (non-run) sessions are unaffected.
+  local run_id_arg='null'
+  if [ -n "${RULEMETRIC_RUN_ID:-}" ]; then
+    run_id_arg=$(jq -n --arg v "$RULEMETRIC_RUN_ID" '$v')
+  fi
+
   local payload
   payload=$(jq -n \
     --arg tool "$HOOK_TOOL" \
@@ -146,7 +156,8 @@ _rulemetric_ensure_session() {
     --arg gitBranch "$git_branch" \
     --argjson metadata "$metadata" \
     --argjson orgId "$org_id_arg" \
-    '{tool: $tool, externalSessionId: $externalSessionId, projectPath: $projectPath, gitBranch: $gitBranch, metadata: $metadata, orgId: $orgId}')
+    --argjson runId "$run_id_arg" \
+    '{tool: $tool, externalSessionId: $externalSessionId, projectPath: $projectPath, gitBranch: $gitBranch, metadata: $metadata, orgId: $orgId, runId: $runId}')
 
   local response
   response=$(curl -sf -X POST "${RULEMETRIC_API_URL}/api/sessions" \

package/scripts/_normalize.sh

@@ -31,7 +31,28 @@ _rulemetric_normalize() {
   has_conversation_id=$(echo "$input" | jq -r 'has("conversation_id")' 2>/dev/null)
   has_hook_event_name=$(echo "$input" | jq -r 'has("hook_event_name")' 2>/dev/null)
 
-  if [ "$has_toolName" = "true" ] && [ "$has_sessionId" != "true" ]; then
+  # Antigravity: keyed on RULEMETRIC_HOOK_TOOL env var (set by our hook
+  # config in ~/.gemini/config/hooks.json). The payload uses camelCase
+  # `conversationId` + `workspacePaths[]` + `transcriptPath`, with
+  # tool args nested under `toolCall.{name,args}`.
+  if [ "${RULEMETRIC_HOOK_TOOL:-}" = "antigravity" ]; then
+    HOOK_TOOL="antigravity"
+    HOOK_SESSION_ID=$(echo "$input" | jq -r '.conversationId // empty' 2>/dev/null)
+    HOOK_CWD=$(echo "$input" | jq -r '
+      .workspacePaths[0] //
+      .workspace_roots[0] //
+      .cwd //
+      .toolCall.args.Cwd //
+      .toolCall.args.cwd //
+      empty
+    ' 2>/dev/null)
+    HOOK_PROMPT=""
+    HOOK_TOOL_NAME=$(echo "$input" | jq -r '.toolCall.name // .tool_name // empty' 2>/dev/null)
+    HOOK_TOOL_INPUT=$(echo "$input" | jq -c '.toolCall.args // .tool_input // {}' 2>/dev/null || echo '{}')
+    HOOK_TOOL_OUTPUT=$(echo "$input" | jq -c '.toolCall.result // .tool_response // {}' 2>/dev/null || echo '{}')
+    HOOK_TRANSCRIPT_PATH=$(echo "$input" | jq -r '.transcriptPath // empty' 2>/dev/null)
+
+  elif [ "$has_toolName" = "true" ] && [ "$has_sessionId" != "true" ]; then
     # Copilot CLI: no session ID, uses toolName/toolArgs/toolResult
     HOOK_TOOL="copilot_cli"
 

package/scripts/_paper-trail.sh

@@ -0,0 +1,204 @@
+#!/usr/bin/env bash
+# RuleMetric: Session paper-trail snapshot (container-use style "auto-commit
+# everything", no containers).
+#
+# Defines _rulemetric_paper_trail_snapshot() which snapshots the FULL working
+# tree to a shadow git ref:
+#
+#   refs/rulemetric/paper-trail/<session-id>
+#
+# It NEVER touches HEAD, the user's index, the working tree, or any visible
+# branch — all writes go through a TEMP index file + write-tree + commit-tree +
+# update-ref. Shadow refs don't appear in normal `git status`/`git log`.
+#
+# Must be sourced AFTER _normalize.sh (needs HOOK_SESSION_ID, HOOK_TOOL_NAME,
+# HOOK_TOOL_INPUT) and _ensure-session.sh (sets TEMP_DIR). Falls back to a
+# sane TEMP_DIR if unset so the function is usable standalone (e.g. in tests).
+#
+# Every failure is swallowed: the snapshot must NEVER break capture or fail the
+# hook. The function always returns 0.
+
+# Best-effort ISO-8601 UTC timestamp.
+_rulemetric_paper_trail_ts() {
+  date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo ""
+}
+
+# Try to derive the edited file path from HOOK_TOOL_INPUT JSON. Tools use
+# `file_path` (Edit/Write/MultiEdit) or `notebook_path` (NotebookEdit). Returns
+# empty on any failure — purely cosmetic for the commit message.
+_rulemetric_paper_trail_file() {
+  if ! command -v jq >/dev/null 2>&1; then
+    echo ""
+    return 0
+  fi
+  printf '%s' "${HOOK_TOOL_INPUT:-{\}}" \
+    | jq -r '.file_path // .notebook_path // .path // empty' 2>/dev/null \
+    || echo ""
+}
+
+_rulemetric_paper_trail_snapshot() {
+  # Gate: default ON; RULEMETRIC_PAPER_TRAIL=0 disables.
+  if [ "${RULEMETRIC_PAPER_TRAIL:-1}" = "0" ]; then
+    return 0
+  fi
+
+  # Need a session id to name the ref.
+  if [ -z "${HOOK_SESSION_ID:-}" ]; then
+    return 0
+  fi
+
+  # Must be inside a git work tree. Clean skip otherwise.
+  if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    _rulemetric_log "paper-trail" "skip" "not_a_git_repo"
+    return 0
+  fi
+
+  # Ensure we have a temp dir for the isolated index file.
+  local temp_dir="${TEMP_DIR:-${TMPDIR:-/tmp}/rulemetric}"
+  mkdir -p "$temp_dir" 2>/dev/null || {
+    _rulemetric_log "paper-trail" "error" "mkdir_temp_dir_failed"
+    return 0
+  }
+
+  local ref="refs/rulemetric/paper-trail/$HOOK_SESSION_ID"
+
+  # Per-call temp index. Claude Code runs tool calls in PARALLEL within one
+  # session (same HOOK_SESSION_ID), so a shared index path would be clobbered
+  # by concurrent invocations. A unique path per call ($$ pid + $RANDOM) keeps
+  # each write-tree isolated.
+  local tmp_index="$temp_dir/$HOOK_SESSION_ID.$$.${RANDOM}.ptindex"
+
+  # Build the tree from the working tree using ONLY the temp index. The
+  # working-tree READ does not need the lock (git read-tree/add/write-tree only
+  # touch our private GIT_INDEX_FILE, never the user's index). Wrapped in a
+  # subshell so a failure under `set -e` (the caller runs with -euo pipefail)
+  # can't abort the hook. `|| true` on the seed read-tree so an empty/headless
+  # repo still works.
+  local tree=""
+  tree=$(
+    set +e
+    GIT_INDEX_FILE="$tmp_index" git read-tree HEAD 2>/dev/null \
+      || GIT_INDEX_FILE="$tmp_index" git read-tree --empty 2>/dev/null
+    GIT_INDEX_FILE="$tmp_index" git add -A 2>/dev/null
+    GIT_INDEX_FILE="$tmp_index" git write-tree 2>/dev/null
+  ) || true
+
+  # Clean up the per-call temp index regardless of outcome.
+  rm -f "$tmp_index" 2>/dev/null || true
+
+  if [ -z "$tree" ]; then
+    _rulemetric_log "paper-trail" "error" "write_tree_failed"
+    return 0
+  fi
+
+  # --- Critical section: read-parent → de-dup → commit-tree → update-ref ------
+  # Parallel tool calls share HOOK_SESSION_ID and therefore the same trail ref.
+  # Without serialization, two snapshots read the same parent tip, both commit
+  # off it, and the second update-ref clobbers the first (last-writer-wins →
+  # silent loss of trail commits). Serialize with the same atomic mkdir lock
+  # pattern used by post-tool-use.sh (the .seqlock pattern) so parent
+  # computation and ref update are atomic.
+  #
+  # Bounded wait: give up after ~5s of contention so a stale lock (e.g. a hook
+  # that was SIGKILLed mid-section) can never hang the hook. On give-up we skip
+  # and log — the snapshot is best-effort.
+  local lock_dir="$temp_dir/$HOOK_SESSION_ID.ptlock"
+  local waited=0
+  local got_lock=0
+  while true; do
+    if mkdir "$lock_dir" 2>/dev/null; then
+      got_lock=1
+      break
+    fi
+    if [ "$waited" -ge 500 ]; then
+      break
+    fi
+    waited=$((waited + 1))
+    sleep 0.01
+  done
+
+  if [ "$got_lock" != "1" ]; then
+    _rulemetric_log "paper-trail" "skip" "lock_timeout"
+    return 0
+  fi
+
+  # Everything from here to the matching rmdir MUST release the lock on every
+  # path. We run the whole critical section in a subshell with `set +e` and an
+  # EXIT trap that removes the lock dir, so even an unexpected failure releases
+  # it. The subshell returns the outcome; the function still always returns 0.
+  (
+    set +e
+    # Release the lock no matter how this subshell exits (success, failure,
+    # early return, or signal-ish abort).
+    trap 'rmdir "$lock_dir" 2>/dev/null || true' EXIT
+
+    # Parent = current trail tip if present, else HEAD if the repo has commits.
+    # `ref_old` is the CURRENT value of the trail ref (empty if it doesn't yet
+    # exist) — that, not `parent`, is the compare-and-swap expected-old value.
+    local ref_old=""
+    ref_old=$(git rev-parse --verify -q "$ref" 2>/dev/null || true)
+    local parent="$ref_old"
+    if [ -z "$parent" ]; then
+      parent=$(git rev-parse --verify -q HEAD 2>/dev/null || true)
+    fi
+
+    # De-dup: if the parent's tree equals the new tree, write nothing.
+    if [ -n "$parent" ]; then
+      local parent_tree=""
+      parent_tree=$(git rev-parse -q "$parent^{tree}" 2>/dev/null || true)
+      if [ -n "$parent_tree" ] && [ "$parent_tree" = "$tree" ]; then
+        _rulemetric_log "paper-trail" "skip" "no_change"
+        exit 0
+      fi
+    fi
+
+    # Build the commit message.
+    local file
+    file=$(_rulemetric_paper_trail_file)
+    local tool="${HOOK_TOOL_NAME:-unknown}"
+    local run="${RULEMETRIC_RUN_ID:-none}"
+    local ts
+    ts=$(_rulemetric_paper_trail_ts)
+    local msg
+    if [ -n "$file" ]; then
+      msg="paper-trail: $tool $file (session ${HOOK_SESSION_ID} run ${run}) $ts"
+    else
+      msg="paper-trail: $tool (session ${HOOK_SESSION_ID} run ${run}) $ts"
+    fi
+
+    # Create the commit. Use a fixed rulemetric identity so the commit never
+    # depends on (or pollutes) the user's git config.
+    local commit=""
+    if [ -n "$parent" ]; then
+      commit=$(
+        printf '%s' "$msg" | GIT_AUTHOR_NAME=rulemetric GIT_COMMITTER_NAME=rulemetric \
+          GIT_AUTHOR_EMAIL=rulemetric@localhost GIT_COMMITTER_EMAIL=rulemetric@localhost \
+          git commit-tree "$tree" -p "$parent" 2>/dev/null
+      )
+    else
+      commit=$(
+        printf '%s' "$msg" | GIT_AUTHOR_NAME=rulemetric GIT_COMMITTER_NAME=rulemetric \
+          GIT_AUTHOR_EMAIL=rulemetric@localhost GIT_COMMITTER_EMAIL=rulemetric@localhost \
+          git commit-tree "$tree" 2>/dev/null
+      )
+    fi
+
+    if [ -z "$commit" ]; then
+      _rulemetric_log "paper-trail" "error" "commit_tree_failed"
+      exit 0
+    fi
+
+    # Update only the shadow ref. Compare-and-swap on the ref's expected old
+    # value (empty string ⇒ "ref must not yet exist") — belt-and-suspenders
+    # alongside the lock so a concurrent writer can never be silently
+    # clobbered. Never touches HEAD or any visible branch.
+    if git update-ref "$ref" "$commit" "$ref_old" 2>/dev/null; then
+      _rulemetric_log "paper-trail" "success" "$ref"
+    else
+      _rulemetric_log "paper-trail" "error" "update_ref_failed"
+    fi
+    exit 0
+  ) || true
+
+  return 0
+}

package/scripts/jq

@@ -0,0 +1,310 @@
+#!/usr/bin/env python3
+# LAST-RESORT FALLBACK for hosts without real jq — NOT a full jq implementation.
+# Supports only the narrow filter subset the bundled hook scripts use (see the
+# hardcoded fast-path patterns below). Any other expression may silently return
+# wrong output. If you're extending a hook script with a new jq filter, test it
+# against this shim or require real jq. PATH order matters: real jq wins when
+# installed; this file is only found via the scripts dir.
+import json
+import re
+import sys
+
+
+class Empty:
+    pass
+
+
+EMPTY = Empty()
+
+
+def parse_args(argv):
+    flags = set()
+    vars_ = {}
+    filter_ = None
+    files = []
+    i = 0
+    while i < len(argv):
+        arg = argv[i]
+        if arg == "--arg":
+            vars_[argv[i + 1]] = argv[i + 2]
+            i += 3
+        elif arg == "--argjson":
+            raw = argv[i + 2]
+            try:
+                vars_[argv[i + 1]] = json.loads(raw)
+            except Exception:
+                vars_[argv[i + 1]] = None
+            i += 3
+        elif arg.startswith("-") and arg != "-":
+            for ch in arg[1:]:
+                flags.add(ch)
+            i += 1
+        else:
+            if filter_ is None:
+                filter_ = arg
+            else:
+                files.append(arg)
+            i += 1
+    return flags, vars_, filter_ or ".", files
+
+
+def path_get(obj, expr):
+    if not expr.startswith("."):
+        return EMPTY
+    cur = obj
+    rest = expr[1:]
+    if rest == "":
+        return cur
+
+    tokens = []
+    i = 0
+    while i < len(rest):
+        if rest[i] == ".":
+            i += 1
+            continue
+        if rest[i] == "[":
+            end = rest.find("]", i)
+            if end == -1:
+                return None
+            try:
+                tokens.append(int(rest[i + 1:end]))
+            except Exception:
+                return None
+            i = end + 1
+            continue
+        m = re.match(r"[A-Za-z_][A-Za-z0-9_]*", rest[i:])
+        if not m:
+            return None
+        tokens.append(m.group(0))
+        i += len(m.group(0))
+
+    for token in tokens:
+        if isinstance(token, int):
+            if not isinstance(cur, list) or token >= len(cur):
+                return None
+            cur = cur[token]
+        else:
+            if not isinstance(cur, dict) or token not in cur:
+                return None
+            cur = cur[token]
+    return cur
+
+
+def eval_simple(expr, data, vars_):
+    expr = expr.strip()
+    if expr == "empty":
+        return EMPTY
+    if expr == "null":
+        return None
+    if expr == "{}":
+        return {}
+    if expr == ".":
+        return data
+    if expr.startswith("$"):
+        return vars_.get(expr[1:], "")
+    if len(expr) >= 2 and expr[0] == '"' and expr[-1] == '"':
+        return json.loads(expr)
+
+    m = re.fullmatch(r'has\("([^"]+)"\)', expr)
+    if m:
+        return isinstance(data, dict) and m.group(1) in data
+
+    m = re.fullmatch(r"(.+)\\|\\s*length", expr)
+    if m:
+        value = eval_filter(m.group(1), data, vars_)
+        if value is EMPTY or value is None:
+            return 0
+        return len(value)
+
+    if expr == '[.suggestions[] | select(.content != null)]':
+        suggestions = path_get(data, ".suggestions")
+        if not isinstance(suggestions, list):
+            return []
+        return [item for item in suggestions if isinstance(item, dict) and item.get("content") is not None]
+
+    if expr.startswith("{") and "with_entries" in expr:
+        obj_src = expr.split("|", 1)[0].strip()
+        return eval_object_literal(obj_src, data, vars_, drop_null=True)
+
+    if expr.startswith("{") and expr.endswith("}"):
+        return eval_object_literal(expr, data, vars_, drop_null=False)
+
+    return path_get(data, expr)
+
+
+def split_fallbacks(expr):
+    return [part.strip() for part in expr.split("//")]
+
+
+def eval_filter(expr, data, vars_):
+    expr = " ".join(expr.strip().split())
+
+    if "//" in expr:
+        for part in split_fallbacks(expr):
+            value = eval_simple(part, data, vars_)
+            if value is EMPTY:
+                continue
+            if value is not None:
+                return value
+        return EMPTY
+
+    return eval_simple(expr, data, vars_)
+
+
+def eval_object_literal(expr, data, vars_, drop_null=False):
+    inner = expr.strip()[1:-1].strip()
+    if not inner:
+        return {}
+    out = {}
+    parts = []
+    depth = 0
+    start = 0
+    for i, ch in enumerate(inner):
+        if ch in "{[":
+            depth += 1
+        elif ch in "}]":
+            depth -= 1
+        elif ch == "," and depth == 0:
+            parts.append(inner[start:i])
+            start = i + 1
+    parts.append(inner[start:])
+
+    for part in parts:
+        if ":" not in part:
+            continue
+        key, raw_expr = part.split(":", 1)
+        key = key.strip().strip('"')
+        value = eval_filter(raw_expr.strip(), data, vars_)
+        if drop_null and (value is None or value is EMPTY):
+            continue
+        out[key] = None if value is EMPTY else value
+    return out
+
+
+def build_known_n_filter(filter_, vars_):
+    compact = " ".join(filter_.strip().split())
+
+    if compact == "$v":
+        return vars_.get("v", "")
+
+    if "script: $script" in compact and "outcome: $outcome" in compact:
+        return {
+            "ts": vars_.get("ts", ""),
+            "script": vars_.get("script", ""),
+            "outcome": vars_.get("outcome", ""),
+            "reason": vars_.get("reason", ""),
+            "session": vars_.get("session", ""),
+        }
+
+    if "gitRemote" in compact and "isWorktree" in compact:
+        out = {}
+        if vars_.get("gitRemote"):
+            out["gitRemote"] = vars_["gitRemote"]
+        if vars_.get("gitRootCommit"):
+            out["gitRootCommit"] = vars_["gitRootCommit"]
+        if vars_.get("launchProjectPath"):
+            out["launchProjectPath"] = vars_["launchProjectPath"]
+        out["isWorktree"] = bool(vars_.get("isWorktree"))
+        out["headless"] = bool(vars_.get("isHeadless"))
+        return out
+
+    if "externalSessionId" in compact and "projectPath" in compact:
+        return {
+            "tool": vars_.get("tool", ""),
+            "externalSessionId": vars_.get("externalSessionId", ""),
+            "projectPath": vars_.get("projectPath", ""),
+            "gitBranch": vars_.get("gitBranch", ""),
+            "metadata": vars_.get("metadata", {}),
+            "orgId": vars_.get("orgId"),
+        }
+
+    if 'eventType: "tool_call"' in compact:
+        return {
+            "sequence": vars_.get("seq"),
+            "eventType": "tool_call",
+            "toolName": vars_.get("toolName", ""),
+            "toolInput": vars_.get("toolInput", {}),
+            "toolOutput": vars_.get("toolOutput", {}),
+            "timestamp": vars_.get("timestamp", ""),
+        }
+
+    if "input_tokens" in compact and "cache_creation_input_tokens" in compact:
+        out = {}
+        mapping = [
+            ("in", "input_tokens"),
+            ("out", "output_tokens"),
+            ("cr", "cache_read_input_tokens"),
+            ("cw", "cache_creation_input_tokens"),
+        ]
+        for var, key in mapping:
+            raw = vars_.get(var, "")
+            if raw != "":
+                try:
+                    out[key] = int(raw)
+                except Exception:
+                    try:
+                        out[key] = float(raw)
+                    except Exception:
+                        pass
+        return out
+
+    if "generationId" in compact and "usage" in compact:
+        out = {}
+        if vars_.get("generationId"):
+            out["generationId"] = vars_["generationId"]
+        usage = vars_.get("usage", {})
+        if isinstance(usage, dict) and len(usage) > 0:
+            out["usage"] = usage
+        return out
+
+    if 'eventType: "assistant_response"' in compact:
+        return {
+            "sequence": vars_.get("seq"),
+            "eventType": "assistant_response",
+            "content": vars_.get("text", ""),
+            "timestamp": vars_.get("timestamp", ""),
+            "metadata": vars_.get("metadata", {}),
+        }
+
+    return eval_filter(filter_, {}, vars_)
+
+
+def emit(value, raw=False, compact=False):
+    if value is EMPTY:
+        return
+    if raw and isinstance(value, str):
+        sys.stdout.write(value + "\n")
+    elif raw and value is None:
+        sys.stdout.write("\n")
+    elif raw and isinstance(value, bool):
+        sys.stdout.write(("true" if value else "false") + "\n")
+    else:
+        sys.stdout.write(json.dumps(value, separators=(",", ":") if compact else None) + "\n")
+
+
+def main():
+    flags, vars_, filter_, files = parse_args(sys.argv[1:])
+    if files:
+        with open(files[0], "r", encoding="utf-8") as handle:
+            stdin = handle.read()
+    else:
+        stdin = sys.stdin.read()
+
+    if "R" in flags and "s" in flags and filter_.strip() == ".":
+        emit(stdin, raw=False, compact="c" in flags)
+        return
+
+    if "n" in flags:
+        emit(build_known_n_filter(filter_, vars_), raw="r" in flags, compact="c" in flags)
+        return
+
+    try:
+        data = json.loads(stdin) if stdin.strip() else None
+    except Exception:
+        sys.exit(4)
+
+    emit(eval_filter(filter_, data, vars_), raw="r" in flags, compact="c" in flags)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/paper-trail.test.sh

@@ -0,0 +1,275 @@
+#!/usr/bin/env bash
+# RuleMetric: Safety test for the session paper-trail snapshot.
+#
+# Run with: bash packages/hooks/scripts/paper-trail.test.sh
+# Exits non-zero on any failed assertion.
+#
+# The most important assertion is the SAFETY INVARIANT: after a snapshot, the
+# user's current branch, HEAD, `git status --porcelain`, and the staged index
+# must be BYTE-IDENTICAL to before the snapshot. The snapshot must only ever
+# touch refs/rulemetric/paper-trail/<id>.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Colors (fall back to plain if not a tty).
+if [ -t 1 ]; then
+  C_OK="\033[32m"; C_FAIL="\033[31m"; C_RST="\033[0m"
+else
+  C_OK=""; C_FAIL=""; C_RST=""
+fi
+
+FAILURES=0
+PASSES=0
+
+ok() {
+  printf "${C_OK}OK${C_RST}   %s\n" "$1"
+  PASSES=$((PASSES + 1))
+}
+fail() {
+  printf "${C_FAIL}FAIL${C_RST} %s\n" "$1"
+  FAILURES=$((FAILURES + 1))
+}
+
+assert_eq() {
+  # assert_eq <description> <expected> <actual>
+  if [ "$2" = "$3" ]; then
+    ok "$1"
+  else
+    fail "$1 (expected [$2], got [$3])"
+  fi
+}
+
+# --- Stub _rulemetric_log so _paper-trail.sh can call it standalone ----------
+_rulemetric_log() { :; }
+
+# --- Build a throwaway git repo ----------------------------------------------
+WORK_ROOT=$(mktemp -d "${TMPDIR:-/tmp}/pt-test.XXXXXX")
+REPO="$WORK_ROOT/repo"
+mkdir -p "$REPO"
+
+cleanup() {
+  rm -rf "$WORK_ROOT" 2>/dev/null || true
+}
+trap cleanup EXIT
+
+cd "$REPO" || { echo "cd to repo failed"; exit 1; }
+git init -q
+git checkout -q -b work-branch 2>/dev/null || git switch -q -c work-branch 2>/dev/null || true
+git config user.name "Test User"
+git config user.email "test@example.com"
+echo "initial" > a.txt
+git add a.txt
+git commit -q -m "initial commit"
+
+# Source the function under test.
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/_paper-trail.sh"
+
+# Test scaffolding env.
+export HOOK_SESSION_ID="11111111-2222-3333-4444-555555555555"
+export TEMP_DIR="$WORK_ROOT/tmp"
+mkdir -p "$TEMP_DIR"
+export HOOK_TOOL_NAME="Write"
+export HOOK_TOOL_INPUT='{"file_path":"b.txt"}'
+
+REF="refs/rulemetric/paper-trail/$HOOK_SESSION_ID"
+
+# Count paper-trail commits only — commits reachable from the trail ref but
+# NOT from HEAD. The first snapshot parents off HEAD, so the trail's full
+# ancestry includes the user's real commits; those must be excluded to count
+# the paper-trail entries themselves.
+count_commits() {
+  if ! git rev-parse --verify -q "$REF" >/dev/null 2>&1; then
+    echo "0"
+    return 0
+  fi
+  git rev-list --count "$REF" --not HEAD 2>/dev/null || echo "0"
+}
+
+# --- Capture pre-snapshot safety state ---------------------------------------
+make_change_1() { echo "change one" > b.txt; }
+make_change_1
+
+PRE_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+PRE_HEAD=$(git rev-parse HEAD)
+PRE_STATUS=$(git status --porcelain)
+PRE_INDEX=$(git diff --cached --name-only)
+
+# --- Snapshot #1 -------------------------------------------------------------
+_rulemetric_paper_trail_snapshot
+
+POST_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+POST_HEAD=$(git rev-parse HEAD)
+POST_STATUS=$(git status --porcelain)
+POST_INDEX=$(git diff --cached --name-only)
+
+echo "--- Safety invariant (branch / HEAD / status / staged index unchanged) ---"
+assert_eq "branch name unchanged"          "$PRE_BRANCH" "$POST_BRANCH"
+assert_eq "HEAD commit unchanged"          "$PRE_HEAD"   "$POST_HEAD"
+assert_eq "git status --porcelain unchanged" "$PRE_STATUS" "$POST_STATUS"
+assert_eq "staged index unchanged"         "$PRE_INDEX"  "$POST_INDEX"
+
+echo "--- Trail ref created ---"
+# Ref exists?
+if git rev-parse --verify -q "$REF" >/dev/null 2>&1; then
+  ok "trail ref exists"
+else
+  fail "trail ref exists"
+fi
+assert_eq "trail has exactly 1 commit" "1" "$(count_commits)"
+
+# Tree of the trail tip contains the change (b.txt with new content)?
+TRAIL_B=$(git show "$REF:b.txt" 2>/dev/null || echo "")
+assert_eq "trail tip tree contains the change" "change one" "$TRAIL_B"
+
+# --- Snapshot #2 (with a new change) -----------------------------------------
+echo "--- Second change → 2 commits ---"
+echo "change two" > b.txt
+_rulemetric_paper_trail_snapshot
+assert_eq "trail has 2 commits after second change" "2" "$(count_commits)"
+
+# --- Snapshot #3 (no change → de-dup) ----------------------------------------
+echo "--- No change → de-dup (still 2 commits) ---"
+_rulemetric_paper_trail_snapshot
+assert_eq "trail still has 2 commits (de-dup)" "2" "$(count_commits)"
+
+# --- Gate: RULEMETRIC_PAPER_TRAIL=0 is a no-op --------------------------------
+echo "--- Gate RULEMETRIC_PAPER_TRAIL=0 ---"
+echo "change three" > b.txt
+RULEMETRIC_PAPER_TRAIL=0 _rulemetric_paper_trail_snapshot
+assert_eq "gate=0 makes it a no-op (still 2 commits)" "2" "$(count_commits)"
+
+# --- Non-git dir → clean skip ------------------------------------------------
+echo "--- Non-git dir clean skip ---"
+NONGIT="$WORK_ROOT/nongit"
+mkdir -p "$NONGIT"
+(
+  cd "$NONGIT" || exit 1
+  echo "loose" > x.txt
+  # Ensure it really is not inside a git tree.
+  if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    echo "PRECHECK_FAIL: nongit dir is inside a work tree"
+    exit 2
+  fi
+  _rulemetric_paper_trail_snapshot
+  rc=$?
+  exit $rc
+)
+NONGIT_RC=$?
+assert_eq "non-git dir returns 0 (clean skip)" "0" "$NONGIT_RC"
+
+# --- Concurrency: N parallel snapshots → N distinct commits ------------------
+# Claude Code runs tool calls in PARALLEL within one session (same
+# HOOK_SESSION_ID). Each parallel snapshot must be serialized into its own
+# distinct trail commit by the per-session lock — no clobbering / lost commits.
+#
+# Design constraints this test must satisfy to be a real regression guard:
+#   1. The N snapshots must run as genuinely concurrent processes contending
+#      for the paper-trail's OWN lock (NOT a test-level lock around the whole
+#      mutate→snapshot window — that would mask the bug, since fully serialized
+#      dispatch trivially avoids both the index clobber and the update-ref
+#      race). Verified: a whole-window test-level lock makes even the pre-fix
+#      buggy code pass, so it is useless as a guard.
+#   2. Each snapshot must observe a DISTINCT full working tree, or de-dup
+#      legitimately collapses them and the count is meaningless. paper-trail
+#      snapshots the WHOLE tree, so if all jobs append before any snapshot runs
+#      write-tree, every snapshot sees the same final tree → 1 commit.
+#
+# We satisfy both by giving each job its OWN file (f_$i.txt — no write contention
+# on a shared file) and a small per-index stagger before it appends+snapshots.
+# The stagger (STEP ms, >> a snapshot's runtime) spreads the N file-creations
+# across real time so each snapshot, when it wins the paper-trail lock, observes
+# a distinct set of f_*.txt files. The jobs are still N concurrent processes —
+# the stagger only offsets their start, it does not serialize the lock-protected
+# section, which is what the fix must protect. Each job appends a per-job nonce
+# too, so a job that somehow runs twice still produces a unique tree.
+echo "--- Concurrency: N parallel snapshots → N distinct commits ---"
+
+# Use a fresh session id so this trail starts clean and the count is unambiguous.
+export HOOK_SESSION_ID="99999999-8888-7777-6666-555555555555"
+CONC_REF="refs/rulemetric/paper-trail/$HOOK_SESSION_ID"
+
+# Per-index start stagger. paper-trail snapshots the WHOLE tree and de-dups
+# identical trees, so to get N *distinct* (non-de-duped) trees each snapshot
+# must observe a distinct set of f_*.txt files. That requires the file
+# creations to be ordered w.r.t. the snapshots: hence a stagger (STEP_MS)
+# comfortably larger than one snapshot's git-plumbing runtime, so snapshot i
+# reliably observes files 1..i and produces a tree distinct from all others.
+# The jobs are still N concurrent background processes piling onto the
+# paper-trail lock — the lock + per-call index + CAS update-ref is what keeps
+# every one of the N distinct commits instead of clobbering down to fewer.
+#
+# A smaller stagger forces more overlap (and reliably breaks the PRE-FIX code,
+# observed dropping to 1-2 commits), but then de-dup legitimately collapses
+# trees that have converged to the full file set, so it is not a clean
+# count==N assertion. 40ms keeps the trees distinct and the assertion exact.
+STEP_MS=40
+N=12
+pids=()
+for i in $(seq 1 "$N"); do
+  # Precompute the per-index delay in seconds (e.g. 0.040, 0.080, ...) without
+  # nested quoting inside the subshell. Integer ms → "S.mmm" via printf.
+  delay_ms=$(( (i - 1) * STEP_MS ))
+  delay=$(printf '%d.%03d' "$(( delay_ms / 1000 ))" "$(( delay_ms % 1000 ))")
+  (
+    # Stagger start so file-creation order is spread across real time.
+    sleep "$delay"
+    # Distinct, growing tree: this job creates its own file. By staggering,
+    # each snapshot observes a strictly-larger set of f_*.txt files.
+    echo "concurrent-$i" > "f_$i.txt"
+    _rulemetric_paper_trail_snapshot
+  ) &
+  pids+=("$!")
+done
+
+# Wait for all parallel jobs to finish.
+for pid in "${pids[@]}"; do
+  wait "$pid"
+done
+
+conc_count() {
+  if ! git rev-parse --verify -q "$CONC_REF" >/dev/null 2>&1; then
+    echo "0"
+    return 0
+  fi
+  git rev-list --count "$CONC_REF" --not HEAD 2>/dev/null || echo "0"
+}
+CONC_ACTUAL="$(conc_count)"
+assert_eq "all $N parallel snapshots produced $N distinct commits" "$N" "$CONC_ACTUAL"
+
+# The lock must be released after the burst — no stale lock dir left behind.
+if [ -d "$TEMP_DIR/$HOOK_SESSION_ID.ptlock" ]; then
+  fail "lock dir was left behind after concurrent burst"
+else
+  ok "lock dir released after concurrent burst"
+fi
+
+# Restore the original session id for any later assertions.
+export HOOK_SESSION_ID="11111111-2222-3333-4444-555555555555"
+
+# Clean up the per-job files so the final safety re-check sees a stable tree.
+rm -f f_*.txt 2>/dev/null || true
+
+# --- Final safety re-check (after all snapshots) -----------------------------
+# Reset working file to match the committed state for a stable status compare,
+# matching pre-state captured above (b.txt was unstaged, content "change one").
+echo "--- Final safety re-check ---"
+echo "change one" > b.txt
+FINAL_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+FINAL_HEAD=$(git rev-parse HEAD)
+FINAL_STATUS=$(git status --porcelain)
+FINAL_INDEX=$(git diff --cached --name-only)
+assert_eq "branch still unchanged at end"   "$PRE_BRANCH" "$FINAL_BRANCH"
+assert_eq "HEAD still unchanged at end"      "$PRE_HEAD"   "$FINAL_HEAD"
+assert_eq "status still unchanged at end"    "$PRE_STATUS" "$FINAL_STATUS"
+assert_eq "staged index still unchanged at end" "$PRE_INDEX" "$FINAL_INDEX"
+
+# --- Summary -----------------------------------------------------------------
+echo ""
+echo "Passed: $PASSES  Failed: $FAILURES"
+if [ "$FAILURES" -gt 0 ]; then
+  exit 1
+fi
+exit 0

package/scripts/post-tool-use.sh

@@ -13,6 +13,18 @@ source "$SCRIPT_DIR/_config.sh" 2>/dev/null || true
 INPUT=$(cat)
 source "$SCRIPT_DIR/_normalize.sh"
 
+# Session paper-trail: snapshot the full working tree to a shadow git ref for
+# file-mutating tools. Runs BEFORE the capture/auth guards below — the local
+# audit trail only needs HOOK_SESSION_ID + a git repo, NOT RuleMetric API auth,
+# so a user gets the trail even before (or without) capture being configured.
+# Swallows all failures and can never change the hook's exit behavior.
+case "$HOOK_TOOL_NAME" in
+  Edit|Write|MultiEdit|NotebookEdit)
+    source "$SCRIPT_DIR/_paper-trail.sh" 2>/dev/null || true
+    _rulemetric_paper_trail_snapshot || true
+    ;;
+esac
+
 if [ -z "$HOOK_SESSION_ID" ] || [ -z "${RULEMETRIC_API_URL:-}" ]; then
   _rulemetric_log "post-tool-use" "skip" "no_config"
   exit 0

package/scripts/session-end.sh

@@ -122,6 +122,14 @@ else
     -d '{}' > /dev/null 2>&1) &
 fi
 
+# ── Tail transcript for 429 rate-limit events ──
+# Forward-only watcher: reads new lines since the cached byte offset and
+# posts any synthetic 429 messages to the research pipeline. Hook-safe
+# (rulemetric command catches its own errors).
+if [ -n "$HOOK_TRANSCRIPT_PATH" ] && [ -f "$HOOK_TRANSCRIPT_PATH" ]; then
+  (rulemetric research tail-transcript "$HOOK_TRANSCRIPT_PATH" > /dev/null 2>&1 || true) &
+fi
+
 # ── Auto-generate recommendations (daily debounce) ──
 # Queue a recommendation job if one hasn't been generated today.
 # The worker picks it up and runs 7 Opus prompts (~$5-15 per run).

package/scripts/session-start.sh

@@ -176,7 +176,8 @@ _rulemetric_suggest_instructions() {
       "${api_url}/api/instruction-suggestions/${sid}/events" \
       -H "Authorization: Bearer ${auth_token}" \
       -H "Content-Type: application/json" \
-      -d "{\"eventType\":\"${event_type}\",\"tool\":\"${tool}\",\"projectPath\":\"${project_path}\"}" \
+      -d "$(jq -n --arg eventType "$event_type" --arg tool "$tool" --arg projectPath "$project_path" \
+        '{eventType: $eventType, tool: $tool, projectPath: $projectPath}')" \
       >/dev/null 2>&1 &
     disown 2>/dev/null || true
     i=$((i + 1))