@onlooker-community/ecosystem 0.15.2 → 0.16.0

package/plugins/governor/scripts/hooks/governor-stop.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# Governor Stop hook.
+#
+# Fires at session end. Emits governor.session.complete with cumulative
+# spend totals from the JSONL ledger.
+#
+# Hook contract:
+#   - Always exits 0. Never blocks Stop.
+#   - Skips silently when governor.enabled is false.
+#   - Errors from ledger reads are swallowed; emits best-effort totals.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+_ECOSYSTEM_ROOT="${ONLOOKER_ECOSYSTEM_ROOT:-}"
+if [[ -z "$_ECOSYSTEM_ROOT" ]]; then
+	_candidate="$(cd "${PLUGIN_ROOT}/../.." 2>/dev/null && pwd)"
+	if [[ -f "${_candidate}/scripts/lib/validate-path.sh" ]]; then
+		_ECOSYSTEM_ROOT="$_candidate"
+	fi
+fi
+
+if [[ -n "$_ECOSYSTEM_ROOT" && -f "${_ECOSYSTEM_ROOT}/scripts/lib/validate-path.sh" ]]; then
+	# shellcheck disable=SC1091
+	CLAUDE_PLUGIN_ROOT="$_ECOSYSTEM_ROOT" source "${_ECOSYSTEM_ROOT}/scripts/lib/validate-path.sh"
+	# shellcheck disable=SC1091
+	CLAUDE_PLUGIN_ROOT="$_ECOSYSTEM_ROOT" source "${_ECOSYSTEM_ROOT}/scripts/lib/portable-lock.sh"
+fi
+
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+# shellcheck source=../lib/governor-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/governor-config.sh"
+# shellcheck source=../lib/governor-events.sh
+source "${PLUGIN_ROOT}/scripts/lib/governor-events.sh"
+# shellcheck source=../lib/governor-ledger.sh
+source "${PLUGIN_ROOT}/scripts/lib/governor-ledger.sh"
+
+_done() { exit 0; }
+
+INPUT=$(cat)
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+[[ -z "$SESSION_ID" ]] && SESSION_ID="${CLAUDE_SESSION_ID:-unknown}"
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+
+governor_config_load "$CWD"
+
+if ! governor_config_enabled; then
+	_done
+fi
+
+# -----------------------------------------------------------------------
+# Read session totals from the ledger.
+# -----------------------------------------------------------------------
+TOTAL_TOKENS=$(governor_ledger_total_tokens "$SESSION_ID")
+TOTAL_COST=$(governor_ledger_total_cost "$SESSION_ID")
+TOTAL_CALLS=$(governor_ledger_call_count "$SESSION_ID")
+LEDGER_POISONED=$(governor_ledger_is_poisoned "$SESSION_ID" && printf 'true' || printf 'false')
+
+TOKENS_BUDGET=$(governor_config_get '.governor.session.tokens_default')
+TOKENS_BUDGET="${TOKENS_BUDGET:-100000}"
+COST_BUDGET=$(governor_config_get '.governor.session.cost_usd_default')
+COST_BUDGET="${COST_BUDGET:-1.0}"
+
+if [[ -n "${ONLOOKER_SESSION_BUDGET_TOKENS:-}" ]]; then
+	TOKENS_BUDGET="$ONLOOKER_SESSION_BUDGET_TOKENS"
+fi
+
+UNDER_BUDGET="true"
+TOTAL_TOKENS_INT=$(printf '%s' "${TOTAL_TOKENS:-0}" | grep -oE '^[0-9]+' || printf '0')
+TOKENS_BUDGET_INT=$(printf '%s' "${TOKENS_BUDGET:-0}" | grep -oE '^[0-9]+' || printf '0')
+(( TOTAL_TOKENS_INT > TOKENS_BUDGET_INT )) && UNDER_BUDGET="false"
+
+# Also check the cost dimension (float comparison via awk).
+if [[ "$UNDER_BUDGET" == "true" ]]; then
+	COST_OVER=$(awk "BEGIN { print (${TOTAL_COST:-0} > ${COST_BUDGET:-1.0}) ? 1 : 0 }" 2>/dev/null) || COST_OVER=0
+	[[ "$COST_OVER" == "1" ]] && UNDER_BUDGET="false"
+fi
+
+SESSION_PAYLOAD=$(jq -n \
+	--argjson total_cost "${TOTAL_COST:-0}" \
+	--argjson budget_usd "${COST_BUDGET:-1.0}" \
+	--argjson under "$( [[ "$UNDER_BUDGET" == "true" ]] && printf 'true' || printf 'false')" \
+	--arg sid "$SESSION_ID" \
+	--argjson total_tokens "${TOTAL_TOKENS_INT:-0}" \
+	--argjson total_calls "${TOTAL_CALLS:-0}" \
+	--argjson dur 0 \
+	--argjson calls_blocked 0 \
+	--argjson calls_warned 0 \
+	--argjson poisoned "$( [[ "$LEDGER_POISONED" == "true" ]] && printf 'true' || printf 'false')" \
+	'{
+		total_cost_usd: $total_cost,
+		budget_usd: $budget_usd,
+		under_budget: $under,
+		session_id: $sid,
+		total_tokens: $total_tokens,
+		total_api_calls: $total_calls,
+		duration_ms: $dur,
+		calls_blocked: $calls_blocked,
+		calls_warned: $calls_warned,
+		ledger_poisoned: $poisoned
+	}' 2>/dev/null) || SESSION_PAYLOAD="{}"
+
+governor_emit_event "governor.session.complete" "$SESSION_PAYLOAD" || true
+
+_done

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

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# Config resolution for Governor.
+#
+# Reads three layers, latest wins:
+#   1. plugins/governor/config.json (defaults shipped with the plugin)
+#   2. ~/.claude/settings.json
+#   3. <repo>/.claude/settings.json
+#
+# Exposes:
+#   governor_config_load <repo_root>     # populates _GOVERNOR_CONFIG (JSON)
+#   governor_config_get <jq-path>        # echoes string value (empty if unset)
+#   governor_config_get_json <jq-path>   # echoes JSON value (null if unset)
+#   governor_config_enabled              # 0 if governor.enabled is true
+#   governor_config_enforcement          # echoes "soft" or "hard"
+
+_GOVERNOR_CONFIG="{}"
+
+governor_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 '{ governor: (.governor // {}) }' "$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
+
+	_GOVERNOR_CONFIG="$merged"
+}
+
+governor_config_get() {
+	local path="$1"
+	printf '%s' "$_GOVERNOR_CONFIG" | jq -r "${path} // empty" 2>/dev/null
+}
+
+governor_config_get_json() {
+	local path="$1"
+	printf '%s' "$_GOVERNOR_CONFIG" | jq -c "${path}" 2>/dev/null
+}
+
+governor_config_enabled() {
+	local v
+	v=$(governor_config_get '.governor.enabled')
+	[[ "$v" == "true" ]]
+}
+
+governor_config_enforcement() {
+	local v
+	v=$(governor_config_get '.governor.enforcement')
+	printf '%s' "${v:-soft}"
+}

