@onlooker-community/ecosystem 0.10.0 → 0.15.0

package/plugins/echo/docs/adr/002-direct-evaluation-vs-tribunal-pipeline.md

@@ -0,0 +1,35 @@
+# ADR-002: Direct `claude -p` Evaluation vs. Routing Through Tribunal's Pipeline
+
+**Status:** Accepted (with planned future extension)  
+**Date:** 2026-05-24
+
+## Context
+
+Echo needs to evaluate prompt file quality before and after a change. Two approaches were available:
+
+**Option A — Direct `claude -p`**: Build an inline rubric prompt, call `claude -p --max-turns 1` for each file, and parse the JSON score from the response.
+
+**Option B — Tribunal pipeline**: Invoke Tribunal's multi-judge Actor → Jury → Meta-Judge → Gate loop for each file and use the aggregated score as the quality signal.
+
+## Decision
+
+Echo v0.1 uses **Option A** — direct `claude -p` with an inline rubric.
+
+## Rationale
+
+**Stop hook latency budget.** A Stop hook fires synchronously at the end of every session. Tribunal's full loop (Actor + two judges + Meta-Judge + Gate, with potential retries) takes 30–120 seconds per task. Multiplied across several watched files, this would make sessions feel like they hang after every edit. A single `claude -p` call with a 60-second timeout keeps the overhead acceptable.
+
+**Echo evaluates prompts, not outputs.** Tribunal's loop is designed to evaluate an Agent's *work product* against a rubric. Echo evaluates *the prompt file itself* — a simpler, single-document task. A full jury is architecturally overweight for this use case.
+
+**Baseline stability.** Tribunal's multi-judge scores have meaningful variance across runs (different judge models, adversarial judge behavior, Meta-Judge overrides). Echo's baseline comparison depends on stable, reproducible scores — a single `claude -p` pass with a fixed model and rubric is more consistent as a yardstick.
+
+**Haiku is cheap enough.** Evaluating a prompt file with Haiku costs a fraction of a cent. Running a full Tribunal loop (Opus-class models for judges) would cost 10–50× more per file per session. With a default model of `claude-haiku-4-5-20251001`, Echo can run automatically without raising cost concerns.
+
+**Independent of Tribunal installation.** Option A requires only the `claude` CLI. Option B would make Tribunal a hard runtime dependency of Echo, coupling two plugins that have separate versioning and installation paths (see ADR-001).
+
+## Consequences
+
+- Echo's evaluation quality is bounded by a single-model, single-pass rubric. It will miss issues that a diverse jury would catch, but it is consistent enough to detect regressions.
+- The scoring rubric (role clarity, output format, criterion coverage, internal consistency) is hardcoded in the hook rather than being user-overridable in v0.1. A future version should expose this as config.
+- A future `echo.mode: "tribunal"` config option could delegate to Tribunal's jury for higher-confidence evaluation when cost and latency are acceptable. The current design leaves room for this — Echo's event schema (`echo.suite.started`, etc.) is agnostic to the underlying evaluator.
+- The `claude -p` response parsing includes a `sed` strip for accidental markdown fences, which Tribunal's pipeline avoids by using structured judge output. This is a fragility to watch.

package/plugins/echo/docs/adr/003-stop-hook-trigger.md

