@onlooker-community/ecosystem 0.18.0 → 0.20.0

package/plugins/warden/scripts/hooks/warden-post-tool-use.sh

@@ -0,0 +1,201 @@
+#!/usr/bin/env bash
+# Warden PostToolUse hook — detection path for WebFetch and Read.
+#
+# Fires after content has been ingested. Extracts the returned content,
+# runs the hybrid scanner, and on a positive detection closes the session
+# gate and emits warden.threat.detected.
+#
+# Why PostToolUse and not PreToolUse: the fetched/read content does not exist
+# until the tool runs, and the threat model is what the agent does NEXT with
+# that content. PostToolUse cannot (and need not) block the read itself — the
+# PreToolUse enforcement hook blocks the downstream external action. See
+# docs/adr/001-detect-after-ingest-gate-before-action.md.
+#
+# Hook contract:
+#   - Always exits 0. Never blocks PostToolUse.
+#   - Errors are written to stderr only; stdout is kept clean.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+# shellcheck source=../lib/warden-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/warden-config.sh"
+# shellcheck source=../lib/warden-events.sh
+source "${PLUGIN_ROOT}/scripts/lib/warden-events.sh"
+# shellcheck source=../lib/warden-sanitizer.sh
+source "${PLUGIN_ROOT}/scripts/lib/warden-sanitizer.sh"
+# shellcheck source=../lib/warden-patterns.sh
+source "${PLUGIN_ROOT}/scripts/lib/warden-patterns.sh"
+# shellcheck source=../lib/warden-evaluator.sh
+source "${PLUGIN_ROOT}/scripts/lib/warden-evaluator.sh"
+# shellcheck source=../lib/warden-scanner.sh
+source "${PLUGIN_ROOT}/scripts/lib/warden-scanner.sh"
+# shellcheck source=../lib/warden-gate-state.sh
+source "${PLUGIN_ROOT}/scripts/lib/warden-gate-state.sh"
+# shellcheck source=../lib/warden-ulid.sh
+source "${PLUGIN_ROOT}/scripts/lib/warden-ulid.sh"
+
+INPUT=$(cat)
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null) || TOOL_NAME=""
+
+export _HOOK_SESSION_ID="$SESSION_ID"
+
+_done() { exit 0; }
+
+warden_config_load "$CWD"
+
+if ! warden_config_enabled; then
+	_done
+fi
+
+[[ -z "$SESSION_ID" ]] && _done
+
+# If the gate is already closed, there is nothing more to do — it stays closed
+# until the user clears it. Skip the (potentially paid) scan entirely.
+if warden_gate_is_closed "$SESSION_ID"; then
+	_done
+fi
+
+# ---- Resolve source_type from the tool name. -------------------------
+SOURCE_TYPE=""
+SOURCE_URL=""
+SOURCE_PATH=""
+case "$TOOL_NAME" in
+	WebFetch)
+		SOURCE_TYPE="web_fetch"
+		SOURCE_URL=$(printf '%s' "$INPUT" | jq -r '.tool_input.url // ""' 2>/dev/null) || SOURCE_URL=""
+		;;
+	Read)
+		SOURCE_TYPE="file_read"
+		SOURCE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // ""' 2>/dev/null) || SOURCE_PATH=""
+		;;
+	*)
+		_done
+		;;
+esac
+
+# Honor configured scan.sources.
+SOURCES_JSON=$(warden_config_get_json '.warden.scan.sources') || SOURCES_JSON="[]"
+if ! printf '%s' "$SOURCES_JSON" | jq -e --arg s "$SOURCE_TYPE" 'index($s) != null' >/dev/null 2>&1; then
+	_done
+fi
+
+# ---- skip_globs (file reads only). -----------------------------------
+_matches_skip_glob() {
+	local file_path="$1"
+	local globs_json="$2"
+	[[ -z "$file_path" || -z "$globs_json" ]] && return 1
+	# bash 3.2 (macOS default) has no `mapfile`; collect with a while-read loop.
+	local globs=() glob pattern
+	while IFS= read -r glob; do
+		[[ -n "$glob" ]] && globs+=("$glob")
+	done < <(printf '%s' "$globs_json" | jq -r '.[]' 2>/dev/null)
+	for glob in "${globs[@]}"; do
+		pattern="${glob//\*\*/DOUBLE_STAR}"
+		pattern="${pattern//\*/[^/]*}"
+		pattern="${pattern//DOUBLE_STAR/.*}"
+		if [[ "$file_path" =~ $pattern ]]; then
+			return 0
+		fi
+	done
+	return 1
+}
+
+if [[ -n "$SOURCE_PATH" ]]; then
+	SKIP_GLOBS_JSON=$(warden_config_get_json '.warden.scan.skip_globs') || SKIP_GLOBS_JSON="[]"
+	if _matches_skip_glob "$SOURCE_PATH" "$SKIP_GLOBS_JSON"; then
+		_done
+	fi
+fi
+
+# ---- Extract ingested content from the tool response. ----------------
+MAX_CHARS=$(warden_config_get '.warden.scan.max_content_chars')
+MAX_CHARS="${MAX_CHARS:-20000}"
+
+CONTENT=$(printf '%s' "$INPUT" | jq -r '
+	.tool_response as $r
+	| if   ($r|type) == "string" then $r
+	  elif ($r|type) == "object" then ($r.content // $r.text // $r.output // $r.result // ($r|tostring))
+	  else ($r|tostring) end
+	| if (type == "string") then . else tostring end
+' 2>/dev/null) || CONTENT=""
+
+[[ -z "$CONTENT" ]] && _done
+
+# Cap length before scanning (the scanner caps again before any model call).
+CONTENT="${CONTENT:0:$MAX_CHARS}"
+
+# ---- Run the hybrid scanner. -----------------------------------------
+SCAN=$(warden_scan "$SOURCE_TYPE" "$CONTENT")
+DETECTED=$(printf '%s' "$SCAN" | jq -r '.detected // false' 2>/dev/null) || DETECTED="false"
+
+if [[ "$DETECTED" != "true" ]]; then
+	_done
+fi
+
+THREAT_TYPE=$(printf '%s' "$SCAN" | jq -r '.threat_type // "prompt_injection"' 2>/dev/null) || THREAT_TYPE="prompt_injection"
+CONFIDENCE=$(printf '%s' "$SCAN" | jq -r '.confidence // 0.9' 2>/dev/null) || CONFIDENCE="0.9"
+MATCHED_PATTERN=$(printf '%s' "$SCAN" | jq -r '.matched_pattern // ""' 2>/dev/null) || MATCHED_PATTERN=""
+METHOD=$(printf '%s' "$SCAN" | jq -r '.method // "pattern_strong"' 2>/dev/null) || METHOD="pattern_strong"
+
+# ---- Build a snippet for the local record (config-gated). ------------
+STORE_SNIPPET=$(warden_config_get '.warden.scan.store_snippet')
+STORE_SNIPPET="${STORE_SNIPPET:-true}"
+SNIPPET_MAX=$(warden_config_get '.warden.scan.snippet_max_chars')
+SNIPPET_MAX="${SNIPPET_MAX:-240}"
+SNIPPET=""
+if [[ "$STORE_SNIPPET" == "true" ]]; then
+	SNIPPET=$(warden_sanitize "$CONTENT" "$SNIPPET_MAX")
+fi
+
+THREAT_ID=$(warden_ulid)
+
+# ---- Close the gate with the full local threat record. ---------------
+# (The local record keeps matched_pattern / threat_id / method for forensics;
+#  the emitted event below carries only schema-permitted fields.)
+THREAT_RECORD=$(jq -n \
+	--arg id "$THREAT_ID" \
+	--arg st "$SOURCE_TYPE" \
+	--arg tt "$THREAT_TYPE" \
+	--argjson conf "${CONFIDENCE:-0.9}" \
+	--arg url "$SOURCE_URL" \
+	--arg path "$SOURCE_PATH" \
+	--arg snip "$SNIPPET" \
+	--arg mp "$MATCHED_PATTERN" \
+	--arg method "$METHOD" \
+	'{
+		threat_id:$id, source_type:$st, threat_type:$tt, confidence:$conf,
+		source_url:(if $url == "" then null else $url end),
+		source_path:(if $path == "" then null else $path end),
+		snippet:(if $snip == "" then null else $snip end),
+		matched_pattern:(if $mp == "" then null else $mp end),
+		detection_method:$method
+	}' 2>/dev/null) || THREAT_RECORD="{}"
+
+warden_gate_close "$SESSION_ID" "$THREAT_RECORD" || {
+	printf 'warden-post-tool-use: failed to close gate for session %s\n' "$SESSION_ID" >&2
+	_done
+}
+
+# ---- Emit warden.threat.detected (schema-permitted fields only). -----
+EVENT_PAYLOAD=$(jq -n \
+	--arg st "$SOURCE_TYPE" \
+	--arg tt "$THREAT_TYPE" \
+	--argjson conf "${CONFIDENCE:-0.9}" \
+	--arg url "$SOURCE_URL" \
+	--arg path "$SOURCE_PATH" \
+	--arg snip "$SNIPPET" \
+	'{source_type:$st, threat_type:$tt, confidence:$conf}
+	 + (if $url  != "" then {source_url:$url}   else {} end)
+	 + (if $path != "" then {source_path:$path} else {} end)
+	 + (if $snip != "" then {snippet:$snip}     else {} end)' 2>/dev/null) || EVENT_PAYLOAD=""
+
+[[ -n "$EVENT_PAYLOAD" ]] && warden_emit_event "warden.threat.detected" "$EVENT_PAYLOAD" || true
+
+_done

package/plugins/warden/scripts/hooks/warden-pre-tool-use.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# Warden PreToolUse hook — enforcement path for Write, Edit, MultiEdit, Bash.
+#
+# Tool-agnostic gate check: if this session's content gate is closed, block
+# the operation and tell the user how to clear it. Otherwise allow silently.
+# No LLM call, no parsing — just a lock check, so it is fast and trivially
+# fail-closed (a present lock always blocks).
+#
+# Hook contract (Claude Code PreToolUse protocol):
+#   - Always exits 0.
+#   - To block: write {"decision":"block","reason":"..."} to stdout.
+#   - To allow: write nothing to stdout.
+#   - Errors are written to stderr only.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+# shellcheck source=../lib/warden-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/warden-config.sh"
+# shellcheck source=../lib/warden-events.sh
+source "${PLUGIN_ROOT}/scripts/lib/warden-events.sh"
+# shellcheck source=../lib/warden-gate-state.sh
+source "${PLUGIN_ROOT}/scripts/lib/warden-gate-state.sh"
+
+INPUT=$(cat)
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null) || TOOL_NAME=""
+
+export _HOOK_SESSION_ID="$SESSION_ID"
+
+warden_config_load "$CWD"
+
+if ! warden_config_enabled; then
+	exit 0
+fi
+
+[[ -z "$SESSION_ID" ]] && exit 0
+
+# Gate open → allow silently.
+if ! warden_gate_is_closed "$SESSION_ID"; then
+	exit 0
+fi
+
+# ---- Gate closed → block this operation. -----------------------------
+# Map the tool to the schema's blocked_operation enum.
+case "$TOOL_NAME" in
+	Write)              BLOCKED_OP="tool.file.write" ;;
+	Edit|MultiEdit)     BLOCKED_OP="tool.file.edit" ;;
+	Bash)               BLOCKED_OP="tool.shell.exec" ;;
+	*)                  BLOCKED_OP="tool.file.write" ;;
+esac
+
+THREAT=$(warden_gate_threat "$SESSION_ID") || THREAT=""
+THREAT_SOURCE_TYPE=$(printf '%s' "$THREAT" | jq -r '.source_type // "web_fetch"' 2>/dev/null) || THREAT_SOURCE_TYPE="web_fetch"
+THREAT_TYPE=$(printf '%s' "$THREAT" | jq -r '.threat_type // "prompt_injection"' 2>/dev/null) || THREAT_TYPE="prompt_injection"
+THREAT_SOURCE=$(printf '%s' "$THREAT" | jq -r '.source_url // .source_path // "(unknown source)"' 2>/dev/null) || THREAT_SOURCE="(unknown source)"
+THREAT_SNIPPET=$(printf '%s' "$THREAT" | jq -r '.snippet // ""' 2>/dev/null) || THREAT_SNIPPET=""
+
+# Emit warden.gate.blocked (schema-permitted fields only).
+EVENT_PAYLOAD=$(jq -n \
+	--arg op "$BLOCKED_OP" \
+	--arg st "$THREAT_SOURCE_TYPE" \
+	'{blocked_operation:$op, threat_source_type:$st}' 2>/dev/null) || EVENT_PAYLOAD=""
+[[ -n "$EVENT_PAYLOAD" ]] && warden_emit_event "warden.gate.blocked" "$EVENT_PAYLOAD" || true
+
+# Build the block message.
+SNIPPET_LINE=""
+[[ -n "$THREAT_SNIPPET" ]] && SNIPPET_LINE=$(printf '\n  Flagged excerpt: %s' "$THREAT_SNIPPET")
+
+MESSAGE=$(printf \
+'Warden closed the content gate — external actions are paused.
+
+A %s threat was detected in untrusted content from %s (%s).
+Under the Agents Rule of Two, warden has revoked the "external actions"
+property while that content is in your context: Write, Edit, and Bash are
+blocked until you clear the gate.%s
+
+To proceed:
+  • Review the flagged source, then run  /warden clear  to reopen the gate.
+  • Run  /warden status  to see the full threat record.
+  • If this was a false positive, /warden clear records your override.' \
+	"$THREAT_TYPE" "$THREAT_SOURCE" "$THREAT_SOURCE_TYPE" "$SNIPPET_LINE")
+
+jq -n \
+	--arg message "$MESSAGE" \
+	'{"decision":"block","reason":$message}' 2>/dev/null \
+	|| printf '{"decision":"block","reason":"Warden closed the content gate. Run /warden clear to reopen."}'
+
+exit 0

package/plugins/warden/scripts/hooks/warden-session-start.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Warden SessionStart hook.
+#
+# Fires at every session start. Responsibilities:
+#   1. Skip silently when warden.enabled is false.
+#   2. Ensure the session gate directory exists.
+#
+# A new session starts with the gate OPEN — the gate is session-scoped because
+# the threat model is untrusted content ingested into THIS session's context.
+# We never carry a closed gate across sessions, and we never auto-create a
+# closed lock here.
+#
+# Hook contract:
+#   - Always exits 0. Never blocks SessionStart.
+#   - Errors are written to stderr only; stdout is kept clean.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+# shellcheck source=../lib/warden-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/warden-config.sh"
+# shellcheck source=../lib/warden-gate-state.sh
+source "${PLUGIN_ROOT}/scripts/lib/warden-gate-state.sh"
+
+INPUT=$(cat)
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+
+_done() { exit 0; }
+
+warden_config_load "$CWD"
+
+if ! warden_config_enabled; then
+	_done
+fi
+
+[[ -z "$SESSION_ID" ]] && {
+	printf 'warden-session-start: no session_id in hook input\n' >&2
+	_done
+}
+
+GATE_DIR=$(warden_gate_dir "$SESSION_ID")
+mkdir -p "$GATE_DIR" 2>/dev/null || {
+	printf 'warden-session-start: failed to create gate dir %s\n' "$GATE_DIR" >&2
+	_done
+}
+
+_done

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

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# Interactive control surface for the /warden skill.
+#
+# Exposes:
+#   warden_cli status [session_id]   # print the gate state + threat record
+#   warden_cli clear  [session_id]   # explicit user override: reopen the gate
+#
+# Session resolution order:
+#   1. explicit session_id argument
+#   2. $CLAUDE_SESSION_ID (when its gate is closed)
+#   3. the single closed gate, if exactly one exists
+#   4. otherwise: report ambiguity / no closed gate and do nothing
+#
+# Depends on (sourced by the caller): warden-gate-state.sh · warden-events.sh
+
+# Resolve the session whose gate the command should act on.
+# Echoes the session id, or empty. Second arg "require_closed" (default true)
+# restricts auto-resolution to sessions with a closed gate.
+_warden_cli_resolve_session() {
+	local explicit="${1:-}"
+
+	if [[ -n "$explicit" ]]; then
+		printf '%s' "$explicit"
+		return 0
+	fi
+
+	if [[ -n "${CLAUDE_SESSION_ID:-}" ]] && warden_gate_is_closed "$CLAUDE_SESSION_ID"; then
+		printf '%s' "$CLAUDE_SESSION_ID"
+		return 0
+	fi
+
+	# bash 3.2 (macOS default) has no `mapfile`; collect with a while-read loop.
+	local closed=() line
+	while IFS= read -r line; do
+		[[ -n "$line" ]] && closed+=("$line")
+	done < <(warden_list_closed_sessions)
+	if [[ "${#closed[@]}" -eq 1 ]]; then
+		printf '%s' "${closed[0]}"
+		return 0
+	fi
+
+	# Fall back to the current session id even if its gate is open, so status
+	# can report "open" for the right session.
+	if [[ -n "${CLAUDE_SESSION_ID:-}" ]]; then
+		printf '%s' "$CLAUDE_SESSION_ID"
+		return 0
+	fi
+
+	printf ''
+	return 1
+}
+
+warden_cli() {
+	local action="${1:-status}"
+	local session_arg="${2:-}"
+
+	local session_id
+	session_id=$(_warden_cli_resolve_session "$session_arg") || session_id=""
+
+	# Report ambiguity when multiple gates are closed and none was specified.
+	if [[ -z "$session_id" ]]; then
+		local closed=() line
+		while IFS= read -r line; do
+			[[ -n "$line" ]] && closed+=("$line")
+		done < <(warden_list_closed_sessions)
+		if [[ "${#closed[@]}" -gt 1 ]]; then
+			printf 'Multiple sessions have a closed gate. Re-run with an explicit session id:\n'
+			printf '  %s\n' "${closed[@]}"
+			return 0
+		fi
+		printf 'No closed gate found and no session id available.\n'
+		return 0
+	fi
+
+	case "$action" in
+		status)
+			if warden_gate_is_closed "$session_id"; then
+				local threat
+				threat=$(warden_gate_threat "$session_id")
+				printf 'Gate: CLOSED (session %s)\n\n' "$session_id"
+				printf '%s\n' "$threat" | jq -r '
+					"  threat_type:     \(.threat_type // "unknown")",
+					"  source_type:     \(.source_type // "unknown")",
+					"  source:          \(.source_url // .source_path // "(unknown)")",
+					"  confidence:      \(.confidence // "n/a")",
+					"  detection:       \(.detection_method // "unknown")",
+					"  matched_pattern: \(.matched_pattern // "n/a")",
+					"  snippet:         \(.snippet // "(not stored)")"
+				' 2>/dev/null || printf '  (threat record unavailable)\n'
+				printf '\nRun  /warden clear  to reopen the gate (records a user override).\n'
+			else
+				printf 'Gate: OPEN (session %s) — no active threat. Write, Edit, and Bash are allowed.\n' "$session_id"
+			fi
+			;;
+		clear)
+			if ! warden_gate_is_closed "$session_id"; then
+				printf 'Gate already OPEN (session %s) — nothing to clear.\n' "$session_id"
+				return 0
+			fi
+			local prior_threat source_type
+			prior_threat=$(warden_gate_threat "$session_id")
+			source_type=$(printf '%s' "$prior_threat" | jq -r '.source_type // "web_fetch"' 2>/dev/null) || source_type="web_fetch"
+
+			warden_gate_clear "$session_id" >/dev/null || {
+				printf 'Failed to clear the gate for session %s.\n' "$session_id"
+				return 1
+			}
+
+			# Emit warden.threat.cleared (schema-permitted fields only).
+			local payload
+			payload=$(jq -n --arg st "$source_type" \
+				'{source_type:$st, cleared_by:"user_override"}' 2>/dev/null) || payload=""
+			if [[ -n "$payload" ]]; then
+				_HOOK_SESSION_ID="$session_id" warden_emit_event "warden.threat.cleared" "$payload" || true
+			fi
+
+			printf 'Gate CLEARED (session %s). External actions re-enabled by user override.\n' "$session_id"
+			;;
+		*)
+			printf 'Unknown action "%s". Use: status | clear\n' "$action"
+			return 1
+			;;
+	esac
+}

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

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# Config resolution for Warden.
+#
+# Reads three layers, latest wins:
+#   1. plugins/warden/config.json (defaults shipped with the plugin)
+#   2. ~/.claude/settings.json
+#   3. <repo>/.claude/settings.json
+#
+# Exposes:
+#   warden_config_load <repo_root>     # populates _WARDEN_CONFIG (JSON)
+#   warden_config_get <jq-path>        # echoes string value (empty if unset)
+#   warden_config_get_json <jq-path>   # echoes JSON value (null if unset)
+#   warden_config_enabled              # 0 if warden.enabled is true
+
+_WARDEN_CONFIG="{}"
+
+warden_config_load() {
+	local repo_root="${1:-}"
+	local plugin_root="${CLAUDE_PLUGIN_ROOT:-}"
+	local home_dir="${HOME:-}"
+
+	local merged="{}"
+	local file
+
+	file="${plugin_root}/config.json"
+	if [[ -f "$file" ]]; then
+		local defaults
+		defaults=$(jq '.' "$file" 2>/dev/null) || defaults="{}"
+		merged=$(jq -n --argjson a "$merged" --argjson b "$defaults" '$a * $b' 2>/dev/null) \
+			|| merged="$defaults"
+	fi
+
+	local repo_settings=""
+	[[ -n "$repo_root" ]] && repo_settings="${repo_root}/.claude/settings.json"
+
+	for file in "${home_dir}/.claude/settings.json" "$repo_settings"; do
+		[[ -n "$file" && -f "$file" ]] || continue
+		local overlay
+		overlay=$(jq '{ warden: (.warden // {}) }' "$file" 2>/dev/null) || continue
+		[[ -z "$overlay" ]] && continue
+		local attempt
+		if attempt=$(jq -n --argjson a "$merged" --argjson b "$overlay" '
+			def deepmerge($a; $b):
+				if ($a|type) == "object" and ($b|type) == "object" then
+					reduce (($a|keys) + ($b|keys) | unique)[] as $k
+						({}; .[$k] = deepmerge($a[$k]; $b[$k]))
+				elif $b == null then $a
+				else $b end;
+			deepmerge($a; $b)
+		' 2>/dev/null) && [[ -n "$attempt" ]]; then
+			merged="$attempt"
+		fi
+	done
+
+	_WARDEN_CONFIG="$merged"
+}
+
+warden_config_get() {
+	local path="$1"
+	# NB: do NOT use `${path} // empty` — jq's `//` treats `false` and `0` as
+	# empty, so a `false` boolean would read back as "" and a `${v:-true}`
+	# default would silently flip it to true. Emit the raw value and map only a
+	# literal JSON null to the empty string.
+	local v
+	v=$(printf '%s' "$_WARDEN_CONFIG" | jq -r "${path}" 2>/dev/null) || return 1
+	[[ "$v" == "null" ]] && v=""
+	printf '%s' "$v"
+}
+
+warden_config_get_json() {
+	local path="$1"
+	printf '%s' "$_WARDEN_CONFIG" | jq -c "${path}" 2>/dev/null
+}
+
+warden_config_enabled() {
+	local v
+	v=$(warden_config_get '.warden.enabled')
+	[[ "$v" == "true" ]]
+}