package/plugins/governor/scripts/lib/governor-estimate.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# Token estimation for the governor pre-call gate.
+#
+# Uses a tier-table approach: estimate from tool input JSON size with a
+# per-content-type characters-per-token ratio, then multiply by a
+# configurable safety margin.
+#
+# Tier table (characters per token):
+#   ASCII prose      4.0
+#   code / JSON      3.0
+#   mixed            2.5
+#   non-Latin        1.5
+#
+# Safety margin (config: governor.estimation.safety_margin, default 1.3)
+# is applied before the gate check. Hard stop margin
+# (governor.estimation.hard_stop_margin, default 1.5) is the threshold
+# for a blocking decision regardless of enforcement mode.
+#
+# Estimation method tag emitted in governor.gate.checked: "tier_table"
+#
+# Exposes:
+#   governor_estimate_tokens <json_input>   # echoes integer estimate
+#   governor_estimate_cost <tokens> <model> # echoes float USD estimate
+#   governor_estimate_method                # echoes "tier_table"
+
+governor_estimate_method() {
+	printf 'tier_table'
+}
+
+# Detect content tier from a sample of text.
+# Returns one of: ascii_prose code_json mixed non_latin
+_governor_detect_tier() {
+	local sample="${1:-}"
+	local len=${#sample}
+	[[ $len -eq 0 ]] && { printf 'ascii_prose'; return 0; }
+
+	# Check for structural characters that signal code/JSON
+	local struct_count
+	struct_count=$(printf '%s' "$sample" | tr -cd '{}[]():;=><' | wc -c 2>/dev/null) \
+		|| struct_count=0
+	struct_count=$(printf '%s' "$struct_count" | tr -d ' ')
+
+	# >= 10% structural → code/JSON
+	if (( struct_count * 10 >= len )); then
+		printf 'code_json'
+		return 0
+	fi
+
+	# Non-ASCII byte presence signals non-Latin
+	local ascii_count
+	ascii_count=$(printf '%s' "$sample" | tr -cd '[:print:][:space:]' | wc -c 2>/dev/null) \
+		|| ascii_count=$len
+	ascii_count=$(printf '%s' "$ascii_count" | tr -d ' ')
+
+	if (( ascii_count * 10 < len * 7 )); then
+		printf 'non_latin'
+		return 0
+	fi
+
+	# 5–9% structural → mixed (prose with embedded code/JSON)
+	if (( struct_count * 20 >= len )); then
+		printf 'mixed'
+		return 0
+	fi
+
+	printf 'ascii_prose'
+}
+
+# Estimate token count from a JSON input string.
+# Usage: tokens=$(governor_estimate_tokens "$json_input")
+governor_estimate_tokens() {
+	local json_input="${1:-}"
+	local safety_margin="${2:-}"
+
+	[[ -z "$safety_margin" ]] && {
+		safety_margin=$(governor_config_get '.governor.estimation.safety_margin' 2>/dev/null)
+		safety_margin="${safety_margin:-1.3}"
+	}
+
+	local char_count=${#json_input}
+	[[ $char_count -eq 0 ]] && { printf '100'; return 0; }
+
+	local sample="${json_input:0:2000}"
+	local tier
+	tier=$(_governor_detect_tier "$sample")
+
+	local chars_per_token
+	case "$tier" in
+		code_json)  chars_per_token="3.0" ;;
+		mixed)      chars_per_token="2.5" ;;
+		non_latin)  chars_per_token="1.5" ;;
+		*)          chars_per_token="4.0" ;;
+	esac
+
+	# Single awk pass for fractional chars_per_token and safety margin
+	local tokens
+	tokens=$(awk "BEGIN { printf \"%d\", int($char_count / $chars_per_token * $safety_margin + 0.999) }" 2>/dev/null) \
+		|| tokens=$(( char_count * 2 ))
+	(( tokens < 1 )) && tokens=1
+
+	printf '%s' "$tokens"
+}
+
+# Rough USD cost estimate from token count.
+# Uses Sonnet-class pricing as a conservative default (~$3/M input, $15/M output).
+# governor is not aware of the actual model being spawned, so this is a
+# planning-time upper bound.
+#
+# Usage: cost=$(governor_estimate_cost 5000)
+governor_estimate_cost() {
+	local tokens="${1:-0}"
+
+	# $3 per 1M input + $15 per 1M output; assume 50/50 split → ~$9/M blended
+	awk "BEGIN { printf \"%.6f\", ($tokens / 1000000.0) * 9.0 }" 2>/dev/null \
+		|| printf '0.0'
+}

