@onlooker-community/ecosystem 0.10.0 → 0.15.0

package/plugins/tribunal/docs/adr/002-majority-gate-policy.md

@@ -0,0 +1,48 @@
+# ADR-002: Majority Gate Policy as Default
+
+**Status:** Accepted  
+**Date:** 2026-05-24
+
+## Context
+
+After the Jury and Meta-Judge tiers produce scores, the Gate must decide: accept the output, retry, or exhaust? Several policies were considered:
+
+- **Score threshold only** — pass if `aggregated_score >= threshold` (e.g., 0.75).
+- **Unanimous** — pass only if every judge voted passed.
+- **Majority** — pass if strictly more than half of judges voted passed.
+- **Meta-override** — the Meta-Judge's recommendation overrides the jury.
+- **Hybrid** — any combination of the above.
+
+The available policies in config are: `majority`, `strict` (alias for `unanimous`), `unanimous`, `meta_override`.
+
+## Decision
+
+The default gate policy is **`majority`**. The gate requires **both** the jury policy vote **and** `score_threshold` to clear — both conditions must be true for a pass. `score_threshold: 0.75` is a hard blocking condition, not just a reporting signal.
+
+## Rationale
+
+**Majority is the most intuitive policy for a multi-judge panel.** In any jury system, majority verdict is the natural baseline. It prevents a single outlier judge from blocking a good result indefinitely (the adversarial judge is *designed* to find fault and rarely gives a full pass).
+
+**Unanimous is too strict for the default judge composition.** With `["standard", "adversarial"]`, the adversarial judge is built to be skeptical. A policy requiring it to pass alongside the standard judge effectively gives veto power to the judge whose job is to reject. In practice, unanimous with this composition would mean the gate almost never passes.
+
+**Score threshold alone conflates jury agreement with quality.** A score of 0.8 from two judges who disagree strongly (e.g., 1.0 and 0.6) is a different signal than 0.8 from two judges who both scored 0.8. The majority policy captures agreement; the dissent threshold captures disagreement.
+
+## The 2-judge edge case
+
+The majority formula is `passed_count * 2 > total_count`. With two judges:
+
+| Judges passed | Formula | Result |
+|--------------|---------|--------|
+| 2/2 | `2 * 2 > 2` → `4 > 2` | ✓ pass |
+| 1/2 | `1 * 2 > 2` → `2 > 2` | ✗ block |
+| 0/2 | `0 * 2 > 2` → `0 > 2` | ✗ block |
+
+This means with the default two-judge panel, **both judges must pass** for the gate to open. This behaves like unanimous in the 2-judge case. This was observed during early Tribunal development (Echo's own Tribunal evaluation exhausted all 3 iterations because the adversarial judge never passed). It is technically correct — strictly more than half of 2 requires 2 — but surprises users expecting "majority" to mean "1 out of 2".
+
+**The consequence is intentional:** two judges is already a lean panel. Requiring both to pass ensures quality signal from both perspectives before accepting. Users who want genuine 2/3 behavior should add a third judge type (e.g., `security`) to the panel — majority with three judges means two must pass, which is materially different from two-judge unanimous.
+
+## Consequences
+
+- The `majority` policy with 2 judges is effectively `unanimous`. This should be documented prominently for users configuring judge panels.
+- Adding a third judge type (e.g., `security`) changes `majority` to mean 2/3, which is a meaningfully different bar. Users who want consistent behavior regardless of panel size should specify `gate_policy: "unanimous"` explicitly.
+- The `meta_override` policy gives the Meta-Judge final say, bypassing jury vote counts entirely. This is available but not the default — it introduces a single point of failure (Meta-Judge bias or hallucination) that the default policy is specifically designed to avoid.

package/plugins/tribunal/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/tribunal-stop-gate.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/tribunal/scripts/hooks/tribunal-stop-gate.sh

@@ -0,0 +1,267 @@
+#!/usr/bin/env bash
+# Tribunal Stop-gate hook.
+#
+# Triggered by Stop. Off by default — gated on tribunal.stop_hook.enabled in
+# config. When enabled, runs a single-judge advisory pass on the just-finished
+# session's last turn and writes a verdict for review on the next session.
+#
+# Why advisory only: by the time Stop fires the main agent loop has already
+# ended. We cannot retry the Actor or re-run the work. The hook records what
+# the Standard Judge would have said so a human (or a follow-up SessionStart
+# hook in v0.2) can see whether the turn would have passed the gate.
+#
+# Hook contract:
+#   - Always exits 0. Never blocks Stop.
+#   - Skips silently if disabled, no git context, no transcript, or skip_if_no_file_changes
+#     is true and the last turn did not modify files.
+#   - Errors from `claude -p` are swallowed; worst case is "no verdict for this stop".
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+# Ecosystem substrate lives in the sibling ecosystem plugin. Same lookup as
+# archivist-extract.sh.
+_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/onlooker-schema.sh"
+fi
+
+# shellcheck source=../lib/tribunal-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/tribunal-config.sh"
+# shellcheck source=../lib/tribunal-project-key.sh
+source "${PLUGIN_ROOT}/scripts/lib/tribunal-project-key.sh"
+# shellcheck source=../lib/tribunal-ulid.sh
+source "${PLUGIN_ROOT}/scripts/lib/tribunal-ulid.sh"
+# shellcheck source=../lib/tribunal-events.sh
+source "${PLUGIN_ROOT}/scripts/lib/tribunal-events.sh"
+# shellcheck source=../lib/tribunal-verdict.sh
+source "${PLUGIN_ROOT}/scripts/lib/tribunal-verdict.sh"
+
+INPUT=$(cat)
+
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+TRANSCRIPT_PATH=$(printf '%s' "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null) || TRANSCRIPT_PATH=""
+
+# Stop hook MUST NOT emit any stdout besides the optional `{continue: ...}`
+# acknowledgement. Exiting 0 with no output is the safe path.
+_done() {
+	exit 0
+}
+
+REPO_ROOT=$(tribunal_project_repo_root "$CWD")
+tribunal_config_load "$REPO_ROOT"
+
+if ! tribunal_config_stop_hook_enabled; then
+	_done
+fi
+
+PROJECT_KEY=$(tribunal_project_key "$CWD")
+if [[ -z "$PROJECT_KEY" || -z "$REPO_ROOT" ]]; then
+	_done
+fi
+
+if [[ -z "$TRANSCRIPT_PATH" || ! -f "$TRANSCRIPT_PATH" ]]; then
+	_done
+fi
+
+# Skip if no files were modified since the last commit AND the user enabled
+# skip_if_no_file_changes (default true).
+SKIP_IF_CLEAN=$(tribunal_config_get '.tribunal.stop_hook.skip_if_no_file_changes')
+if [[ "$SKIP_IF_CLEAN" == "true" ]]; then
+	if git -C "$REPO_ROOT" diff --quiet 2>/dev/null && git -C "$REPO_ROOT" diff --cached --quiet 2>/dev/null; then
+		_done
+	fi
+fi
+
+if ! command -v claude >/dev/null 2>&1; then
+	_done
+fi
+
+# ----------------------------------------------------------------------------
+# Build the advisory-judge prompt.
+# ----------------------------------------------------------------------------
+
+JUDGE_MODEL=$(tribunal_config_judge_model "standard")
+[[ -z "$JUDGE_MODEL" || "$JUDGE_MODEL" == "null" ]] && JUDGE_MODEL=""
+
+SCORE_THRESHOLD=$(tribunal_config_get '.tribunal.session.score_threshold')
+[[ -z "$SCORE_THRESHOLD" ]] && SCORE_THRESHOLD="0.75"
+
+TRANSCRIPT_TAIL=$(tail -c 30000 "$TRANSCRIPT_PATH" 2>/dev/null) || TRANSCRIPT_TAIL=""
+[[ -z "$TRANSCRIPT_TAIL" ]] && _done
+
+DIFF_SUMMARY=$(git -C "$REPO_ROOT" diff --stat 2>/dev/null | tail -c 4000) || DIFF_SUMMARY=""
+
+PROMPT_FILE=$(mktemp -t tribunal-stop-prompt.XXXXXX 2>/dev/null) || PROMPT_FILE="/tmp/tribunal-stop-prompt.$$"
+trap 'rm -f "$PROMPT_FILE"' EXIT
+
+{
+	printf '%s\n' 'You are a Tribunal Standard Judge performing an advisory pass on a just-finished Claude Code turn. Return JSON only — no prose, no markdown fences.'
+	printf '\n'
+	printf '%s\n' 'Output schema (TribunalVerdictPayload, exactly these keys):'
+	printf '%s\n' '{'
+	printf '%s\n' '  "score": 0.0..1.0,'
+	printf '%s\n' '  "passed": true|false,'
+	printf '%s\n' '  "judge_type": "standard",'
+	printf '%s\n' '  "feedback_summary": "1-3 sentences naming the highest-leverage concern, if any.",'
+	printf '%s\n' '  "confidence": 0.0..1.0'
+	printf '%s\n' '}'
+	printf '\n'
+	printf '%s\n' "Score the work the assistant performed in this turn against general correctness, completeness, and clarity. A score >= ${SCORE_THRESHOLD} is \"passed\"."
+	printf '%s\n' 'This is advisory — the main session has already ended, no retry will happen. Be concise.'
+	printf '\n'
+	if [[ -n "$DIFF_SUMMARY" ]]; then
+		printf '%s\n' '---WORKING-TREE DIFF STAT---'
+		printf '%s\n' "$DIFF_SUMMARY"
+		printf '%s\n' '---END DIFF STAT---'
+		printf '\n'
+	fi
+	printf '%s\n' '---TRANSCRIPT TAIL---'
+	printf '%s\n' "$TRANSCRIPT_TAIL"
+	printf '%s\n' '---END TRANSCRIPT TAIL---'
+} > "$PROMPT_FILE"
+
+CLAUDE_ARGS=(-p --max-turns 1)
+[[ -n "$JUDGE_MODEL" ]] && CLAUDE_ARGS+=(--model "$JUDGE_MODEL")
+
+RESPONSE=""
+if command -v timeout >/dev/null 2>&1; then
+	RESPONSE=$(timeout 60 claude "${CLAUDE_ARGS[@]}" < "$PROMPT_FILE" 2>/dev/null) || RESPONSE=""
+elif command -v gtimeout >/dev/null 2>&1; then
+	RESPONSE=$(gtimeout 60 claude "${CLAUDE_ARGS[@]}" < "$PROMPT_FILE" 2>/dev/null) || RESPONSE=""
+else
+	RESPONSE=$(claude "${CLAUDE_ARGS[@]}" < "$PROMPT_FILE" 2>/dev/null) || RESPONSE=""
+fi
+
+[[ -z "$RESPONSE" ]] && _done
+
+CLEAN_RESPONSE=$(printf '%s' "$RESPONSE" | sed -e 's/^```json//' -e 's/^```//' -e 's/```$//')
+if ! printf '%s' "$CLEAN_RESPONSE" | jq -e '.score and (.passed // false | type == "boolean") and .judge_type' >/dev/null 2>&1; then
+	_done
+fi
+
+# ----------------------------------------------------------------------------
+# Emit the canonical event chain + persist the advisory verdict.
+# ----------------------------------------------------------------------------
+
+TASK_ID=$(tribunal_ulid)
+ITERATION_ID=$(tribunal_ulid)
+JUDGE_ID=$(tribunal_ulid)
+
+START_PAYLOAD=$(jq -n \
+	--arg task_id "$TASK_ID" \
+	--arg model "$JUDGE_MODEL" \
+	--argjson thr "$SCORE_THRESHOLD" \
+	'{
+		task_id: $task_id,
+		judge_types: ["standard"],
+		gate_policy: "strict",
+		score_threshold: $thr,
+		max_iterations: 1
+	} + (if $model != "" then {judge_model_ids: [$model]} else {} end)')
+
+ITER_PAYLOAD=$(jq -n \
+	--arg task_id "$TASK_ID" \
+	--arg iter_id "$ITERATION_ID" \
+	'{task_id: $task_id, iteration_id: $iter_id, iteration_number: 0, trigger: "initial"}')
+
+JUDGE_START_PAYLOAD=$(jq -n \
+	--arg task_id "$TASK_ID" \
+	--arg iter_id "$ITERATION_ID" \
+	--arg judge_id "$JUDGE_ID" \
+	--arg model "$JUDGE_MODEL" \
+	'{
+		task_id: $task_id,
+		iteration_id: $iter_id,
+		judge_id: $judge_id,
+		judge_type: "standard",
+		judge_model_id: (if $model == "" then null else $model end)
+	} | with_entries(select(.value != null))')
+
+VERDICT_PAYLOAD=$(printf '%s' "$CLEAN_RESPONSE" | jq -c \
+	--arg task_id "$TASK_ID" \
+	--arg iter_id "$ITERATION_ID" \
+	--arg judge_id "$JUDGE_ID" \
+	--arg model "$JUDGE_MODEL" \
+	--argjson thr "$SCORE_THRESHOLD" \
+	'{
+		task_id: $task_id,
+		score: .score,
+		passed: (.passed // (.score >= $thr)),
+		judge_type: "standard",
+		iteration_id: $iter_id,
+		judge_id: $judge_id,
+		feedback_summary: (.feedback_summary // ""),
+		confidence: (.confidence // 0.6),
+		judge_model_id: (if $model == "" then null else $model end)
+	} | with_entries(select(.value != null and .value != ""))')
+
+SCORE=$(printf '%s' "$VERDICT_PAYLOAD" | jq -r '.score')
+PASSED=$(printf '%s' "$VERDICT_PAYLOAD" | jq -r '.passed')
+
+if [[ "$PASSED" == "true" ]]; then
+	GATE_PAYLOAD=$(jq -n \
+		--arg task_id "$TASK_ID" \
+		--arg iter_id "$ITERATION_ID" \
+		--argjson score "$SCORE" \
+		'{task_id: $task_id, iteration_id: $iter_id, final_score: $score, iteration_number: 0, judges_consulted: 1}')
+	GATE_EVENT="tribunal.gate.passed"
+	OUTCOME="accepted"
+else
+	GATE_PAYLOAD=$(jq -n \
+		--arg task_id "$TASK_ID" \
+		--arg iter_id "$ITERATION_ID" \
+		--argjson score "$SCORE" \
+		'{task_id: $task_id, iteration_id: $iter_id, reason: "low_score", final_score: $score, iteration_number: 0, will_retry: false}')
+	GATE_EVENT="tribunal.gate.blocked"
+	OUTCOME="rejected"
+fi
+
+COMPLETE_PAYLOAD=$(jq -n \
+	--arg task_id "$TASK_ID" \
+	--arg outcome "$OUTCOME" \
+	--argjson score "$SCORE" \
+	'{task_id: $task_id, outcome: $outcome, final_score: $score, iterations_used: 1}')
+
+# Emit in canonical order. Each call is best-effort — a single schema failure
+# should not break the user's Stop.
+tribunal_emit_event "tribunal.session.start"     "$START_PAYLOAD"        || true
+tribunal_emit_event "tribunal.iteration.start"   "$ITER_PAYLOAD"         || true
+tribunal_emit_event "tribunal.judge.start"       "$JUDGE_START_PAYLOAD"  || true
+tribunal_emit_event "tribunal.verdict"           "$VERDICT_PAYLOAD"      || true
+tribunal_emit_event "$GATE_EVENT"                "$GATE_PAYLOAD"         || true
+tribunal_emit_event "tribunal.session.complete"  "$COMPLETE_PAYLOAD"     || true
+
+# Persist a single advisory file for the next session to surface.
+STOP_DIR="$(tribunal_project_dir "$PROJECT_KEY")"
+mkdir -p "$STOP_DIR" 2>/dev/null || _done
+SAFE_SESSION_ID=$(printf '%s' "$SESSION_ID" | tr -c 'a-zA-Z0-9-' '_')
+[[ -z "$SAFE_SESSION_ID" ]] && SAFE_SESSION_ID="unknown"
+
+jq -n \
+	--arg task_id "$TASK_ID" \
+	--arg session_id "$SESSION_ID" \
+	--arg outcome "$OUTCOME" \
+	--argjson verdict "$VERDICT_PAYLOAD" \
+	'{
+		task_id: $task_id,
+		session_id: $session_id,
+		outcome: $outcome,
+		verdict: $verdict,
+		mode: "stop-advisory"
+	}' > "${STOP_DIR}/stop-${SAFE_SESSION_ID}.json" 2>/dev/null || true
+
+_done

package/plugins/tribunal/scripts/lib/tribunal-aggregate.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Score aggregation for Tribunal.
+#
+# Aggregates per-judge verdicts into a single jury-level score per the chosen
+# aggregation_method. Also computes the dissent metric (max - min) so callers
+# can decide whether to emit tribunal.dissent.recorded.
+#
+# Verdicts input is a JSON array of TribunalVerdictPayload objects (or a subset
+# containing at least { judge_id, score }). Rubric is the active rubric (for
+# weighted_mean only).
+#
+# Exposes:
+#   tribunal_aggregate <method> <verdicts_json> [<rubric_json>]
+#       echoes the aggregated score (0..1) as a JSON number
+#   tribunal_disagreement <verdicts_json>
+#       echoes max(score) - min(score), or 0 if 0/1 verdicts
+#
+# weighted_mean uses *rubric criterion weights*, not per-judge weights — the
+# semantics are "weight each criterion's contribution, then average judges'
+# scores on each criterion." For v0.1 the per-criterion breakdown is not yet
+# threaded through verdicts, so weighted_mean degrades to mean when the rubric
+# weights cannot be applied. The schema still emits aggregation_method =
+# "weighted_mean" so dashboards see the intent.
+
+tribunal_aggregate() {
+	local method="${1:-mean}"
+	local verdicts="${2:-[]}"
+	local _rubric="${3:-{}}"  # reserved for true weighted_mean once per-criterion scores are threaded
+	: "$_rubric"
+
+	local count
+	count=$(printf '%s' "$verdicts" | jq 'length' 2>/dev/null) || count=0
+	[[ "$count" -eq 0 ]] && { printf '0'; return 0; }
+
+	case "$method" in
+		mean|weighted_mean)
+			printf '%s' "$verdicts" | jq -r '[.[].score] | add / length'
+			;;
+		median)
+			printf '%s' "$verdicts" | jq -r '
+				[.[].score] | sort as $s
+				| ($s | length) as $n
+				| if ($n % 2) == 1 then $s[($n - 1) / 2]
+				  else (($s[$n / 2 - 1] + $s[$n / 2]) / 2)
+				  end
+			'
+			;;
+		min)
+			printf '%s' "$verdicts" | jq -r '[.[].score] | min'
+			;;
+		*)
+			printf 'tribunal-aggregate: unknown method %s, falling back to mean\n' \
+				"$method" >&2
+			printf '%s' "$verdicts" | jq -r '[.[].score] | add / length'
+			;;
+	esac
+}
+
+tribunal_disagreement() {
+	local verdicts="${1:-[]}"
+	local count
+	count=$(printf '%s' "$verdicts" | jq 'length' 2>/dev/null) || count=0
+	[[ "$count" -lt 2 ]] && { printf '0'; return 0; }
+	printf '%s' "$verdicts" | jq -r '[.[].score] | (max - min)'
+}

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

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# Config resolution for Tribunal.
+#
+# Reads three layers, latest wins:
+#   1. plugins/tribunal/config.json (defaults shipped with the plugin)
+#   2. ~/.claude/settings.json
+#   3. <repo>/.claude/settings.json
+#
+# Exposes:
+#   tribunal_config_load <repo_root>       # populates _TRIBUNAL_CONFIG (JSON)
+#   tribunal_config_get <jq-path>          # echoes string value (empty if unset)
+#   tribunal_config_get_json <jq-path>     # echoes JSON value (null if unset)
+#   tribunal_config_enabled                # 0 if tribunal.enabled is true
+#   tribunal_config_stop_hook_enabled      # 0 if tribunal.stop_hook.enabled is true
+#   tribunal_config_judge_model <judge_type>
+#                                          # echoes per-judge-type model override,
+#                                          # falling back to tribunal.judges.model
+#
+# Settings overlay only touches the `tribunal.*` subtree so this plugin coexists
+# with other plugins' configuration.
+
+_TRIBUNAL_CONFIG="{}"
+
+tribunal_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
+
+	for file in "${home_dir}/.claude/settings.json" "${repo_root}/.claude/settings.json"; do
+		[[ -n "$file" && -f "$file" ]] || continue
+		local overlay
+		overlay=$(jq '{ tribunal: (.tribunal // {}) }' "$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
+
+	_TRIBUNAL_CONFIG="$merged"
+}
+
+# Read a string value from the loaded config.
+# Usage: tribunal_config_get '.tribunal.session.gate_policy'
+tribunal_config_get() {
+	local path="$1"
+	printf '%s' "$_TRIBUNAL_CONFIG" | jq -r "${path} // empty" 2>/dev/null
+}
+
+# Read a JSON value (arrays, objects, numbers) from the loaded config.
+# Usage: tribunal_config_get_json '.tribunal.session.judge_types'
+tribunal_config_get_json() {
+	local path="$1"
+	printf '%s' "$_TRIBUNAL_CONFIG" | jq -c "${path}" 2>/dev/null
+}
+
+# Returns 0 if tribunal.enabled is true.
+tribunal_config_enabled() {
+	local v
+	v=$(tribunal_config_get '.tribunal.enabled')
+	[[ "$v" == "true" ]]
+}
+
+# Returns 0 if tribunal.stop_hook.enabled is true. Default is false.
+tribunal_config_stop_hook_enabled() {
+	local v
+	v=$(tribunal_config_get '.tribunal.stop_hook.enabled')
+	[[ "$v" == "true" ]]
+}
+
+# Resolve the model id for a given judge_type.
+# Precedence: tribunal.judges.<type>.model > tribunal.judges.model
+tribunal_config_judge_model() {
+	local judge_type="$1"
+	local override
+	override=$(tribunal_config_get ".tribunal.judges.\"${judge_type}\".model")
+	if [[ -n "$override" ]]; then
+		printf '%s' "$override"
+		return 0
+	fi
+	tribunal_config_get '.tribunal.judges.model'
+}

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

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# Canonical tribunal.* event emission.
+#
+# Thin wrapper around the ecosystem plugin's onlooker-event.mjs `emit` mode.
+# Every emission is validated against @onlooker-community/schema v2.1.0+ before
+# it is appended to ~/.onlooker/logs/onlooker-events.jsonl.
+#
+# Why a per-plugin wrapper: bash hooks should not have to know about node
+# invocation paths or env wiring. This module centralizes that detail so the
+# orchestrator and Stop hook both call `tribunal_emit_event <type> <payload>`.
+#
+# Requires:
+#   - $ONLOOKER_DIR (set by the ecosystem onlooker-schema.sh)
+#   - $ONLOOKER_EVENTS_LOG (same)
+#   - $_HOOK_SESSION_ID or $CLAUDE_SESSION_ID for the session id
+#   - The ecosystem onlooker-event.mjs reachable via $_ONLOOKER_EVENT_JS or
+#     under the ecosystem plugin root.
+#
+# Usage:
+#   tribunal_emit_event "tribunal.session.start" '{"task_id":"01J...","gate_policy":"majority"}'
+
+_TRIBUNAL_PLUGIN_NAME="tribunal"
+
+# Resolve the ecosystem onlooker-event.mjs even when CLAUDE_PLUGIN_ROOT points
+# at the tribunal plugin (the wrapper script lives under ecosystem/scripts/lib).
+_tribunal_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
+}
+
+_tribunal_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 tribunal event. Returns 0 on success, non-zero on validation
+# failure (so callers can decide whether to abort the loop). Validation errors
+# are written to stderr.
+tribunal_emit_event() {
+	local event_type="${1:-}"
+	local payload="${2:-}"
+	[[ -z "$event_type" || -z "$payload" ]] && return 1
+
+	local event_js
+	event_js=$(_tribunal_event_js_path) || {
+		printf 'tribunal-events: cannot locate onlooker-event.mjs\n' >&2
+		return 1
+	}
+
+	local session_id
+	session_id=$(_tribunal_session_id)
+
+	local params
+	params=$(jq -n \
+		--arg plugin "$_TRIBUNAL_PLUGIN_NAME" \
+		--arg sid "$session_id" \
+		--arg type "$event_type" \
+		--argjson payload "$payload" \
+		'{plugin: $plugin, session_id: $sid, event_type: $type, payload: $payload}')
+
+	local event
+	local stderr_file
+	stderr_file=$(mktemp -t tribunal-event-err.XXXXXX 2>/dev/null) || stderr_file="/tmp/tribunal-event-err.$$"
+	event=$(printf '%s' "$params" \
+		| ONLOOKER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}" \
+		  ONLOOKER_PLUGIN_NAME="$_TRIBUNAL_PLUGIN_NAME" \
+		  node "$event_js" emit 2>"$stderr_file") || {
+		printf 'tribunal-events: 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"
+}