@onlooker-community/ecosystem 0.17.0 → 0.19.0

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

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Input sanitization for Warden evaluator-bound content.
+#
+# Applied before any ingested content is interpolated into the escalation
+# evaluator prompt. The content warden scans is, by definition, untrusted —
+# so before it is shown to the evaluator it must be neutralized against a
+# second-order injection (content that tries to talk the evaluator out of
+# flagging it).
+#
+# Exposes:
+#   warden_sanitize <string> <max_chars>   # echoes sanitized, truncated string
+#
+# Sanitization steps (applied in order):
+#   1. Null-byte removal
+#   2. Control-character removal (0x00–0x1F and 0x7F, except \t and \n)
+#   3. Prompt-delimiter stripping (evaluator prompt tag sequences → [STRIPPED])
+#   4. Truncation to max_chars
+
+# Tags that, if present in scanned content, would inject into the evaluator prompt.
+_WARDEN_STRIP_SEQUENCES=(
+	"<source_content>"
+	"</source_content>"
+	"<instructions>"
+	"</instructions>"
+	"<|"
+	"[INST]"
+	"[/INST]"
+	"<<SYS>>"
+	"<</SYS>>"
+)
+
+# Remove null bytes and ASCII control characters except \t (0x09) and \n (0x0A).
+_warden_strip_control_chars() {
+	local input="$1"
+	printf '%s' "$input" \
+		| tr -d '\000-\010\013-\037\177' \
+		2>/dev/null
+}
+
+# Replace all occurrences of a literal string with [STRIPPED].
+#
+# Uses bash native substring replacement rather than sed: the strip sequences
+# contain '/', '[', and '|', any of which would collide with sed's delimiter
+# or regex syntax. Quoting the needle in ${var//"needle"/repl} forces a literal
+# (non-glob) match that is safe for arbitrary bytes.
+_warden_strip_literal() {
+	local input="$1"
+	local needle="$2"
+	printf '%s' "${input//"$needle"/[STRIPPED]}"
+}
+
+# Truncate a string to at most max_chars characters.
+_warden_truncate() {
+	local input="$1"
+	local max_chars="${2:-0}"
+	if [[ "$max_chars" -le 0 ]]; then
+		printf '%s' "$input"
+		return
+	fi
+	printf '%s' "$input" | cut -c "1-${max_chars}" 2>/dev/null
+}
+
+# Full sanitization pipeline. Echoes the sanitized string.
+#   $1 — raw input string
+#   $2 — max chars (0 = no truncation)
+warden_sanitize() {
+	local input="$1"
+	local max_chars="${2:-0}"
+
+	local s
+	s=$(_warden_strip_control_chars "$input")
+
+	local seq
+	for seq in "${_WARDEN_STRIP_SEQUENCES[@]}"; do
+		s=$(_warden_strip_literal "$s" "$seq")
+	done
+
+	s=$(_warden_truncate "$s" "$max_chars")
+	printf '%s' "$s"
+}

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

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

package/test/bats/counsel-project-key.bats

@@ -0,0 +1,82 @@
+#!/usr/bin/env bats
+
+setup() {
+  # shellcheck source=../helpers/setup.bash
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/counsel"
+  export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/counsel-project-key.sh"
+}
+
+@test "non-git directory returns empty key" {
+  local d="${BATS_TEST_TMPDIR}/non-git"
+  mkdir -p "$d"
+  run counsel_project_key "$d"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "git repo without remote falls back to repo-root hash" {
+  local d="${BATS_TEST_TMPDIR}/local-only-repo"
+  mkdir -p "$d"
+  git -C "$d" init -q
+  git -C "$d" config user.email t@example.com
+  git -C "$d" config user.name "Test"
+
+  local k1
+  k1=$(counsel_project_key "$d")
+  [ -n "$k1" ]
+  [ "${#k1}" -eq 12 ]
+
+  local k2
+  k2=$(counsel_project_key "$d")
+  [ "$k1" = "$k2" ]
+}
+
+@test "git repo with remote uses remote hash, ignores local path" {
+  local a="${BATS_TEST_TMPDIR}/clone-a"
+  local b="${BATS_TEST_TMPDIR}/clone-b"
+  mkdir -p "$a" "$b"
+  for d in "$a" "$b"; do
+    git -C "$d" init -q
+    git -C "$d" config user.email t@example.com
+    git -C "$d" config user.name "Test"
+    git -C "$d" remote add origin git@github.com:org/proj.git
+  done
+
+  local ka kb
+  ka=$(counsel_project_key "$a")
+  kb=$(counsel_project_key "$b")
+  [ -n "$ka" ]
+  [ "$ka" = "$kb" ]
+}
+
+@test "different remotes yield different keys" {
+  local a="${BATS_TEST_TMPDIR}/proj-a"
+  local b="${BATS_TEST_TMPDIR}/proj-b"
+  mkdir -p "$a" "$b"
+  for d in "$a" "$b"; do
+    git -C "$d" init -q
+    git -C "$d" config user.email t@example.com
+    git -C "$d" config user.name "Test"
+  done
+  git -C "$a" remote add origin git@github.com:org/proj-a.git
+  git -C "$b" remote add origin git@github.com:org/proj-b.git
+
+  local ka kb
+  ka=$(counsel_project_key "$a")
+  kb=$(counsel_project_key "$b")
+  [ -n "$ka" ]
+  [ -n "$kb" ]
+  [ "$ka" != "$kb" ]
+}
+
+@test "counsel_project_dir includes project key in path" {
+  local key="abc123def456"
+  run counsel_project_dir "$key"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"counsel/${key}/briefs" ]]
+}