package/plugins/governor/scripts/lib/governor-events.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# Canonical governor.* event emission.
+#
+# Thin wrapper around the ecosystem plugin's onlooker-event.mjs `emit` mode.
+# Every emission is validated against @onlooker-community/schema v2.4.0+
+# before being appended to ~/.onlooker/logs/onlooker-events.jsonl.
+#
+# Usage:
+#   governor_emit_event "governor.gate.checked" '{"session_id":"...","decision":"allow",...}'
+
+_GOVERNOR_PLUGIN_NAME="governor"
+
+_governor_event_js_path() {
+	if [[ -n "${_ONLOOKER_EVENT_JS:-}" && -f "$_ONLOOKER_EVENT_JS" ]]; then
+		printf '%s' "$_ONLOOKER_EVENT_JS"
+		return 0
+	fi
+	local plugin_root="${CLAUDE_PLUGIN_ROOT:-}"
+	local candidates=(
+		"${plugin_root}/scripts/lib/onlooker-event.mjs"
+		"${plugin_root}/../../scripts/lib/onlooker-event.mjs"
+	)
+	local c
+	for c in "${candidates[@]}"; do
+		[[ -f "$c" ]] && { printf '%s' "$c"; return 0; }
+	done
+	return 1
+}
+
+_governor_session_id() {
+	if [[ -n "${_HOOK_SESSION_ID:-}" ]]; then
+		printf '%s' "$_HOOK_SESSION_ID"
+		return 0
+	fi
+	if [[ -n "${CLAUDE_SESSION_ID:-}" ]]; then
+		printf '%s' "$CLAUDE_SESSION_ID"
+		return 0
+	fi
+	printf 'unknown'
+}
+
+# Emit a single governor.* event. Returns 0 on success, non-zero on failure.
+governor_emit_event() {
+	local event_type="${1:-}"
+	local payload="${2:-}"
+
+	[[ -z "$event_type" || -z "$payload" ]] && return 1
+
+	local event_js
+	event_js=$(_governor_event_js_path) || return 1
+
+	local session_id
+	session_id=$(_governor_session_id)
+
+	local params
+	params=$(jq -n \
+		--arg plugin "$_GOVERNOR_PLUGIN_NAME" \
+		--arg sid "$session_id" \
+		--arg type "$event_type" \
+		--argjson payload "$payload" \
+		'{plugin: $plugin, session_id: $sid, event_type: $type, payload: $payload}' \
+		2>/dev/null) || return 1
+
+	local event
+	local stderr_file
+	stderr_file=$(mktemp -t governor-event-err.XXXXXX 2>/dev/null) || stderr_file="/tmp/governor-event-err.$$"
+	event=$(printf '%s' "$params" \
+		| ONLOOKER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}" \
+		  ONLOOKER_PLUGIN_NAME="$_GOVERNOR_PLUGIN_NAME" \
+		  node "$event_js" emit 2>"$stderr_file") || {
+		printf 'governor_emit_event: schema validation failed for %s\n' "$event_type" >&2
+		[[ -s "$stderr_file" ]] && cat "$stderr_file" >&2
+		rm -f "$stderr_file"
+		return 1
+	}
+	rm -f "$stderr_file"
+
+	local log_path="${ONLOOKER_EVENTS_LOG:-${ONLOOKER_DIR:-$HOME/.onlooker}/logs/onlooker-events.jsonl}"
+	mkdir -p "$(dirname "$log_path")" 2>/dev/null || return 1
+	printf '%s\n' "$event" >> "$log_path"
+}

