@onlooker-community/ecosystem 0.18.0 → 0.20.0

package/plugins/warden/scripts/lib/warden-scanner.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# Hybrid scanner orchestration for Warden.
+#
+# Combines the deterministic pattern floor (warden-patterns.sh) with optional
+# LLM escalation (warden-evaluator.sh):
+#
+#   strong pattern hit  → detected immediately (no model call)
+#   weak pattern hit     → escalate to the evaluator when enabled; otherwise
+#                          fall back to the weak-pattern confidence
+#   no hit               → clean (no model call)
+#
+# On evaluator error the scanner falls back to the pattern verdict, so a model
+# outage degrades coverage but never silently closes the gate on every read.
+#
+# Depends on (sourced by the caller):
+#   warden-config.sh · warden-patterns.sh · warden-sanitizer.sh · warden-evaluator.sh
+#
+# Exposes:
+#   warden_scan <source_type> <content>
+#     → JSON {"detected":bool, "threat_type":"<t>", "confidence":<f>,
+#             "matched_pattern":"<p>", "method":"<m>", "rationale":"<str>"}
+
+# awk-based float >= comparison. Returns 0 (true) if $1 >= $2.
+#
+# Values are passed via `awk -v` (data), never interpolated into the program
+# string: thresholds can originate from repo-level .claude/settings.json, which
+# is untrusted under warden's threat model. -v also makes non-numeric input
+# degrade to 0 rather than executing as awk code.
+_warden_ge() {
+	awk -v a="${1:-0}" -v b="${2:-0}" 'BEGIN {exit !(a >= b)}' 2>/dev/null
+}
+
+_warden_scan_result() {
+	local detected="$1" threat="$2" confidence="$3" pattern="$4" method="$5" rationale="$6"
+	jq -n \
+		--argjson detected "$detected" \
+		--arg t "$threat" \
+		--argjson c "${confidence:-0}" \
+		--arg p "$pattern" \
+		--arg m "$method" \
+		--arg r "$rationale" \
+		'{detected:$detected, threat_type:$t, confidence:$c, matched_pattern:$p, method:$m, rationale:$r}' \
+		2>/dev/null \
+		|| printf '{"detected":%s,"threat_type":"%s","confidence":%s,"matched_pattern":"%s","method":"%s","rationale":"%s"}' \
+			"$detected" "$threat" "${confidence:-0}" "$pattern" "$method" "$rationale"
+}
+
+warden_scan() {
+	local source_type="$1"
+	local content="$2"
+
+	local close_threshold strong_conf weak_conf
+	close_threshold=$(warden_config_get '.warden.detection.close_threshold')
+	close_threshold="${close_threshold:-0.65}"
+	strong_conf=$(warden_config_get '.warden.detection.strong_pattern_confidence')
+	strong_conf="${strong_conf:-0.9}"
+	weak_conf=$(warden_config_get '.warden.detection.weak_pattern_confidence')
+	weak_conf="${weak_conf:-0.5}"
+
+	local classify severity threat pattern
+	classify=$(warden_pattern_classify "$content")
+	severity=$(printf '%s' "$classify" | jq -r '.severity // "none"' 2>/dev/null) || severity="none"
+	threat=$(printf '%s' "$classify" | jq -r '.threat_type // "none"' 2>/dev/null) || threat="none"
+	pattern=$(printf '%s' "$classify" | jq -r '.matched_pattern // ""' 2>/dev/null) || pattern=""
+
+	# ---- Clean: no signal at all. ------------------------------------
+	if [[ "$severity" == "none" ]]; then
+		_warden_scan_result false "none" 0 "" "none" "no injection pattern matched"
+		return 0
+	fi
+
+	# ---- Strong: explicit, high-precision phrasing. ------------------
+	if [[ "$severity" == "strong" ]]; then
+		local detected="false"
+		_warden_ge "$strong_conf" "$close_threshold" && detected="true"
+		_warden_scan_result "$detected" "$threat" "$strong_conf" "$pattern" "pattern_strong" "matched a strong injection signature"
+		return 0
+	fi
+
+	# ---- Weak: borderline. Escalate when enabled. --------------------
+	local escalation_enabled
+	escalation_enabled=$(warden_config_get '.warden.escalation.enabled')
+	escalation_enabled="${escalation_enabled:-true}"
+
+	if [[ "$escalation_enabled" == "true" ]]; then
+		local max_chars excerpt
+		max_chars=$(warden_config_get '.warden.scan.max_content_chars')
+		max_chars="${max_chars:-20000}"
+		excerpt=$(warden_sanitize "$content" "$max_chars")
+
+		local eval_result decision eval_conf eval_threat eval_rationale
+		eval_result=$(warden_evaluate "$source_type" "$excerpt" "$threat")
+		decision=$(printf '%s' "$eval_result" | jq -r '.decision // "error"' 2>/dev/null) || decision="error"
+		eval_conf=$(printf '%s' "$eval_result" | jq -r '.confidence // 0' 2>/dev/null) || eval_conf="0"
+		eval_threat=$(printf '%s' "$eval_result" | jq -r '.threat_type // "none"' 2>/dev/null) || eval_threat="none"
+		eval_rationale=$(printf '%s' "$eval_result" | jq -r '.rationale // ""' 2>/dev/null) || eval_rationale=""
+
+		if [[ "$decision" == "injection" ]]; then
+			[[ "$eval_threat" == "none" || -z "$eval_threat" ]] && eval_threat="$threat"
+			local detected="false"
+			_warden_ge "$eval_conf" "$close_threshold" && detected="true"
+			_warden_scan_result "$detected" "$eval_threat" "$eval_conf" "$pattern" "escalation" "$eval_rationale"
+			return 0
+		fi
+
+		if [[ "$decision" == "clean" ]]; then
+			_warden_scan_result false "none" "$eval_conf" "$pattern" "escalation" "evaluator judged the borderline content clean"
+			return 0
+		fi
+
+		# decision == error → fall back to the weak-pattern verdict below.
+	fi
+
+	# ---- Weak fallback: no escalation, or evaluator errored. ---------
+	local detected="false"
+	_warden_ge "$weak_conf" "$close_threshold" && detected="true"
+	_warden_scan_result "$detected" "$threat" "$weak_conf" "$pattern" "pattern_weak" "weak injection signal; escalation unavailable"
+	return 0
+}