@@ -0,0 +1,40 @@
+# ADR-003: Stop Hook as the Trigger Mechanism
+
+**Status:** Accepted  
+**Date:** 2026-05-24
+
+## Context
+
+Echo needs to know when an agent file has changed and run an evaluation. Several trigger points were considered:
+
+- **Stop hook** — fires when a Claude Code session ends.
+- **Pre-commit hook** — fires when the developer runs `git commit`.
+- **PostToolUse hook** — fires after every tool call that writes a file.
+- **CI step** — fires on push to a remote branch.
+- **Manual `/echo` skill** — user-invoked on demand.
+
+## Decision
+
+Echo v0.1 uses the **Stop hook**.
+
+## Rationale
+
+**Correct granularity.** A session is the natural unit of prompt engineering work. A developer edits `tribunal-judge-standard.md`, tests it through several turns, and ends the session. That's the moment Echo should fire — after the work is done, not after each intermediate save.
+
+**Claude Code already provides it.** The Stop hook is a first-class Claude Code hook type with a well-defined contract: the hook receives `{cwd, session_id}` on stdin and must exit 0 (or the session stop is blocked, which is why Echo always exits 0). No additional tooling or git hooks needed.
+
+**Consistent with Tribunal's pattern.** Tribunal's Stop hook (when enabled) follows the same pattern — an advisory pass that fires at session end without blocking the stop. Echo mirrors this, which keeps the plugin model coherent across the ecosystem.
+
+**No commit discipline required.** A pre-commit hook would only fire when the developer commits. Many prompt engineering workflows involve many experimental edits before any commit. Echo should capture signal on *any* session where a watched file changed, not only committed ones. Untracked and unstaged files are explicitly included in Echo's change detection.
+
+**Low friction.** PostToolUse fires on every file write, which would run evaluations continuously mid-session — expensive, noisy, and disruptive. The Stop hook batches all changes from a session into a single suite run.
+
+**Not CI.** CI integration has value but is a separate concern. A CI step can't write to `~/.onlooker/` on the developer's machine, and the baseline comparison is inherently local. Echo is a local development feedback tool; CI integration (e.g., posting drift to a PR comment) is a future feature.
+
+## Consequences
+
+- The recursion guard (`ECHO_NESTED=1`) is mandatory. `claude -p` spawns a subprocess that also triggers Stop, which would re-enter the hook infinitely. The guard must be set before any work begins and is checked as the very first statement.
+- Echo cannot fire mid-session, so rapid iteration on a prompt file produces one signal per session, not one per edit. This is a feature for reducing noise, but means a long session with many edits only records the final state of each file.
+- If a session ends without the developer saving changes (e.g., closed the terminal abruptly), the Stop hook may not fire. This is consistent with how all Stop hooks in Claude Code behave.
+- Users who want on-demand evaluation can invoke Echo's logic manually by calling the hook directly. A future `/echo` skill could wrap this.
+- The hook must be registered in `hooks.json` with `"matcher": "*"` so it fires on all sessions. Projects that want to opt out can set `echo.enabled: false` rather than removing the hook registration.

package/plugins/echo/hooks/hooks.json

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

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