package/plugins/governor/scripts/lib/governor-ledger.sh

@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+# JSONL ledger read/write for the governor plugin.
+#
+# Two-phase accounting model:
+#
+#   1. PreToolUse (gate): writes a "reservation" record inside the gate
+#      lock with estimated_tokens > 0. This ensures concurrent spawns
+#      each see the others' in-flight cost before deciding to allow.
+#
+#   2. PostToolUse (completion): writes a "Task" record with
+#      estimated_tokens = -(original estimate) to cancel the reservation,
+#      plus actual_tokens = observed count (if available). Net effect:
+#
+#        in-flight:  estimated_tokens(reservation) = N_est
+#        completed:  estimated_tokens(Task) = -N_est, actual_tokens = N_act
+#        total:      N_est + (-N_est) + N_act = N_act  ✓
+#
+# governor_ledger_total_tokens sums (.estimated_tokens + .actual_tokens)
+# across all records so the running total is always:
+#   (in-flight reservation estimates) + (completed actuals)
+#
+# Requires portable-lock.sh to be sourced beforehand.
+
+GOVERNOR_LEDGER_MAX_RETRIES=3
+GOVERNOR_LEDGER_LOCK_TIMEOUT=5
+
+governor_ledger_path() {
+	local session_id="${1:-unknown}"
+	local dir="${ONLOOKER_DIR:-${HOME}/.onlooker}/governance/ledgers"
+	local safe_id
+	safe_id=$(printf '%s' "$session_id" | tr -c 'a-zA-Z0-9-' '_')
+	printf '%s/%s.jsonl' "$dir" "$safe_id"
+}
+
+governor_ledger_poison_path() {
+	local ledger_path="${1:-}"
+	printf '%s.poisoned' "$ledger_path"
+}
+
+governor_ledger_is_poisoned() {
+	local session_id="${1:-}"
+	local ledger_path
+	ledger_path=$(governor_ledger_path "$session_id")
+	[[ -f "$(governor_ledger_poison_path "$ledger_path")" ]]
+}
+
+# Append a record to the ledger under the ledger's own write lock.
+# Safe to call from PostToolUse and other hooks that do not already hold
+# the gate lock. For writing inside the gate lock use governor_ledger_write_direct.
+#
+# Usage: governor_ledger_append "$session_id" "$record_json"
+governor_ledger_append() {
+	local session_id="${1:-}"
+	local record="${2:-}"
+
+	[[ -z "$session_id" || -z "$record" ]] && return 1
+
+	local ledger_path
+	ledger_path=$(governor_ledger_path "$session_id")
+	local lock_path="${ledger_path}.lock"
+
+	mkdir -p "$(dirname "$ledger_path")" 2>/dev/null || return 1
+
+	local attempt=0
+	local unrecorded_tokens=0
+	unrecorded_tokens=$(printf '%s' "$record" | jq -r '.estimated_tokens // 0' 2>/dev/null) \
+		|| unrecorded_tokens=0
+
+	while (( attempt < GOVERNOR_LEDGER_MAX_RETRIES )); do
+		if lock_acquire "$lock_path" "$GOVERNOR_LEDGER_LOCK_TIMEOUT"; then
+			printf '%s\n' "$(printf '%s' "$record" | jq -c . 2>/dev/null)" >> "$ledger_path" 2>/dev/null
+			local write_ok=$?
+			lock_release "$lock_path"
+			if (( write_ok == 0 )); then
+				return 0
+			fi
+		fi
+		attempt=$(( attempt + 1 ))
+	done
+
+	_governor_ledger_poison "$session_id" "$ledger_path" "$unrecorded_tokens"
+	return 1
+}
+
+# Write a record directly to the ledger file without acquiring the write
+# lock. ONLY call this when you already hold the gate lock, which serializes
+# access. The gate lock is the same as the write lock (same .lock path), so
+# re-acquiring it here would deadlock.
+#
+# Usage: governor_ledger_write_direct "$ledger_path" "$record_json"
+governor_ledger_write_direct() {
+	local ledger_path="${1:-}"
+	local record="${2:-}"
+
+	[[ -z "$ledger_path" || -z "$record" ]] && return 1
+
+	mkdir -p "$(dirname "$ledger_path")" 2>/dev/null || return 1
+	printf '%s\n' "$(printf '%s' "$record" | jq -c . 2>/dev/null)" >> "$ledger_path" 2>/dev/null
+}
+
+_governor_ledger_poison() {
+	local session_id="${1:-}"
+	local ledger_path="${2:-}"
+	local unrecorded_tokens="${3:-0}"
+
+	touch "$(governor_ledger_poison_path "$ledger_path")" 2>/dev/null || true
+
+	local poison_payload
+	poison_payload=$(jq -n \
+		--arg sid "$session_id" \
+		--arg aid "${CLAUDE_SESSION_ID:-unknown}" \
+		--arg err "write failed after ${GOVERNOR_LEDGER_MAX_RETRIES} attempts" \
+		--argjson retries "$GOVERNOR_LEDGER_MAX_RETRIES" \
+		--argjson tok "$unrecorded_tokens" \
+		'{
+			session_id: $sid,
+			agent_id: $aid,
+			error: $err,
+			retry_count: $retries,
+			ledger_poisoned: true,
+			unrecorded_tokens: $tok
+		}' 2>/dev/null) || poison_payload="{}"
+
+	governor_emit_event "governor.ledger.write_failed" "$poison_payload" || true
+}
+
+# Running total of tokens for a session.
+#
+# Uses the two-phase model: each record contributes
+#   .estimated_tokens + (.actual_tokens // 0)
+#
+# In-flight reservations:  estimated_tokens > 0, no actual_tokens → counts N_est
+# Completed Task records:  estimated_tokens = -N_est, actual_tokens = N_act → counts N_act
+# Net: in-flight estimates + completed actuals.
+#
+# Usage: tokens=$(governor_ledger_total_tokens "$session_id")
+governor_ledger_total_tokens() {
+	local session_id="${1:-}"
+	local ledger_path
+	ledger_path=$(governor_ledger_path "$session_id")
+
+	[[ -f "$ledger_path" ]] || { printf '0'; return 0; }
+
+	jq -s '[.[] | ((.estimated_tokens // 0) + (.actual_tokens // 0))] | add // 0' \
+		"$ledger_path" 2>/dev/null || printf '0'
+}
+
+# Running total of cost for a session (same two-phase logic as tokens).
+# Usage: cost=$(governor_ledger_total_cost "$session_id")
+governor_ledger_total_cost() {
+	local session_id="${1:-}"
+	local ledger_path
+	ledger_path=$(governor_ledger_path "$session_id")
+
+	[[ -f "$ledger_path" ]] || { printf '0'; return 0; }
+
+	jq -s '[.[] | ((.cost_usd_estimated // 0) + (.cost_usd_actual // 0))] | add // 0' \
+		"$ledger_path" 2>/dev/null || printf '0'
+}
+
+# Count completed Task calls (excludes reservation records).
+# Usage: calls=$(governor_ledger_call_count "$session_id")
+governor_ledger_call_count() {
+	local session_id="${1:-}"
+	local ledger_path
+	ledger_path=$(governor_ledger_path "$session_id")
+
+	[[ -f "$ledger_path" ]] || { printf '0'; return 0; }
+
+	jq -s '[.[] | select(.agent_type == "Task" and .record_type != "reservation")] | length' \
+		"$ledger_path" 2>/dev/null || printf '0'
+}

