@onlooker-community/ecosystem 0.18.0 → 0.19.0

package/plugins/warden/scripts/lib/warden-gate-state.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# Session-scoped content gate state for Warden.
+#
+# The gate is a single JSON lock per session under
+#   $ONLOOKER_DIR/warden/sessions/<session_id>/gate.json
+#
+# Absent file or {"state":"open"} → gate open (writes/edits/bash allowed).
+# {"state":"closed", ...} → gate closed (those operations are blocked).
+#
+# The gate is closed by the detection hook on a positive scan and cleared
+# ONLY by the user via the /warden skill (clear_policy: user_override_only).
+#
+# Exposes:
+#   warden_gate_dir <session_id>
+#   warden_gate_file <session_id>
+#   warden_gate_is_closed <session_id>            # return 0 if closed
+#   warden_gate_close <session_id> <threat_json>  # write closed lock
+#   warden_gate_read <session_id>                 # echo gate JSON (empty if open/absent)
+#   warden_gate_threat <session_id>               # echo stored threat object (empty if open)
+#   warden_gate_clear <session_id>                # remove lock; echo prior threat object
+
+warden_gate_dir() {
+	local session_id="$1"
+	local onlooker_dir="${ONLOOKER_DIR:-${HOME}/.onlooker}"
+	printf '%s' "${onlooker_dir}/warden/sessions/${session_id}"
+}
+
+warden_gate_file() {
+	local session_id="$1"
+	printf '%s/gate.json' "$(warden_gate_dir "$session_id")"
+}
+
+warden_gate_is_closed() {
+	local session_id="$1"
+	local file
+	file=$(warden_gate_file "$session_id")
+	[[ -f "$file" ]] || return 1
+	local state
+	state=$(jq -r '.state // "open"' "$file" 2>/dev/null) || return 1
+	[[ "$state" == "closed" ]]
+}
+
+warden_gate_read() {
+	local session_id="$1"
+	local file
+	file=$(warden_gate_file "$session_id")
+	[[ -f "$file" ]] || { printf ''; return 1; }
+	cat "$file" 2>/dev/null
+}
+
+warden_gate_threat() {
+	local session_id="$1"
+	local file
+	file=$(warden_gate_file "$session_id")
+	[[ -f "$file" ]] || { printf ''; return 1; }
+	jq -c '.threat // empty' "$file" 2>/dev/null
+}
+
+# Close the gate. $2 is the threat object (JSON) to record.
+warden_gate_close() {
+	local session_id="$1"
+	local threat_json="${2:-}"
+	[[ -z "$threat_json" ]] && threat_json='{}'
+	local dir file now
+	dir=$(warden_gate_dir "$session_id")
+	file=$(warden_gate_file "$session_id")
+	mkdir -p "$dir" 2>/dev/null || return 1
+	now=$(date +%s 2>/dev/null) || now=0
+	local out
+	out=$(jq -n \
+		--argjson ts "$now" \
+		--argjson threat "$threat_json" \
+		'{state:"closed", closed_at:$ts, threat:$threat}' 2>/dev/null) || return 1
+	printf '%s\n' "$out" > "$file"
+}
+
+# List session ids that currently have a CLOSED gate (one per line). Used by
+# the /warden skill to resolve the active gate when CLAUDE_SESSION_ID is not
+# in the skill environment.
+warden_list_closed_sessions() {
+	local onlooker_dir="${ONLOOKER_DIR:-${HOME}/.onlooker}"
+	local base="${onlooker_dir}/warden/sessions"
+	[[ -d "$base" ]] || return 0
+	local gate sid state
+	for gate in "$base"/*/gate.json; do
+		[[ -f "$gate" ]] || continue
+		state=$(jq -r '.state // "open"' "$gate" 2>/dev/null) || continue
+		[[ "$state" == "closed" ]] || continue
+		sid=$(basename "$(dirname "$gate")")
+		printf '%s\n' "$sid"
+	done
+}
+
+# Clear the gate. Echoes the prior threat object (for the cleared event), then
+# removes the lock. Returns 1 if the gate was not closed.
+warden_gate_clear() {
+	local session_id="$1"
+	local file
+	file=$(warden_gate_file "$session_id")
+	[[ -f "$file" ]] || return 1
+	local prior_threat
+	prior_threat=$(jq -c '.threat // empty' "$file" 2>/dev/null) || prior_threat=""
+	rm -f "$file" 2>/dev/null || return 1
+	printf '%s' "$prior_threat"
+}

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

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Deterministic injection-pattern floor for Warden.
+#
+# Classifies a block of ingested content against a curated set of
+# prompt-injection signatures, mapped to the five schema threat_types:
+#   prompt_injection · instruction_override · credential_exfiltration
+#   command_injection · social_engineering
+#
+# Two severities:
+#   strong — explicit, high-precision phrasing. Closes the gate on its own.
+#   weak   — heuristic suspicion. Below the close threshold; escalates to the
+#            evaluator (when escalation is enabled) rather than closing alone.
+#
+# Exposes:
+#   warden_pattern_classify <content>
+#     → JSON {"severity":"strong|weak|none","threat_type":"<t>",
+#             "matched_pattern":"<regex>","hit_count":<n>}
+#
+# The matched_pattern is retained for the local gate record only — it is NOT
+# emitted in warden.threat.detected (the schema forbids extra fields there).
+
+# Each entry: "threat_type|regex" (extended regex, matched case-insensitively).
+
+_WARDEN_STRONG_PATTERNS=(
+	# instruction_override — explicit attempts to discard the standing prompt.
+	'instruction_override|ignore (all (of )?)?(the )?(previous|prior|above|preceding|earlier) (instructions|prompts|directions|context)'
+	'instruction_override|disregard (all |the |any )?(previous|prior|above|earlier|preceding) (instructions|directions|prompts|rules)'
+	'instruction_override|forget (everything|all (of )?your|all (the )?previous|your (previous )?instructions)'
+	'instruction_override|(override|overrule|bypass) (your|the|all) (instructions|system prompt|guardrails|safety)'
+	'instruction_override|do not (follow|obey|comply with) (the|your|any) (previous|prior|system|earlier) (instructions|prompt)'
+	# prompt_injection — role / system-prompt hijack and delimiter spoofing.
+	'prompt_injection|you are now (a|an|the|in|no longer|free|developer mode)'
+	'prompt_injection|new (instructions|system prompt|directives?)( for you)?:'
+	'prompt_injection|(reveal|print|repeat|disclose|show) (me )?(your|the) (system prompt|initial instructions|hidden instructions)'
+	'prompt_injection|<\/?(system|instructions?|assistant|im_start|im_end)>'
+	'prompt_injection|\[/?INST\]|<<SYS>>|<\|im_(start|end)\|>'
+	# credential_exfiltration — moving secrets out.
+	'credential_exfiltration|(send|post|upload|transmit|exfiltrate|email|leak|forward) .{0,40}(api[ _-]?key|password|secret|token|credential|\.env|private key|ssh key)'
+	'credential_exfiltration|(curl|wget|fetch|http) .{0,80}(api[ _-]?key|token|secret|password|\$\{?[A-Z_]*(KEY|TOKEN|SECRET|PASSWORD))'
+	'credential_exfiltration|(AWS_SECRET_ACCESS_KEY|ANTHROPIC_API_KEY|GITHUB_TOKEN|OPENAI_API_KEY|cat .{0,30}\.env)'
+	# command_injection — get the agent to run attacker-chosen commands.
+	'command_injection|(curl|wget) .{0,120}\| ?(ba)?sh'
+	'command_injection|base64 (--?d|--decode) .{0,80}\| ?(ba)?sh'
+	'command_injection|rm -rf (/|~|\$HOME|\*)'
+	'command_injection|(run|execute|eval) (the following|this) (command|code|script|payload)'
+)
+
+_WARDEN_WEAK_PATTERNS=(
+	# social_engineering — pressure and false authority.
+	'social_engineering|do not (tell|inform|notify|alert) (the )?(user|human|operator)'
+	'social_engineering|without (asking|informing|telling|notifying) (the )?(user|anyone)'
+	'social_engineering|i am (your|the) (developer|administrator|admin|owner|creator|operator)'
+	'social_engineering|as an? (authorized|trusted|admin|administrator|privileged) (user|agent|developer)'
+	'social_engineering|this is (urgent|critical|an emergency|time.?sensitive)'
+	# prompt_injection — softer instruction-shaped imperatives in fetched text.
+	'prompt_injection|(important|attention|note to|message for|hey) (ai|assistant|claude|chatbot|llm|model)'
+	'prompt_injection|(please |kindly )?(now )?(follow|execute|carry out) (these|the following) (instructions|steps|commands)'
+	# command_injection — pipe-to-shell shapes that did not hit the strong rule.
+	'command_injection|(eval|exec|system)\(.{0,60}\)'
+)
+
+# Run one pattern list against the content. Echoes the first matching entry's
+# "threat_type|matched_regex" and returns 0; returns 1 if nothing matches.
+_warden_first_match() {
+	local content="$1"
+	shift
+	local entry threat regex
+	for entry in "$@"; do
+		threat="${entry%%|*}"
+		regex="${entry#*|}"
+		if printf '%s' "$content" | grep -iqE -- "$regex" 2>/dev/null; then
+			printf '%s|%s' "$threat" "$regex"
+			return 0
+		fi
+	done
+	return 1
+}
+
+# Count how many entries in a list match (signal strength for borderline calls).
+_warden_count_matches() {
+	local content="$1"
+	shift
+	local entry regex count=0
+	for entry in "$@"; do
+		regex="${entry#*|}"
+		if printf '%s' "$content" | grep -iqE -- "$regex" 2>/dev/null; then
+			count=$((count + 1))
+		fi
+	done
+	printf '%d' "$count"
+}
+
+# Classify content. Echoes a JSON verdict object.
+warden_pattern_classify() {
+	local content="$1"
+
+	local strong_hit weak_hit
+	strong_hit=$(_warden_first_match "$content" "${_WARDEN_STRONG_PATTERNS[@]}") || strong_hit=""
+
+	if [[ -n "$strong_hit" ]]; then
+		local threat="${strong_hit%%|*}"
+		local regex="${strong_hit#*|}"
+		local n
+		n=$(_warden_count_matches "$content" "${_WARDEN_STRONG_PATTERNS[@]}")
+		jq -n \
+			--arg sev "strong" \
+			--arg t "$threat" \
+			--arg p "$regex" \
+			--argjson n "$n" \
+			'{severity:$sev, threat_type:$t, matched_pattern:$p, hit_count:$n}' 2>/dev/null \
+			|| printf '{"severity":"strong","threat_type":"%s","matched_pattern":"","hit_count":%s}' "$threat" "$n"
+		return 0
+	fi
+
+	weak_hit=$(_warden_first_match "$content" "${_WARDEN_WEAK_PATTERNS[@]}") || weak_hit=""
+	if [[ -n "$weak_hit" ]]; then
+		local threat="${weak_hit%%|*}"
+		local regex="${weak_hit#*|}"
+		local n
+		n=$(_warden_count_matches "$content" "${_WARDEN_WEAK_PATTERNS[@]}")
+		jq -n \
+			--arg sev "weak" \
+			--arg t "$threat" \
+			--arg p "$regex" \
+			--argjson n "$n" \
+			'{severity:$sev, threat_type:$t, matched_pattern:$p, hit_count:$n}' 2>/dev/null \
+			|| printf '{"severity":"weak","threat_type":"%s","matched_pattern":"","hit_count":%s}' "$threat" "$n"
+		return 0
+	fi
+
+	printf '{"severity":"none","threat_type":"none","matched_pattern":"","hit_count":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

@@ -142,6 +142,22 @@
           "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/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
+}