@@ -0,0 +1,366 @@
+#!/usr/bin/env bash
+# Echo Stop-gate hook.
+#
+# Triggered by Stop. Off by default — gated on echo.enabled in config.
+# When enabled, detects which watched agent files changed in this session,
+# runs a single-judge advisory pass on each, and compares the score against a
+# stored baseline to report improved / degraded / neutral.
+#
+# Hook contract:
+#   - Always exits 0. Never blocks Stop.
+#   - Skips silently if disabled, no git context, or no watched files changed.
+#   - Recursion guard: exits immediately if ECHO_NESTED=1 to prevent a claude -p
+#     subprocess from re-triggering this hook on its own Writes.
+#   - Errors from `claude -p` are swallowed; worst case is no verdict written.
+
+set -uo pipefail
+
+# Recursion guard — must be first.
+[[ "${ECHO_NESTED:-}" == "1" ]] && exit 0
+export ECHO_NESTED=1
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+# Resolve the ecosystem root (sibling to this plugin's parent).
+_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/echo-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/echo-config.sh"
+# shellcheck source=../lib/echo-project-key.sh
+source "${PLUGIN_ROOT}/scripts/lib/echo-project-key.sh"
+# shellcheck source=../lib/echo-ulid.sh
+source "${PLUGIN_ROOT}/scripts/lib/echo-ulid.sh"
+# shellcheck source=../lib/echo-events.sh
+CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" source "${PLUGIN_ROOT}/scripts/lib/echo-events.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=""
+
+_done() { exit 0; }
+
+# ---------------------------------------------------------------------------
+# Config + prerequisites
+# ---------------------------------------------------------------------------
+
+REPO_ROOT=$(echo_project_repo_root "$CWD")
+[[ -z "$REPO_ROOT" ]] && _done
+
+CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" echo_config_load "$REPO_ROOT"
+echo_config_enabled || _done
+
+PROJECT_KEY=$(echo_project_key "$CWD")
+[[ -z "$PROJECT_KEY" ]] && _done
+
+command -v claude >/dev/null 2>&1 || _done
+command -v jq >/dev/null 2>&1 || _done
+
+# ---------------------------------------------------------------------------
+# Identify changed agent files
+# ---------------------------------------------------------------------------
+
+# Collect all changed paths: unstaged, staged, and untracked.
+CHANGED_FILES=$(git -C "$REPO_ROOT" diff --name-only HEAD 2>/dev/null) || CHANGED_FILES=""
+STAGED_FILES=$(git -C "$REPO_ROOT" diff --name-only --cached 2>/dev/null) || STAGED_FILES=""
+UNTRACKED_FILES=$(git -C "$REPO_ROOT" ls-files --others --exclude-standard 2>/dev/null) || UNTRACKED_FILES=""
+ALL_CHANGED=$(printf '%s\n%s\n%s' "$CHANGED_FILES" "$STAGED_FILES" "$UNTRACKED_FILES" | sort -u | grep -v '^$') || ALL_CHANGED=""
+[[ -z "$ALL_CHANGED" ]] && _done
+
+# Load watch and exclude patterns (bash 3 compatible — no mapfile).
+WATCH_PATTERNS=()
+while IFS= read -r _pat; do
+	[[ -n "$_pat" ]] && WATCH_PATTERNS+=("$_pat")
+done < <(CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" echo_config_watch_paths)
+
+EXCLUDE_PATTERNS=()
+while IFS= read -r _pat; do
+	[[ -n "$_pat" ]] && EXCLUDE_PATTERNS+=("$_pat")
+done < <(CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" echo_config_exclude_paths)
+
+# Filter changed files: must match at least one watch pattern AND no exclude pattern.
+WATCHED_CHANGED=()
+while IFS= read -r f; do
+	[[ -z "$f" ]] && continue
+
+	local_match=0
+	for pat in "${WATCH_PATTERNS[@]}"; do
+		# shellcheck disable=SC2053
+		if [[ "$f" == $pat ]]; then
+			local_match=1
+			break
+		fi
+	done
+	[[ "$local_match" -eq 0 ]] && continue
+
+	excluded=0
+	for pat in "${EXCLUDE_PATTERNS[@]}"; do
+		# shellcheck disable=SC2053
+		if [[ "$f" == $pat ]]; then
+			excluded=1
+			break
+		fi
+	done
+	[[ "$excluded" -eq 1 ]] && continue
+
+	WATCHED_CHANGED+=("$f")
+done <<< "$ALL_CHANGED"
+
+[[ "${#WATCHED_CHANGED[@]}" -eq 0 ]] && _done
+
+# ---------------------------------------------------------------------------
+# Storage paths
+# ---------------------------------------------------------------------------
+
+ONLOOKER_BASE="${ONLOOKER_DIR:-$HOME/.onlooker}"
+ECHO_DIR="${ONLOOKER_BASE}/echo/${PROJECT_KEY}"
+BASELINE_DIR="${ECHO_DIR}/baselines"
+mkdir -p "$BASELINE_DIR" 2>/dev/null || _done
+
+# ---------------------------------------------------------------------------
+# Evaluation loop
+# ---------------------------------------------------------------------------
+
+EVAL_MODEL=$(CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" echo_config_model)
+TIMEOUT_SECS=$(CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" echo_config_timeout)
+DRIFT_THRESHOLD=$(CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" echo_config_drift_threshold)
+
+SUITE_ID=$(echo_ulid)
+SUITE_START=$(python3 -c 'import time; print(int(time.time()*1000))' 2>/dev/null || echo 0)
+FIRST_CHANGED="${WATCHED_CHANGED[0]}"
+
+suite_started_payload=$(jq -n \
+	--arg suite_id "$SUITE_ID" \
+	--argjson test_count "${#WATCHED_CHANGED[@]}" \
+	--arg trigger "file_change" \
+	--arg changed_file "$FIRST_CHANGED" \
+	'{suite_id: $suite_id, test_count: $test_count, trigger: $trigger, changed_file: $changed_file}')
+echo_emit_event "echo.suite.started" "$suite_started_payload" || true
+
+PROMPT_FILE=$(mktemp -t echo-prompt.XXXXXX 2>/dev/null) || PROMPT_FILE="/tmp/echo-prompt.$$"
+trap 'rm -f "$PROMPT_FILE"' EXIT
+
+count_improved=0
+count_degraded=0
+count_neutral=0
+sum_before=0
+sum_after=0
+file_count=0
+
+for rel_path in "${WATCHED_CHANGED[@]}"; do
+	abs_path="${REPO_ROOT}/${rel_path}"
+	[[ ! -f "$abs_path" ]] && continue
+
+	FILE_CONTENT=$(cat "$abs_path" 2>/dev/null) || continue
+	[[ -z "$FILE_CONTENT" ]] && continue
+
+	TEST_ID=$(echo_test_id_for_path "$rel_path")
+	BASELINE_FILE="${BASELINE_DIR}/${TEST_ID}.json"
+
+	# Build the evaluation prompt.
+	{
+		printf '%s\n' 'You are evaluating an agent prompt file for quality. Return JSON only — no prose, no markdown fences.'
+		printf '\n'
+		printf '%s\n' 'Output schema (exactly these keys):'
+		printf '%s\n' '{'
+		printf '%s\n' '  "score": 0.0..1.0,'
+		printf '%s\n' '  "passed": true|false,'
+		printf '%s\n' '  "confidence": 0.0..1.0,'
+		printf '%s\n' '  "feedback": "1-2 sentences on the highest-leverage issue, if any."'
+		printf '%s\n' '}'
+		printf '\n'
+		printf '%s\n' 'Score on these criteria (equal weight):'
+		printf '%s\n' '  - Role clarity: does the file clearly define what the agent is and what it must do?'
+		printf '%s\n' '  - Output format: are output format and schema requirements unambiguous?'
+		printf '%s\n' '  - Criterion coverage: are all evaluation dimensions specified with enough detail to apply consistently?'
+		printf '%s\n' '  - Internal consistency: no contradictory instructions, no undefined terms.'
+		printf '\n'
+		printf '%s\n' "A score >= 0.7 is \"passed\". Be concise."
+		printf '\n'
+		printf '%s\n' "---FILE: ${rel_path}---"
+		printf '%s\n' "$FILE_CONTENT"
+		printf '%s\n' '---END FILE---'
+	} > "$PROMPT_FILE"
+
+	CLAUDE_ARGS=(-p --max-turns 1)
+	[[ -n "$EVAL_MODEL" ]] && CLAUDE_ARGS+=(--model "$EVAL_MODEL")
+
+	RESPONSE=""
+	if command -v timeout >/dev/null 2>&1; then
+		RESPONSE=$(timeout "$TIMEOUT_SECS" claude "${CLAUDE_ARGS[@]}" < "$PROMPT_FILE" 2>/dev/null) || RESPONSE=""
+	elif command -v gtimeout >/dev/null 2>&1; then
+		RESPONSE=$(gtimeout "$TIMEOUT_SECS" claude "${CLAUDE_ARGS[@]}" < "$PROMPT_FILE" 2>/dev/null) || RESPONSE=""
+	else
+		RESPONSE=$(claude "${CLAUDE_ARGS[@]}" < "$PROMPT_FILE" 2>/dev/null) || RESPONSE=""
+	fi
+
+	[[ -z "$RESPONSE" ]] && continue
+
+	CLEAN=$(printf '%s' "$RESPONSE" | sed -e 's/^```json//' -e 's/^```//' -e 's/```$//')
+	SCORE_AFTER=$(printf '%s' "$CLEAN" | jq -r '.score // empty' 2>/dev/null) || SCORE_AFTER=""
+	CONFIDENCE=$(printf '%s' "$CLEAN" | jq -r '.confidence // "0.6"' 2>/dev/null) || CONFIDENCE="0.6"
+	[[ -z "$SCORE_AFTER" ]] && continue
+
+	SCORE_BEFORE=""
+	if [[ -f "$BASELINE_FILE" ]]; then
+		SCORE_BEFORE=$(jq -r '.score // empty' "$BASELINE_FILE" 2>/dev/null) || SCORE_BEFORE=""
+	fi
+
+	# Persist new baseline.
+	jq -n \
+		--arg path "$rel_path" \
+		--arg test_id "$TEST_ID" \
+		--argjson score "$SCORE_AFTER" \
+		--arg ts "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
+		'{path: $path, test_id: $test_id, score: $score, recorded_at: $ts}' \
+		> "$BASELINE_FILE" 2>/dev/null || true
+
+	file_count=$((file_count + 1))
+	sum_after=$(python3 -c "print($sum_after + $SCORE_AFTER)" 2>/dev/null) || sum_after=$sum_after
+
+	if [[ -n "$SCORE_BEFORE" ]]; then
+		DELTA=$(python3 -c "print(round($SCORE_AFTER - $SCORE_BEFORE, 4))" 2>/dev/null) || DELTA="0"
+		sum_before=$(python3 -c "print($sum_before + $SCORE_BEFORE)" 2>/dev/null) || sum_before=$sum_before
+
+		ABS_DELTA=$(python3 -c "print(abs($DELTA))" 2>/dev/null) || ABS_DELTA="0"
+		IS_IMPROVED=$(python3 -c "print('true' if $DELTA > $DRIFT_THRESHOLD else 'false')" 2>/dev/null) || IS_IMPROVED="false"
+		IS_DEGRADED=$(python3 -c "print('true' if $DELTA < -$DRIFT_THRESHOLD else 'false')" 2>/dev/null) || IS_DEGRADED="false"
+
+		FILE_NAME=$(basename "$rel_path")
+
+		if [[ "$IS_IMPROVED" == "true" ]]; then
+			count_improved=$((count_improved + 1))
+			improvement_payload=$(jq -n \
+				--arg suite_id "$SUITE_ID" \
+				--arg test_id "$TEST_ID" \
+				--arg test_name "$FILE_NAME" \
+				--argjson score_before "$SCORE_BEFORE" \
+				--argjson score_after "$SCORE_AFTER" \
+				--argjson delta "$DELTA" \
+				--argjson confidence "$CONFIDENCE" \
+				'{suite_id: $suite_id, test_id: $test_id, test_name: $test_name,
+				  score_before: $score_before, score_after: $score_after,
+				  delta: $delta, confidence: $confidence}')
+			echo_emit_event "echo.improvement.detected" "$improvement_payload" || true
+
+		elif [[ "$IS_DEGRADED" == "true" ]]; then
+			count_degraded=$((count_degraded + 1))
+			regression_payload=$(jq -n \
+				--arg suite_id "$SUITE_ID" \
+				--arg test_id "$TEST_ID" \
+				--arg test_name "$FILE_NAME" \
+				--argjson score_before "$SCORE_BEFORE" \
+				--argjson score_after "$SCORE_AFTER" \
+				--argjson delta "$DELTA" \
+				--argjson confidence "$CONFIDENCE" \
+				'{suite_id: $suite_id, test_id: $test_id, test_name: $test_name,
+				  score_before: $score_before, score_after: $score_after,
+				  delta: $delta, confidence: $confidence}')
+			echo_emit_event "echo.regression.detected" "$regression_payload" || true
+		else
+			count_neutral=$((count_neutral + 1))
+		fi
+	else
+		# First evaluation for this file — no baseline to compare against yet.
+		count_neutral=$((count_neutral + 1))
+	fi
+done
+
+[[ "$file_count" -eq 0 ]] && _done
+
+# ---------------------------------------------------------------------------
+# Emit suite events
+# ---------------------------------------------------------------------------
+
+SUITE_END=$(python3 -c 'import time; print(int(time.time()*1000))' 2>/dev/null || echo 0)
+DURATION_MS=$(( SUITE_END - SUITE_START ))
+
+MERGE_RECOMMENDED="false"
+[[ "$count_degraded" -eq 0 && "$count_improved" -gt 0 ]] && MERGE_RECOMMENDED="true"
+[[ "$count_degraded" -eq 0 && "$count_improved" -eq 0 ]] && MERGE_RECOMMENDED="true"
+
+if [[ "$file_count" -gt 0 && -n "$sum_before" ]] && python3 -c "exit(0 if $sum_before > 0 else 1)" 2>/dev/null; then
+	BASELINE_AVG=$(python3 -c "print(round($sum_before / $file_count, 4))" 2>/dev/null) || BASELINE_AVG=""
+	AFTER_AVG=$(python3 -c "print(round($sum_after / $file_count, 4))" 2>/dev/null) || AFTER_AVG=""
+	DRIFT=$(python3 -c "print(round($sum_after / $file_count - $sum_before / $file_count, 4))" 2>/dev/null) || DRIFT=""
+
+	if [[ -n "$BASELINE_AVG" && -n "$AFTER_AVG" && -n "$DRIFT" ]]; then
+		suite_complete_payload=$(jq -n \
+			--arg suite_id "$SUITE_ID" \
+			--argjson test_count "$file_count" \
+			--argjson improved "$count_improved" \
+			--argjson degraded "$count_degraded" \
+			--argjson neutral "$count_neutral" \
+			--argjson merge_recommended "$MERGE_RECOMMENDED" \
+			--argjson duration_ms "$DURATION_MS" \
+			--argjson baseline_score "$BASELINE_AVG" \
+			--argjson score_after "$AFTER_AVG" \
+			--argjson drift "$DRIFT" \
+			--argjson drift_threshold "$DRIFT_THRESHOLD" \
+			'{suite_id: $suite_id, test_count: $test_count,
+			  improved: $improved, degraded: $degraded, neutral: $neutral,
+			  merge_recommended: $merge_recommended, duration_ms: $duration_ms,
+			  baseline_score: $baseline_score, score_after: $score_after,
+			  drift: $drift, drift_threshold: $drift_threshold}')
+	else
+		suite_complete_payload=$(jq -n \
+			--arg suite_id "$SUITE_ID" \
+			--argjson test_count "$file_count" \
+			--argjson improved "$count_improved" \
+			--argjson degraded "$count_degraded" \
+			--argjson neutral "$count_neutral" \
+			--argjson merge_recommended "$MERGE_RECOMMENDED" \
+			--argjson duration_ms "$DURATION_MS" \
+			'{suite_id: $suite_id, test_count: $test_count,
+			  improved: $improved, degraded: $degraded, neutral: $neutral,
+			  merge_recommended: $merge_recommended, duration_ms: $duration_ms}')
+	fi
+else
+	suite_complete_payload=$(jq -n \
+		--arg suite_id "$SUITE_ID" \
+		--argjson test_count "$file_count" \
+		--argjson improved "$count_improved" \
+		--argjson degraded "$count_degraded" \
+		--argjson neutral "$count_neutral" \
+		--argjson merge_recommended "$MERGE_RECOMMENDED" \
+		--argjson duration_ms "$DURATION_MS" \
+		'{suite_id: $suite_id, test_count: $test_count,
+		  improved: $improved, degraded: $degraded, neutral: $neutral,
+		  merge_recommended: $merge_recommended, duration_ms: $duration_ms}')
+fi
+echo_emit_event "echo.suite.complete" "$suite_complete_payload" || true
+
+# ---------------------------------------------------------------------------
+# Write advisory file for review in next session.
+# ---------------------------------------------------------------------------
+
+SAFE_SESSION_ID=$(printf '%s' "${SESSION_ID:-unknown}" | tr -c 'a-zA-Z0-9-' '_')
+
+jq -n \
+	--arg suite_id "$SUITE_ID" \
+	--arg session_id "${SESSION_ID:-unknown}" \
+	--argjson test_count "$file_count" \
+	--argjson improved "$count_improved" \
+	--argjson degraded "$count_degraded" \
+	--argjson neutral "$count_neutral" \
+	--argjson merge_recommended "$MERGE_RECOMMENDED" \
+	--argjson files "$(printf '%s\n' "${WATCHED_CHANGED[@]}" | jq -R . | jq -s .)" \
+	'{suite_id: $suite_id, session_id: $session_id, test_count: $test_count,
+	  improved: $improved, degraded: $degraded, neutral: $neutral,
+	  merge_recommended: $merge_recommended, files: $files}' \
+	> "${ECHO_DIR}/run-${SAFE_SESSION_ID}.json" 2>/dev/null || true
+
+_done

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

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# Config loading for Echo.
+# Reads config.json from the repo's .claude/settings.json echo.* keys,
+# falling back to the plugin's own config.json defaults.
+
+_ECHO_CONFIG_JSON=""
+_ECHO_PLUGIN_CONFIG_JSON=""
+
+echo_config_load() {
+	local repo_root="${1:-}"
+
+	_ECHO_PLUGIN_CONFIG_JSON=""
+	local plugin_config="${CLAUDE_PLUGIN_ROOT:-}/config.json"
+	if [[ -f "$plugin_config" ]]; then
+		_ECHO_PLUGIN_CONFIG_JSON=$(cat "$plugin_config" 2>/dev/null) || _ECHO_PLUGIN_CONFIG_JSON=""
+	fi
+
+	_ECHO_CONFIG_JSON=""
+	if [[ -n "$repo_root" ]]; then
+		local settings_file="${repo_root}/.claude/settings.json"
+		if [[ -f "$settings_file" ]]; then
+			local settings
+			settings=$(cat "$settings_file" 2>/dev/null) || settings=""
+			local echo_block
+			echo_block=$(printf '%s' "$settings" | jq -c '.echo // empty' 2>/dev/null) || echo_block=""
+			[[ -n "$echo_block" ]] && _ECHO_CONFIG_JSON="$echo_block"
+		fi
+	fi
+}
+
+# Get a single scalar value. Checks settings.json first, then plugin config.json.
+echo_config_get() {
+	local key="$1"
+
+	if [[ -n "$_ECHO_CONFIG_JSON" ]]; then
+		local val
+		val=$(printf '%s' "$_ECHO_CONFIG_JSON" | jq -r "${key} // empty" 2>/dev/null) || val=""
+		[[ -n "$val" && "$val" != "null" ]] && { printf '%s' "$val"; return 0; }
+	fi
+
+	if [[ -n "$_ECHO_PLUGIN_CONFIG_JSON" ]]; then
+		local val
+		val=$(printf '%s' "$_ECHO_PLUGIN_CONFIG_JSON" | jq -r ".echo${key} // empty" 2>/dev/null) || val=""
+		[[ -n "$val" && "$val" != "null" ]] && { printf '%s' "$val"; return 0; }
+	fi
+}
+
+echo_config_get_json() {
+	local key="$1"
+
+	if [[ -n "$_ECHO_CONFIG_JSON" ]]; then
+		local val
+		val=$(printf '%s' "$_ECHO_CONFIG_JSON" | jq -c "${key} // empty" 2>/dev/null) || val=""
+		[[ -n "$val" && "$val" != "null" && "$val" != "empty" ]] && { printf '%s' "$val"; return 0; }
+	fi
+
+	if [[ -n "$_ECHO_PLUGIN_CONFIG_JSON" ]]; then
+		local val
+		val=$(printf '%s' "$_ECHO_PLUGIN_CONFIG_JSON" | jq -c ".echo${key} // empty" 2>/dev/null) || val=""
+		[[ -n "$val" && "$val" != "null" && "$val" != "empty" ]] && { printf '%s' "$val"; return 0; }
+	fi
+}
+
+echo_config_enabled() {
+	local val
+	val=$(echo_config_get '.enabled')
+	[[ "$val" == "true" ]]
+}
+
+echo_config_model() {
+	local val
+	val=$(echo_config_get '.evaluation.model')
+	printf '%s' "${val:-claude-haiku-4-5-20251001}"
+}
+
+echo_config_timeout() {
+	local val
+	val=$(echo_config_get '.evaluation.timeout_seconds')
+	printf '%s' "${val:-60}"
+}
+
+echo_config_drift_threshold() {
+	local val
+	val=$(echo_config_get '.drift_threshold')
+	printf '%s' "${val:-0.05}"
+}
+
+# Prints newline-separated list of watch glob patterns.
+echo_config_watch_paths() {
+	local raw
+	raw=$(echo_config_get_json '.watch_paths')
+	if [[ -n "$raw" ]]; then
+		printf '%s' "$raw" | jq -r '.[]' 2>/dev/null
+	else
+		printf 'plugins/*/agents/*.md\n'
+	fi
+}
+
+# Prints newline-separated list of exclude glob patterns.
+echo_config_exclude_paths() {
+	local raw
+	raw=$(echo_config_get_json '.exclude_paths')
+	if [[ -n "$raw" ]]; then
+		printf '%s' "$raw" | jq -r '.[]' 2>/dev/null
+	fi
+	# Always exclude Echo's own tree — hardcoded, not overridable.
+	printf 'plugins/echo/**\n'
+}

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

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# Canonical echo.* event emission.
+# Thin wrapper around the ecosystem plugin's onlooker-event.mjs `emit` mode.
+
+_ECHO_PLUGIN_NAME="echo"
+
+_echo_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
+}
+
+_echo_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'
+}
+
+echo_emit_event() {
+	local event_type="${1:-}"
+	local payload="${2:-}"
+	[[ -z "$event_type" || -z "$payload" ]] && return 1
+
+	local event_js
+	event_js=$(_echo_event_js_path) || {
+		printf 'echo-events: cannot locate onlooker-event.mjs\n' >&2
+		return 1
+	}
+
+	local session_id
+	session_id=$(_echo_session_id)
+
+	local params
+	params=$(jq -n \
+		--arg plugin "$_ECHO_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 stderr_file
+	stderr_file=$(mktemp -t echo-event-err.XXXXXX 2>/dev/null) || stderr_file="/tmp/echo-event-err.$$"
+	event=$(printf '%s' "$params" \
+		| ONLOOKER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}" \
+		  ONLOOKER_PLUGIN_NAME="$_ECHO_PLUGIN_NAME" \
+		  node "$event_js" emit 2>"$stderr_file") || {
+		printf 'echo-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"
+}