package/plugins/warden/scripts/lib/warden-ulid.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Minimal ULID generator for Warden threat_id values.
+#
+# Spec: https://github.com/ulid/spec
+#   - 48-bit timestamp (ms since epoch) → 10 chars Crockford Base32
+#   - 80-bit randomness → 16 chars Crockford Base32
+#   - lexicographically sortable, time-ordered
+
+_WARDEN_ULID_ALPHABET="0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+_warden_ulid_encode() {
+	local n="$1"
+	local len="$2"
+	local out=""
+	local i
+	for ((i = 0; i < len; i++)); do
+		out="${_WARDEN_ULID_ALPHABET:$((n % 32)):1}${out}"
+		n=$((n / 32))
+	done
+	printf '%s' "$out"
+}
+
+warden_ulid() {
+	local now_ms
+	if [[ "$(uname)" == "Darwin" ]]; then
+		now_ms=$(python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null) \
+			|| now_ms=$(($(date +%s) * 1000))
+	else
+		now_ms=$(date +%s%3N 2>/dev/null) || now_ms=$(($(date +%s) * 1000))
+	fi
+
+	local rand_hex rand_hi rand_lo
+	rand_hex=$(openssl rand -hex 10 2>/dev/null)
+	if [[ -n "$rand_hex" && ${#rand_hex} -eq 20 ]]; then
+		rand_hi=$((16#${rand_hex:0:10}))
+		rand_lo=$((16#${rand_hex:10:10}))
+	else
+		rand_hi=$((RANDOM * 32768 + RANDOM))
+		rand_lo=$((RANDOM * 32768 + RANDOM))
+		rand_hi=$(((rand_hi * 256 + RANDOM % 256) & ((1 << 40) - 1)))
+		rand_lo=$(((rand_lo * 256 + RANDOM % 256) & ((1 << 40) - 1)))
+	fi
+
+	local ts_part hi_part lo_part
+	ts_part=$(_warden_ulid_encode "$now_ms" 10)
+	hi_part=$(_warden_ulid_encode "$rand_hi" 8)
+	lo_part=$(_warden_ulid_encode "$rand_lo" 8)
+
+	printf '%s%s%s' "$ts_part" "$hi_part" "$lo_part"
+}

package/plugins/warden/skills/warden/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: warden
+description: Inspect and control the Warden content gate. Shows whether the session's content gate is open or closed and the threat that closed it (`/warden` or `/warden status`), and explicitly clears a closed gate to re-enable Write/Edit/Bash (`/warden clear`). Clearing is the only sanctioned way to reopen the gate — it records a user override in the warden.* event stream. Use when Warden has blocked a write/edit/bash operation, or when the user asks to check or clear the content gate.
+---
+
+# Warden: Content Gate Control
+
+You are operating the **Warden** content gate — the user-facing control surface for the gate that Warden's hooks open and close automatically.
+
+Warden enforces Meta's **Agents Rule of Two**: an agent should hold at most two of {access to private data, ability to take external actions, processing of untrusted content}. When Warden's detection hook finds an injection pattern in content ingested via WebFetch or Read, it closes a session-scoped gate that revokes the *external actions* property — blocking Write, Edit, MultiEdit, and Bash until the user explicitly clears it. This skill is that explicit clear (and a status readout).
+
+## Parse the request
+
+Read the user's argument after `/warden`:
+
+- no argument, or `status` → **status** action
+- `clear`, `reopen`, `override`, `unblock` → **clear** action
+
+If the user passed a session id explicitly (rare), capture it as the optional second argument.
+
+## Run the control surface
+
+Source the plugin helpers and invoke `warden_cli`. Run this in a single bash call:
+
+```bash
+set -uo pipefail
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/warden-config.sh"
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/warden-events.sh"
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/warden-gate-state.sh"
+source "$CLAUDE_PLUGIN_ROOT/scripts/lib/warden-cli.sh"
+
+# action is "status" or "clear"; SESSION_ID_ARG is optional and usually empty.
+warden_cli "<action>" "${SESSION_ID_ARG:-}"
+```
+
+`warden_cli` resolves the session automatically: it prefers `$CLAUDE_SESSION_ID`, falls back to the single closed gate if exactly one exists, and reports ambiguity if several sessions have closed gates (re-run with an explicit session id in that case).
+
+## Behavior
+
+- **status** — prints whether the gate is OPEN or CLOSED. When closed, prints the recorded threat: `threat_type`, `source_type`, source URL/path, confidence, detection method, matched pattern, and the flagged snippet (if storage is enabled).
+- **clear** — verifies the gate is closed, removes the lock, and emits `warden.threat.cleared` with `cleared_by: user_override`. This re-enables Write/Edit/Bash for the session.
+
+## After clearing
+
+When you clear the gate on the user's behalf:
+
+1. Confirm the gate is reopened and name the source that triggered it.
+2. Remind the user briefly that the flagged content is still in the conversation context — clearing the gate does not remove it. If they have not reviewed the source, suggest they do before continuing with external actions.
+3. Do not clear a gate the user has not asked you to clear. Closing is automatic; clearing is always a deliberate user decision.

package/release-please-config.json

@@ -142,6 +142,38 @@
           "jsonpath": "$.version"
         }
       ]
+    },
+    "plugins/warden": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "component": "warden",
+      "draft": false,
+      "prerelease": false,
+      "extra-files": [
+        {
+          "type": "json",
+          "path": ".claude-plugin/plugin.json",
+          "jsonpath": "$.version"
+        }
+      ]
+    },
+    "plugins/librarian": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "component": "librarian",
+      "draft": false,
+      "prerelease": false,
+      "extra-files": [
+        {
+          "type": "json",
+          "path": ".claude-plugin/plugin.json",
+          "jsonpath": "$.version"
+        }
+      ]
     }
   },
   "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"

package/test/bats/librarian-session-end.bats

@@ -0,0 +1,182 @@
+#!/usr/bin/env bats
+#
+# Exercises the librarian SessionEnd scan pipeline end-to-end with a stub
+# `claude` CLI. Verifies:
+#   - Disabled config: no proposals, no events.
+#   - Empty archivist dir: scan.started + scan.complete{outcome: empty}
+#     emitted, watermark advances.
+#   - Synthetic artifacts that pass durability filter and classifier:
+#     proposals land on disk with the expected provenance and scan events
+#     report the correct counts.
+#   - Durability-filtered artifacts (no marker phrase) emit
+#     candidate.dropped events.
+
+setup() {
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/librarian"
+  export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+  export ONLOOKER_ECOSYSTEM_ROOT="$REPO_ROOT"
+
+  # Stand up a fake project repo so project-key resolution succeeds.
+  PROJECT_REPO="${BATS_TEST_TMPDIR}/repo"
+  mkdir -p "$PROJECT_REPO"
+  git -C "$PROJECT_REPO" init -q
+  git -C "$PROJECT_REPO" config user.email t@example.com
+  git -C "$PROJECT_REPO" config user.name "Test"
+  git -C "$PROJECT_REPO" remote add origin git@github.com:org/librarian-scan-test.git
+
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/librarian-project-key.sh"
+  PROJECT_KEY=$(librarian_project_key "$PROJECT_REPO")
+  [ -n "$PROJECT_KEY" ]
+
+  ARCHIVIST_DIR="${ONLOOKER_DIR}/archivist/${PROJECT_KEY}"
+  LIBRARIAN_DIR="${ONLOOKER_DIR}/librarian/${PROJECT_KEY}"
+  ONLOOKER_EVENTS_LOG="${ONLOOKER_DIR}/logs/onlooker-events.jsonl"
+
+  # Project-scoped settings.json that enables librarian.
+  mkdir -p "${PROJECT_REPO}/.claude"
+  printf '%s\n' '{"librarian":{"enabled":true}}' > "${PROJECT_REPO}/.claude/settings.json"
+
+  # Stub `claude` CLI on PATH. Returns a deterministic classifier response
+  # based on the artifact's summary contents.
+  STUB_BIN="${BATS_TEST_TMPDIR}/bin"
+  mkdir -p "$STUB_BIN"
+  cat > "${STUB_BIN}/claude" <<'STUB'
+#!/usr/bin/env bash
+# Read the prompt from stdin and decide which classifier response to emit.
+prompt=$(cat)
+if [[ "$prompt" == *"prefer-functional-stub"* ]]; then
+  printf '%s' '{"type":"feedback","title":"Prefer functional patterns","body":"User prefers functional patterns over class-based.\n\n**Why:** Stated explicitly during code review.\n**How to apply:** Default to plain functions and composition.","confidence":0.84}'
+elif [[ "$prompt" == *"compliance-stub"* ]]; then
+  printf '%s' '{"type":"project","title":"Auth rewrite is compliance driven","body":"Auth middleware rewrite is driven by legal/compliance requirements around session token storage.\n\n**Why:** Compliance ask, not tech debt cleanup.\n**How to apply:** Favor compliance posture over ergonomics when scoping.","confidence":0.91}'
+elif [[ "$prompt" == *"low-conf-stub"* ]]; then
+  printf '%s' '{"type":"user","title":"User edits","body":"User edits files.","confidence":0.4}'
+else
+  printf '%s' '{"type":null,"title":"","body":"","confidence":0.2}'
+fi
+STUB
+  chmod +x "${STUB_BIN}/claude"
+  export PATH="${STUB_BIN}:${PATH}"
+
+  HOOK="${PLUGIN_ROOT}/scripts/hooks/librarian-session-end.sh"
+}
+
+# Helper: write an archivist artifact for the project.
+_seed_artifact() {
+  local kind="$1" id="$2" summary="$3" detail="$4" created_at="${5:-2026-06-01T12:00:00Z}"
+  local dir="${ARCHIVIST_DIR}/${kind}"
+  mkdir -p "$dir"
+  jq -n \
+    --arg id "$id" --arg kind "${kind%s}" \
+    --arg project_key "$PROJECT_KEY" \
+    --arg summary "$summary" --arg detail "$detail" \
+    --arg created_at "$created_at" --arg session_id "sess-1" \
+    '{ id: $id, kind: $kind, project_key: $project_key, source: "local",
+       created_at: $created_at, updated_at: $created_at,
+       summary: $summary, detail: $detail, files: [], session_id: $session_id }' \
+    > "${dir}/${id}.json"
+}
+
+_hook_input() {
+  jq -cn --arg cwd "$PROJECT_REPO" --arg sid "sess-end-test" \
+    '{cwd: $cwd, session_id: $sid, hook_event_name: "SessionEnd"}'
+}
+
+@test "session-end is a no-op when librarian is disabled" {
+  rm -f "${PROJECT_REPO}/.claude/settings.json"
+  run bash -c "printf '%s' '$(_hook_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  # No proposals written.
+  [ ! -d "${LIBRARIAN_DIR}/proposals" ] || [ -z "$(ls -A "${LIBRARIAN_DIR}/proposals" 2>/dev/null)" ]
+  # No events emitted.
+  [ ! -f "$ONLOOKER_EVENTS_LOG" ] || ! grep -q 'librarian' "$ONLOOKER_EVENTS_LOG"
+}
+
+@test "session-end emits empty scan when archivist has nothing" {
+  run bash -c "printf '%s' '$(_hook_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+
+  # scan.started fired with artifact_count_in_window = 0.
+  grep -q '"event_type":"librarian.scan.started"' "$ONLOOKER_EVENTS_LOG"
+  grep '"event_type":"librarian.scan.started"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.artifact_count_in_window == 0' >/dev/null
+
+  # scan.complete fired with outcome=empty and zero counts.
+  grep -q '"event_type":"librarian.scan.complete"' "$ONLOOKER_EVENTS_LOG"
+  grep '"event_type":"librarian.scan.complete"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.outcome == "empty" and .payload.candidates_proposed == 0 and .payload.candidates_dropped == 0' >/dev/null
+
+  # Watermark advanced for next scan.
+  [ -f "${LIBRARIAN_DIR}/last_scan.json" ]
+  jq -e '.scanned_at | test("^[0-9]{4}-[0-9]{2}-[0-9]{2}T")' "${LIBRARIAN_DIR}/last_scan.json" >/dev/null
+}
+
+@test "session-end proposes promotion for marker-phrase + classifier success" {
+  # Seed two promotable artifacts and one filter-rejected one.
+  _seed_artifact "decisions" "01PROPOSEEFEEDBACK00000000" \
+    "User prefers functional patterns prefer-functional-stub" \
+    "User explicitly said: always prefer plain functions over classes when adding new code in the api layer."
+
+  _seed_artifact "decisions" "01PROPOSEEPROJECT000000000" \
+    "Compliance-driven auth rewrite compliance-stub" \
+    "The reason for the auth middleware rewrite is legal compliance, not tech debt; remember this when sizing scope."
+
+  _seed_artifact "open_questions" "01FILTERREJECTED000000000" \
+    "ad hoc question" \
+    "this short text contains no marker phrase and should be filtered out before the classifier runs"
+
+  run bash -c "printf '%s' '$(_hook_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+
+  # Two proposals on disk.
+  proposals=("${LIBRARIAN_DIR}/proposals"/*.json)
+  [ "${#proposals[@]}" -eq 2 ]
+
+  # Both carry provenance back to their source artifact.
+  for p in "${proposals[@]}"; do
+    jq -e '.status == "pending" and .conflict_state == "none"' "$p" >/dev/null
+    jq -e '.proposed.type | IN("user", "feedback", "project", "reference")' "$p" >/dev/null
+    jq -e '.proposed.classifier_confidence >= 0.6' "$p" >/dev/null
+    jq -e '(.source_artifact_ids | length) > 0' "$p" >/dev/null
+  done
+
+  # scan.started reported the right window size (2 marker matches + 1 filtered = 3).
+  grep '"event_type":"librarian.scan.started"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.artifact_count_in_window == 3' >/dev/null
+
+  # candidate.proposed fired twice with correct types.
+  proposed_types=$(grep '"event_type":"librarian.candidate.proposed"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -r '.payload.memory_type' | sort | paste -sd, -)
+  [ "$proposed_types" = "feedback,project" ]
+
+  # candidate.dropped fired for the marker-missing artifact.
+  grep '"event_type":"librarian.candidate.dropped"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e 'select(.payload.reason == "filter_marker_missing")' >/dev/null
+
+  # scan.complete with ok outcome and accurate counts.
+  scan_complete=$(grep '"event_type":"librarian.scan.complete"' "$ONLOOKER_EVENTS_LOG")
+  echo "$scan_complete" | jq -e '.payload.outcome == "ok" and .payload.candidates_proposed == 2 and .payload.candidates_dropped >= 1' >/dev/null
+}
+
+@test "session-end drops candidates below confidence floor" {
+  _seed_artifact "decisions" "01LOWCONFCANDIDATE0000000" \
+    "low-conf-stub trigger" \
+    "always prefer some thing because reasons that show a marker phrase but the stub returns low confidence"
+
+  run bash -c "printf '%s' '$(_hook_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+
+  # No proposal written.
+  [ ! -d "${LIBRARIAN_DIR}/proposals" ] || [ -z "$(ls -A "${LIBRARIAN_DIR}/proposals" 2>/dev/null)" ]
+
+  # candidate.dropped fired with low_confidence reason.
+  grep '"event_type":"librarian.candidate.dropped"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e 'select(.payload.reason == "low_confidence")' >/dev/null
+
+  # scan.complete reports empty outcome (zero proposals).
+  grep '"event_type":"librarian.scan.complete"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.outcome == "empty" and .payload.candidates_proposed == 0 and .payload.candidates_dropped >= 1' >/dev/null
+}

package/test/bats/librarian-session-start.bats

@@ -0,0 +1,136 @@
+#!/usr/bin/env bats
+#
+# Tests the librarian SessionStart surfacer. Verifies:
+#   - Disabled config: empty additionalContext, exit 0.
+#   - No git context: empty additionalContext, exit 0.
+#   - Empty proposal queue + skip_inject_when_zero=true: empty context.
+#   - Pending proposals: one-line pointer with the count and pluralization.
+#   - Overflow: counts above max_pending_for_inject render as "<cap>+".
+
+setup() {
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/librarian"
+  export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+  export ONLOOKER_ECOSYSTEM_ROOT="$REPO_ROOT"
+
+  PROJECT_REPO="${BATS_TEST_TMPDIR}/repo"
+  mkdir -p "$PROJECT_REPO"
+  git -C "$PROJECT_REPO" init -q
+  git -C "$PROJECT_REPO" config user.email t@example.com
+  git -C "$PROJECT_REPO" config user.name "Test"
+  git -C "$PROJECT_REPO" remote add origin git@github.com:org/librarian-surfacer-test.git
+
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/librarian-project-key.sh"
+  PROJECT_KEY=$(librarian_project_key "$PROJECT_REPO")
+  [ -n "$PROJECT_KEY" ]
+  LIBRARIAN_DIR="${ONLOOKER_DIR}/librarian/${PROJECT_KEY}"
+
+  mkdir -p "${PROJECT_REPO}/.claude"
+  printf '%s\n' '{"librarian":{"enabled":true}}' > "${PROJECT_REPO}/.claude/settings.json"
+
+  HOOK="${PLUGIN_ROOT}/scripts/hooks/librarian-session-start.sh"
+}
+
+_input() {
+  jq -cn --arg cwd "$PROJECT_REPO" \
+    '{cwd: $cwd, source: "startup", session_id: "sess-start-test"}'
+}
+
+# Helper: drop a proposal file with the given status into the queue.
+_seed_proposal() {
+  local id="$1" status="${2:-pending}"
+  mkdir -p "${LIBRARIAN_DIR}/proposals"
+  jq -n --arg id "$id" --arg status "$status" \
+    '{
+      id: $id,
+      created_at: "2026-06-01T00:00:00Z",
+      source_artifact_ids: [],
+      source_session_ids: [],
+      proposed: { type: "feedback", filename: ($id + ".md"),
+                  title: "t", body: "b", classifier_confidence: 0.8 },
+      conflict_state: "none",
+      conflict_with: [],
+      status: $status
+    }' > "${LIBRARIAN_DIR}/proposals/${id}.json"
+}
+
+@test "surfacer emits empty context when librarian is disabled" {
+  rm -f "${PROJECT_REPO}/.claude/settings.json"
+  _seed_proposal "01PROPOSALA000000000000000"
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  echo "$output" | jq -e '.hookSpecificOutput.additionalContext == ""' >/dev/null
+  echo "$output" | jq -e '.hookSpecificOutput.hookEventName == "SessionStart"' >/dev/null
+}
+
+@test "surfacer emits empty context when there is no git context" {
+  local non_git="${BATS_TEST_TMPDIR}/no-git"
+  mkdir -p "$non_git"
+  local input
+  input=$(jq -cn --arg cwd "$non_git" '{cwd: $cwd, source: "startup", session_id: "s"}')
+
+  run bash -c "printf '%s' '$input' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  echo "$output" | jq -e '.hookSpecificOutput.additionalContext == ""' >/dev/null
+}
+
+@test "surfacer emits empty context when no proposals are pending" {
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  echo "$output" | jq -e '.hookSpecificOutput.additionalContext == ""' >/dev/null
+}
+
+@test "surfacer surfaces one-line pointer when proposals exist (plural)" {
+  _seed_proposal "01PROPOSAL11111111111111A"
+  _seed_proposal "01PROPOSAL11111111111111B"
+  _seed_proposal "01PROPOSAL11111111111111C"
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  local ctx
+  ctx=$(echo "$output" | jq -r '.hookSpecificOutput.additionalContext')
+  [[ "$ctx" == *"Librarian has 3 pending memory promotion proposals"* ]]
+  [[ "$ctx" == *"/librarian review"* ]]
+}
+
+@test "surfacer pluralizes singular vs plural correctly" {
+  _seed_proposal "01PROPOSALSINGULAR0000000"
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  local ctx
+  ctx=$(echo "$output" | jq -r '.hookSpecificOutput.additionalContext')
+  [[ "$ctx" == *"Librarian has 1 pending memory promotion proposal"* ]]
+  [[ "$ctx" != *"proposals."* ]]
+}
+
+@test "surfacer ignores accepted/rejected proposals when counting pending" {
+  _seed_proposal "01PROPOSALACCEPTED000000" "accepted"
+  _seed_proposal "01PROPOSALREJECTED000000" "rejected"
+  _seed_proposal "01PROPOSALPENDING0000000" "pending"
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  local ctx
+  ctx=$(echo "$output" | jq -r '.hookSpecificOutput.additionalContext')
+  [[ "$ctx" == *"1 pending memory promotion proposal"* ]]
+}
+
+@test "surfacer caps display at max_pending_for_inject + '+'" {
+  # Override max to 3 via a project settings overlay.
+  printf '%s\n' '{"librarian":{"enabled":true,"surfacer":{"max_pending_for_inject":3}}}' \
+    > "${PROJECT_REPO}/.claude/settings.json"
+  for i in A B C D E; do
+    _seed_proposal "01PROPOSALCAP$i$i$i$i$i$i$i$i$i$i$i$i"
+  done
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  local ctx
+  ctx=$(echo "$output" | jq -r '.hookSpecificOutput.additionalContext')
+  [[ "$ctx" == *"Librarian has 3+ pending memory promotion proposals"* ]]
+}

package/test/bats/warden-config.bats

@@ -0,0 +1,54 @@
+#!/usr/bin/env bats
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/warden"
+	export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/warden-config.sh"
+}
+
+@test "warden is disabled by default" {
+	warden_config_load ""
+	run warden_config_enabled
+	[ "$status" -ne 0 ]
+}
+
+@test "user-level settings.json can enable warden" {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"warden":{"enabled":true}}' > "${HOME}/.claude/settings.json"
+	warden_config_load ""
+	run warden_config_enabled
+	[ "$status" -eq 0 ]
+}
+
+@test "repo-level settings.json overrides user-level" {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"warden":{"enabled":true}}' > "${HOME}/.claude/settings.json"
+	local repo="${BATS_TEST_TMPDIR}/repo"
+	mkdir -p "${repo}/.claude"
+	printf '%s\n' '{"warden":{"enabled":false}}' > "${repo}/.claude/settings.json"
+	warden_config_load "$repo"
+	run warden_config_enabled
+	[ "$status" -ne 0 ]
+}
+
+@test "defaults are preserved when an overlay sets only some keys" {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"warden":{"enabled":true,"escalation":{"enabled":false}}}' > "${HOME}/.claude/settings.json"
+	warden_config_load ""
+	# escalation.enabled overridden to false…
+	[ "$(warden_config_get '.warden.escalation.enabled')" = "false" ]
+	# …but shipped defaults survive the deep merge.
+	[ "$(warden_config_get '.warden.detection.close_threshold')" = "0.65" ]
+	[ "$(warden_config_get '.warden.scan.max_content_chars')" = "20000" ]
+}
+
+@test "config_get_json returns arrays" {
+	warden_config_load ""
+	run warden_config_get_json '.warden.scan.sources'
+	[ "$status" -eq 0 ]
+	printf '%s' "$output" | jq -e 'index("web_fetch") != null and index("file_read") != null' >/dev/null
+}