package/release-please-config.json

@@ -78,6 +78,22 @@
           "jsonpath": "$.version"
         }
       ]
+    },
+    "plugins/governor": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "component": "governor",
+      "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/governor-config.bats

@@ -0,0 +1,106 @@
+#!/usr/bin/env bats
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/governor"
+	export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/governor-config.sh"
+}
+
+@test "governor is disabled by default" {
+	governor_config_load ""
+	run governor_config_enabled
+	[ "$status" -ne 0 ]
+}
+
+@test "user-level settings.json can enable governor" {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"governor":{"enabled":true}}' > "${HOME}/.claude/settings.json"
+	governor_config_load ""
+	run governor_config_enabled
+	[ "$status" -eq 0 ]
+}
+
+@test "repo-level settings.json overrides user-level" {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"governor":{"enabled":true}}' > "${HOME}/.claude/settings.json"
+	local repo="${BATS_TEST_TMPDIR}/repo"
+	mkdir -p "${repo}/.claude"
+	printf '%s\n' '{"governor":{"enabled":false}}' > "${repo}/.claude/settings.json"
+	governor_config_load "$repo"
+	run governor_config_enabled
+	[ "$status" -ne 0 ]
+}
+
+@test "default enforcement is soft" {
+	governor_config_load ""
+	local v
+	v=$(governor_config_enforcement)
+	[ "$v" = "soft" ]
+}
+
+@test "enforcement can be overridden to hard" {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"governor":{"enforcement":"hard"}}' > "${HOME}/.claude/settings.json"
+	governor_config_load ""
+	local v
+	v=$(governor_config_enforcement)
+	[ "$v" = "hard" ]
+}
+
+@test "default tokens budget is 100000" {
+	governor_config_load ""
+	local v
+	v=$(governor_config_get '.governor.session.tokens_default')
+	[ "$v" = "100000" ]
+}
+
+@test "default cost budget is 1.0" {
+	governor_config_load ""
+	local v
+	v=$(governor_config_get '.governor.session.cost_usd_default')
+	[ "$v" = "1.0" ]
+}
+
+@test "default safety margin is 1.3" {
+	governor_config_load ""
+	local v
+	v=$(governor_config_get '.governor.estimation.safety_margin')
+	[ "$v" = "1.3" ]
+}
+
+@test "default hard_stop_margin is 1.5" {
+	governor_config_load ""
+	local v
+	v=$(governor_config_get '.governor.estimation.hard_stop_margin')
+	[ "$v" = "1.5" ]
+}
+
+@test "default estimation method is tier_table" {
+	governor_config_load ""
+	local v
+	v=$(governor_config_get '.governor.estimation.method')
+	[ "$v" = "tier_table" ]
+}
+
+@test "governor_config_get returns empty for missing key" {
+	governor_config_load ""
+	local v
+	v=$(governor_config_get '.governor.no_such_key')
+	[ -z "$v" ]
+}
+
+@test "empty repo_root does not load /.claude/settings.json" {
+	# Place a settings.json at the absolute root path that an empty repo_root would produce.
+	# On a real machine this won't exist, but in CI it might; the guard should skip it.
+	# We verify that a file at / does not influence config by confirming the default holds.
+	governor_config_load ""
+	run governor_config_enabled
+	# Default is disabled — if /.claude/settings.json were loaded with {enabled:true}
+	# this would fail. We can't plant a file at / in tests, so we assert the default
+	# is intact (regression guard rather than direct injection test).
+	[ "$status" -ne 0 ]
+}