package/test/bats/counsel-reader.bats

@@ -0,0 +1,132 @@
+#!/usr/bin/env bats
+
+setup() {
+  # shellcheck source=../helpers/setup.bash
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/counsel"
+  export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/counsel-reader.sh"
+}
+
+# ---------------------------------------------------------------------------
+# counsel_count_events
+# ---------------------------------------------------------------------------
+
+@test "count_events returns 0 for empty input" {
+  run counsel_count_events ""
+  [ "$status" -eq 0 ]
+  [ "$output" = "0" ]
+}
+
+@test "count_events counts non-blank lines" {
+  local text
+  text=$(printf '%s\n%s\n%s\n' '{"type":"a"}' '{"type":"b"}' '{"type":"c"}')
+  run counsel_count_events "$text"
+  [ "$status" -eq 0 ]
+  [ "$output" = "3" ]
+}
+
+# ---------------------------------------------------------------------------
+# counsel_sources_from_events
+# ---------------------------------------------------------------------------
+
+@test "sources_from_events returns onlooker_events for unknown types" {
+  local text='{"type":"scribe.distill.complete"}'
+  run counsel_sources_from_events "$text"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"onlooker_events"* ]]
+}
+
+@test "sources_from_events detects tribunal events" {
+  local text='{"type":"tribunal.gate.blocked"}'
+  run counsel_sources_from_events "$text"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"tribunal_verdicts"* ]]
+}
+
+@test "sources_from_events detects echo events" {
+  local text='{"type":"echo.regression.detected"}'
+  run counsel_sources_from_events "$text"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"echo_regressions"* ]]
+}
+
+@test "sources_from_events returns onlooker_events for empty input" {
+  run counsel_sources_from_events ""
+  [ "$status" -eq 0 ]
+  [ "$output" = '["onlooker_events"]' ]
+}
+
+# ---------------------------------------------------------------------------
+# counsel_read_events — file-based
+# ---------------------------------------------------------------------------
+
+@test "read_events returns empty when log does not exist" {
+  export ONLOOKER_EVENTS_LOG="${BATS_TEST_TMPDIR}/no-log.jsonl"
+  run counsel_read_events "30" "60000"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "read_events returns empty for empty log" {
+  local log="${BATS_TEST_TMPDIR}/empty-log.jsonl"
+  touch "$log"
+  export ONLOOKER_EVENTS_LOG="$log"
+  run counsel_read_events "30" "60000"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "read_events filters events within lookback window" {
+  local log="${BATS_TEST_TMPDIR}/events.jsonl"
+  # Use a timestamp far in the future to ensure it passes any lookback filter.
+  local ts
+  ts=$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) || ts="2099-01-01T00:00:00Z"
+  printf '%s\n' \
+    "{\"event_type\":\"scribe.distill.complete\",\"timestamp\":\"${ts}\",\"session_id\":\"s1\",\"payload\":{}}" \
+    > "$log"
+  export ONLOOKER_EVENTS_LOG="$log"
+  run counsel_read_events "30" "60000"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"scribe.distill.complete"* ]]
+}
+
+@test "read_events output is JSONL-shaped: one object per line" {
+  local log="${BATS_TEST_TMPDIR}/multi-events.jsonl"
+  local ts
+  ts=$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) || ts="2099-01-01T00:00:00Z"
+  printf '%s\n' \
+    "{\"event_type\":\"tribunal.gate.blocked\",\"timestamp\":\"${ts}\",\"session_id\":\"s1\",\"payload\":{}}" \
+    "{\"event_type\":\"echo.regression.detected\",\"timestamp\":\"${ts}\",\"session_id\":\"s2\",\"payload\":{}}" \
+    "{\"event_type\":\"scribe.distill.complete\",\"timestamp\":\"${ts}\",\"session_id\":\"s3\",\"payload\":{}}" \
+    > "$log"
+  export ONLOOKER_EVENTS_LOG="$log"
+
+  local events
+  events=$(counsel_read_events "30" "60000")
+
+  # count_events must see exactly 3 records, not inflated by pretty-printing.
+  run counsel_count_events "$events"
+  [ "$status" -eq 0 ]
+  [ "$output" = "3" ]
+}
+
+@test "read_events output preserves source types for sources_from_events" {
+  local log="${BATS_TEST_TMPDIR}/source-events.jsonl"
+  local ts
+  ts=$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) || ts="2099-01-01T00:00:00Z"
+  printf '%s\n' \
+    "{\"event_type\":\"tribunal.gate.blocked\",\"timestamp\":\"${ts}\",\"session_id\":\"s1\",\"payload\":{}}" \
+    > "$log"
+  export ONLOOKER_EVENTS_LOG="$log"
+
+  local events
+  events=$(counsel_read_events "30" "60000")
+
+  run counsel_sources_from_events "$events"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"tribunal_verdicts"* ]]
+}

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
+}