@onlooker-community/ecosystem 0.15.2 → 0.17.0

package/plugins/compass/scripts/lib/compass-gate.sh

@@ -0,0 +1,465 @@
+#!/usr/bin/env bash
+# Shared evaluation pipeline for Compass.
+#
+# Called by compass-pre-tool-use.sh (Write/Edit/MultiEdit) and
+# compass-bash-gate.sh (Bash write commands). Contains all gate logic:
+#   1. Skip-glob filter
+#   2. Dir+stem cooldown check
+#   3. Turn budget check
+#   4. Context minimum check
+#   5. Skip sentinel check
+#   6. Symbolic skip layer (reply-to-question pattern)
+#   7. Input sanitization
+#   8. Prior-turn transcript read
+#   9. N=5 parallel evaluator
+#  10. Intervention UX on block
+#
+# Exposes:
+#   compass_run_gate <tool_name> <file_path> <operation> \
+#                   <context_or_command> <session_id> <cwd>
+#
+# Hook contract (Claude Code PreToolUse protocol):
+#   - Always exits 0.
+#   - To block: write {"decision":"block","reason":"..."} to stdout before returning.
+#   - To allow: write nothing to stdout.
+
+# -----------------------------------------------------------------------
+# Helper: update session state (turn_check_count, circuit_breaker).
+# -----------------------------------------------------------------------
+
+_compass_state_file() {
+	local session_id="$1"
+	local onlooker_dir="${ONLOOKER_DIR:-${HOME}/.onlooker}"
+	printf '%s' "${onlooker_dir}/compass/sessions/${session_id}.json"
+}
+
+_compass_state_get() {
+	local session_id="$1"
+	local jq_path="$2"
+	local state_file
+	state_file=$(_compass_state_file "$session_id")
+	[[ -f "$state_file" ]] || { printf ''; return 1; }
+	jq -r "${jq_path} // empty" "$state_file" 2>/dev/null
+}
+
+_compass_state_update() {
+	local session_id="$1"
+	local jq_expr="$2"
+	local state_file
+	state_file=$(_compass_state_file "$session_id")
+	[[ -f "$state_file" ]] || return 1
+	local updated
+	updated=$(jq "$jq_expr" "$state_file" 2>/dev/null) || return 1
+	[[ -n "$updated" ]] && printf '%s' "$updated" > "$state_file"
+}
+
+_compass_increment_turn_count() {
+	local session_id="$1"
+	_compass_state_update "$session_id" '.turn_check_count += 1'
+}
+
+_compass_record_failure() {
+	local session_id="$1"
+	_compass_state_update "$session_id" '
+		.circuit_breaker.consecutive_failures += 1
+	'
+}
+
+_compass_reset_failures() {
+	local session_id="$1"
+	_compass_state_update "$session_id" '
+		.circuit_breaker.consecutive_failures = 0
+	'
+}
+
+_compass_open_circuit() {
+	local session_id="$1"
+	local now
+	now=$(date +%s 2>/dev/null) || now=0
+	_compass_state_update "$session_id" \
+		--argjson now "$now" \
+		'.circuit_breaker.state = "open" | .circuit_breaker.opened_at = $now' \
+		2>/dev/null || \
+	_compass_state_update "$session_id" \
+		".circuit_breaker.state = \"open\" | .circuit_breaker.opened_at = ${now}"
+}
+
+# -----------------------------------------------------------------------
+# Helper: glob matching for skip_globs.
+# -----------------------------------------------------------------------
+_compass_matches_skip_glob() {
+	local file_path="$1"
+	local globs_json="$2"
+	[[ -z "$file_path" || -z "$globs_json" ]] && return 1
+
+	# Convert JSON array to bash array and check each pattern.
+	local globs
+	mapfile -t globs < <(printf '%s' "$globs_json" | jq -r '.[]' 2>/dev/null) || return 1
+
+	local glob
+	for glob in "${globs[@]}"; do
+		# Use bash glob matching (extglob not needed for ** — use case).
+		# Convert ** to a catch-all for simple prefix/suffix matching.
+		local pattern="${glob//\*\*/DOUBLE_STAR}"
+		pattern="${pattern//\*/[^/]*}"
+		pattern="${pattern//DOUBLE_STAR/.*}"
+		if [[ "$file_path" =~ $pattern ]]; then
+			return 0
+		fi
+	done
+	return 1
+}
+
+# -----------------------------------------------------------------------
+# Helper: dir+stem identity (same as compass-record-write.sh).
+# -----------------------------------------------------------------------
+_compass_gate_dir_plus_stem() {
+	local path="$1"
+	[[ -z "$path" ]] && return 1
+	local dir base stem
+	dir=$(dirname "$path" 2>/dev/null) || dir="."
+	base=$(basename "$path" 2>/dev/null) || base="$path"
+	stem="${base%%.*}"
+	[[ -z "$stem" ]] && stem="$base"
+	printf '%s/%s' "$dir" "$stem"
+}
+
+# -----------------------------------------------------------------------
+# Helper: cooldown check.
+# -----------------------------------------------------------------------
+_compass_in_cooldown() {
+	local file_path="$1"
+	local session_id="$2"
+	local cooldown_seconds="$3"
+
+	[[ -z "$file_path" ]] && return 1
+
+	local identity
+	identity=$(_compass_gate_dir_plus_stem "$file_path") || return 1
+
+	local state_file
+	state_file=$(_compass_state_file "$session_id")
+	[[ -f "$state_file" ]] || return 1
+
+	local now
+	now=$(date +%s 2>/dev/null) || now=0
+
+	local entry_ts
+	entry_ts=$(jq -r \
+		--arg identity "$identity" \
+		'.cooldown[] | select(.identity == $identity) | .ts' \
+		"$state_file" 2>/dev/null | tail -1) || entry_ts=""
+
+	[[ -z "$entry_ts" ]] && return 1
+
+	local age=$(( now - entry_ts ))
+	[[ "$age" -le "$cooldown_seconds" ]] && return 0
+	return 1
+}
+
+# -----------------------------------------------------------------------
+# Helper: symbolic skip layer (reply-to-question pattern).
+# -----------------------------------------------------------------------
+_compass_symbolic_skip() {
+	local prior_turn="$1"
+	local context_excerpt="$2"
+
+	[[ -z "$prior_turn" ]] && return 1
+
+	# Condition 1: prior turn contains a numbered list and a question mark.
+	local has_numbered_list has_question
+	has_numbered_list=$(printf '%s' "$prior_turn" \
+		| grep -cE '^\s*[0-9]+[.)]\s+' 2>/dev/null) || has_numbered_list=0
+	has_question=$(printf '%s' "$prior_turn" | grep -c '?' 2>/dev/null) || has_question=0
+
+	[[ "$has_numbered_list" -eq 0 || "$has_question" -eq 0 ]] && return 1
+
+	# Condition 2: context excerpt looks like an option reference or affirmation.
+	local trimmed_context
+	trimmed_context=$(printf '%s' "$context_excerpt" | tr -s ' \t\n' ' ' | sed 's/^ *//;s/ *$//' 2>/dev/null) \
+		|| trimmed_context="$context_excerpt"
+
+	if printf '%s' "$trimmed_context" | grep -qiE \
+		'^(yes|no|both|all|none|either|ok|okay|sure|the (first|second|third|fourth|fifth)|option [0-9]|[0-9]+[.)]?$)' \
+		2>/dev/null; then
+		return 0
+	fi
+
+	return 1
+}
+
+# -----------------------------------------------------------------------
+# Intervention output — block with structured message.
+# -----------------------------------------------------------------------
+_compass_intervention() {
+	local tool_name="$1"
+	local file_path="$2"
+	local confidence="$3"
+	local stddev="$4"
+	local primary_concern="$5"
+	local rationale="$6"
+	local session_id="$7"
+	local confidence_threshold="$8"
+	local stddev_threshold="$9"
+
+	local block_reason=""
+	local passed_conf passed_std
+	passed_conf=$(awk "BEGIN {exit !(${confidence:-0} >= ${confidence_threshold:-0.65})}" 2>/dev/null && echo true || echo false)
+	passed_std=$(awk "BEGIN {exit !(${stddev:-1} <= ${stddev_threshold:-0.20})}" 2>/dev/null && echo true || echo false)
+
+	if [[ "$passed_conf" != "true" && "$passed_std" != "true" ]]; then
+		block_reason="low confidence and high evaluator disagreement"
+	elif [[ "$passed_conf" != "true" ]]; then
+		block_reason="low confidence (${confidence} < ${confidence_threshold})"
+	else
+		block_reason="high evaluator disagreement (stddev ${stddev} > ${stddev_threshold})"
+	fi
+
+	local message
+	message=$(printf \
+'Compass blocked this write — %s.
+
+  File: %s
+  Tool: %s
+  Confidence: %s  Stddev: %s  Concern: %s
+  Evaluator rationale: %s
+
+Choose a path:
+  • Type compass: proceed  — override and allow this write
+  • Provide more context   — compass will re-evaluate once with your clarification
+  • Type compass: cancel   — abandon this write' \
+		"$block_reason" "$file_path" "$tool_name" \
+		"${confidence:-n/a}" "${stddev:-n/a}" "${primary_concern:-none}" \
+		"${rationale:-(none)}")
+
+	jq -n \
+		--arg message "$message" \
+		--arg decision "block" \
+		'{"decision": $decision, "reason": $message}' 2>/dev/null \
+		|| printf '{"decision":"block","reason":"Compass blocked this write — intent unclear."}'
+}
+
+# -----------------------------------------------------------------------
+# Main gate function.
+# $1 — tool_name   (Write | Edit | MultiEdit | Bash)
+# $2 — file_path   (may be empty for Bash)
+# $3 — operation   (write | edit | multi_edit | bash_write)
+# $4 — context     (context excerpt or bash command string)
+# $5 — session_id
+# $6 — cwd
+# -----------------------------------------------------------------------
+compass_run_gate() {
+	local tool_name="$1"
+	local file_path="$2"
+	local operation="$3"
+	local context="$4"
+	local session_id="${5:-unknown}"
+	local cwd="${6:-}"
+
+	local _allow_exit=0
+	local _block_exit=0
+
+	# ---- Rule 1: skip sentinel ----------------------------------------
+	if printf '%s' "${context}${file_path}" | grep -qF '[compass:skip]' 2>/dev/null; then
+		compass_emit_event "compass.check.skipped" \
+			"$(jq -n --arg r "skip_sentinel" --arg f "$file_path" \
+			'{reason:$r,file_path:$f}' 2>/dev/null || echo '{}')" 2>/dev/null || true
+		return $_allow_exit
+	fi
+
+	# ---- Rule 2: skip_globs -------------------------------------------
+	local skip_globs_json
+	skip_globs_json=$(compass_config_get_json '.compass.skip_globs') || skip_globs_json="[]"
+	if [[ -n "$file_path" ]] && _compass_matches_skip_glob "$file_path" "$skip_globs_json"; then
+		compass_emit_event "compass.check.skipped" \
+			"$(jq -n --arg r "skip_glob" --arg f "$file_path" \
+			'{reason:$r,file_path:$f}' 2>/dev/null || echo '{}')" 2>/dev/null || true
+		return $_allow_exit
+	fi
+
+	# ---- Rule 3: dir+stem cooldown ------------------------------------
+	local cooldown_seconds
+	cooldown_seconds=$(compass_config_get '.compass.cooldown.seconds')
+	cooldown_seconds="${cooldown_seconds:-120}"
+	if [[ -n "$file_path" ]] && _compass_in_cooldown "$file_path" "$session_id" "$cooldown_seconds"; then
+		compass_emit_event "compass.check.skipped" \
+			"$(jq -n --arg r "dir_plus_stem_cooldown" --arg f "$file_path" \
+			'{reason:$r,file_path:$f}' 2>/dev/null || echo '{}')" 2>/dev/null || true
+		return $_allow_exit
+	fi
+
+	# ---- Rule 4: turn budget ------------------------------------------
+	local max_checks
+	max_checks=$(compass_config_get '.compass.max_checks_per_turn')
+	max_checks="${max_checks:-3}"
+	local current_count
+	current_count=$(_compass_state_get "$session_id" '.turn_check_count') || current_count=0
+	current_count="${current_count:-0}"
+	if (( current_count >= max_checks )); then
+		compass_emit_event "compass.check.skipped" \
+			"$(jq -n --arg r "turn_budget_exhausted" --arg f "$file_path" \
+			'{reason:$r,file_path:$f}' 2>/dev/null || echo '{}')" 2>/dev/null || true
+		return $_allow_exit
+	fi
+
+	# ---- Rule 5: context minimum -------------------------------------
+	local min_context_chars
+	min_context_chars=$(compass_config_get '.compass.min_context_chars')
+	min_context_chars="${min_context_chars:-80}"
+	local context_len="${#context}"
+	if (( context_len < min_context_chars )); then
+		compass_emit_event "compass.check.skipped" \
+			"$(jq -n --arg r "insufficient_context" --arg f "$file_path" \
+			'{reason:$r,file_path:$f}' 2>/dev/null || echo '{}')" 2>/dev/null || true
+		return $_allow_exit
+	fi
+
+	# ---- Rule 6: circuit breaker -------------------------------------
+	local cb_enabled cb_state cb_failures cb_threshold cb_open_duration
+	cb_enabled=$(compass_config_get '.compass.circuit_breaker.enabled')
+	cb_enabled="${cb_enabled:-true}"
+	if [[ "$cb_enabled" == "true" ]]; then
+		cb_state=$(_compass_state_get "$session_id" '.circuit_breaker.state') || cb_state="closed"
+		cb_state="${cb_state:-closed}"
+		if [[ "$cb_state" == "open" ]]; then
+			cb_open_duration=$(compass_config_get '.compass.circuit_breaker.open_duration_seconds')
+			cb_open_duration="${cb_open_duration:-300}"
+			local opened_at
+			opened_at=$(_compass_state_get "$session_id" '.circuit_breaker.opened_at') || opened_at=0
+			opened_at="${opened_at:-0}"
+			local now
+			now=$(date +%s 2>/dev/null) || now=0
+			local open_age=$(( now - opened_at ))
+			if (( open_age < cb_open_duration )); then
+				compass_emit_event "compass.check.skipped" \
+					"$(jq -n --arg r "circuit_open" --arg f "$file_path" \
+					'{reason:$r,file_path:$f}' 2>/dev/null || echo '{}')" 2>/dev/null || true
+				return $_allow_exit
+			else
+				# TTL expired — close the circuit and proceed.
+				_compass_state_update "$session_id" \
+					'.circuit_breaker.state = "closed" | .circuit_breaker.opened_at = null' \
+					2>/dev/null || true
+			fi
+		fi
+	fi
+
+	# ---- Increment turn check count ----------------------------------
+	_compass_increment_turn_count "$session_id" 2>/dev/null || true
+
+	# ---- Read prior assistant turn -----------------------------------
+	local prior_turn_chars_max transcript_max_age
+	prior_turn_chars_max=$(compass_config_get '.compass.transcript.prior_turn_chars_max')
+	prior_turn_chars_max="${prior_turn_chars_max:-800}"
+	transcript_max_age=$(compass_config_get '.compass.transcript.transcript_max_age_seconds')
+	transcript_max_age="${transcript_max_age:-300}"
+
+	local prior_turn=""
+	prior_turn=$(compass_read_prior_turn "$session_id" "$prior_turn_chars_max" "$transcript_max_age") \
+		|| prior_turn=""
+
+	# ---- Symbolic skip layer -----------------------------------------
+	local skip_reply_enabled
+	skip_reply_enabled=$(compass_config_get '.compass.skip_patterns.reply_to_question.enabled')
+	skip_reply_enabled="${skip_reply_enabled:-true}"
+	if [[ "$skip_reply_enabled" == "true" ]] && _compass_symbolic_skip "$prior_turn" "$context"; then
+		compass_emit_event "compass.check.skipped" \
+			"$(jq -n --arg r "reply_to_question_pattern" --arg f "$file_path" \
+			'{reason:$r,file_path:$f}' 2>/dev/null || echo '{}')" 2>/dev/null || true
+		return $_allow_exit
+	fi
+
+	# ---- Sanitize context excerpt ------------------------------------
+	local context_chars_max
+	context_chars_max=$(compass_config_get '.compass.context_chars_max')
+	context_chars_max="${context_chars_max:-600}"
+	local sanitized_context
+	sanitized_context=$(compass_sanitize "$context" "$context_chars_max")
+
+	local sanitized_path
+	sanitized_path=$(compass_sanitize "$file_path" 0)
+
+	# ---- Run evaluator -----------------------------------------------
+	local eval_result eval_exit
+	eval_result=$(compass_evaluate \
+		"$tool_name" "$sanitized_path" "$operation" \
+		"$prior_turn" "$sanitized_context" "$session_id")
+	eval_exit=$?
+
+	local decision confidence stddev primary_concern rationale
+	decision=$(printf '%s' "$eval_result" | jq -r '.decision // "error"' 2>/dev/null) || decision="error"
+	confidence=$(printf '%s' "$eval_result" | jq -r '.confidence // ""' 2>/dev/null) || confidence=""
+	stddev=$(printf '%s' "$eval_result" | jq -r '.stddev // ""' 2>/dev/null) || stddev=""
+	primary_concern=$(printf '%s' "$eval_result" | jq -r '.primary_concern // "none"' 2>/dev/null) || primary_concern="none"
+	rationale=$(printf '%s' "$eval_result" | jq -r '.rationale // ""' 2>/dev/null) || rationale=""
+
+	local had_prior_turn="false"
+	[[ -n "$prior_turn" ]] && had_prior_turn="true"
+
+	local confidence_threshold stddev_threshold
+	confidence_threshold=$(compass_config_get '.compass.confidence_threshold')
+	confidence_threshold="${confidence_threshold:-0.65}"
+	stddev_threshold=$(compass_config_get '.compass.stddev_threshold')
+	stddev_threshold="${stddev_threshold:-0.20}"
+
+	if [[ "$decision" == "error" ]]; then
+		local error_policy
+		error_policy=$(compass_config_get '.compass.error_policy')
+		error_policy="${error_policy:-closed}"
+
+		_compass_record_failure "$session_id" 2>/dev/null || true
+
+		cb_failures=$(_compass_state_get "$session_id" '.circuit_breaker.consecutive_failures') \
+			|| cb_failures=0
+		cb_failures="${cb_failures:-0}"
+		cb_threshold=$(compass_config_get '.compass.circuit_breaker.consecutive_failures_to_open')
+		cb_threshold="${cb_threshold:-3}"
+		if [[ "$cb_enabled" == "true" ]] && (( cb_failures >= cb_threshold )); then
+			_compass_open_circuit "$session_id" 2>/dev/null || true
+		fi
+
+		compass_emit_event "compass.check.skipped" \
+			"$(jq -n --arg r "sampler_error" --arg f "$file_path" \
+			'{reason:$r,file_path:$f}' 2>/dev/null || echo '{}')" 2>/dev/null || true
+
+		[[ "$error_policy" == "open" ]] && return $_allow_exit
+		# fail-closed: block
+		_compass_intervention \
+			"$tool_name" "$file_path" "" "" "none" \
+			"Evaluator failed — cannot verify intent clarity." \
+			"$session_id" "$confidence_threshold" "$stddev_threshold"
+		return $_block_exit
+	fi
+
+	# ---- Emit result event -------------------------------------------
+	if [[ "$decision" == "pass" ]]; then
+		_compass_reset_failures "$session_id" 2>/dev/null || true
+		compass_emit_event "compass.check.passed" \
+			"$(jq -n \
+				--arg f "$file_path" \
+				--arg t "$tool_name" \
+				--arg hpt "$had_prior_turn" \
+				--argjson conf "${confidence:-0}" \
+				--argjson std "${stddev:-0}" \
+				'{confidence:$conf,stddev:$std,file_path:$f,tool_name:$t,had_prior_turn:($hpt=="true")}' \
+				2>/dev/null || echo '{}')" 2>/dev/null || true
+		return $_allow_exit
+	fi
+
+	# decision == fail
+	compass_emit_event "compass.check.failed" \
+		"$(jq -n \
+			--arg f "$file_path" \
+			--arg concern "$primary_concern" \
+			--argjson conf "${confidence:-0}" \
+			--argjson std "${stddev:-0}" \
+			'{confidence:$conf,stddev:$std,primary_concern:$concern,file_path:$f}' \
+			2>/dev/null || echo '{}')" 2>/dev/null || true
+
+	_compass_intervention \
+		"$tool_name" "$file_path" \
+		"${confidence:-0}" "${stddev:-0}" \
+		"$primary_concern" "$rationale" \
+		"$session_id" "$confidence_threshold" "$stddev_threshold"
+	return $_block_exit
+}

package/plugins/compass/scripts/lib/compass-sanitizer.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# Input sanitization for Compass evaluator-bound fields.
+#
+# Applied before any user-supplied content is interpolated into the
+# evaluator prompt. Prevents prompt injection via crafted file names,
+# file contents, or conversation text.
+#
+# Exposes:
+#   compass_sanitize <string> <max_chars>   # echoes sanitized, truncated string
+#   compass_sanitize_field <field> <string> # echoes sanitized string for a named field
+#
+# Sanitization steps (applied in order):
+#   1. Null-byte removal
+#   2. Control-character removal (0x00–0x1F and 0x7F, except \t and \n)
+#   3. XML delimiter stripping (evaluator prompt tag sequences → [STRIPPED])
+#   4. Truncation to max_chars
+
+# Tags that, if present in user-supplied data, would inject into the evaluator prompt.
+_COMPASS_STRIP_SEQUENCES=(
+	"<prior_assistant_turn>"
+	"</prior_assistant_turn>"
+	"<context_excerpt>"
+	"</context_excerpt>"
+	"<tool_input>"
+	"</tool_input>"
+	"<instructions>"
+	"</instructions>"
+	"<|"
+	"[INST]"
+	"[/INST]"
+	"<<SYS>>"
+	"<</SYS>>"
+)
+
+# Remove null bytes and ASCII control characters except \t (0x09) and \n (0x0A).
+_compass_strip_control_chars() {
+	local input="$1"
+	# tr: delete bytes 0x00-0x08, 0x0B-0x1F, 0x7F
+	printf '%s' "$input" \
+		| tr -d '\000-\010\013-\037\177' \
+		2>/dev/null
+}
+
+# Replace all occurrences of a literal string with [STRIPPED].
+_compass_strip_literal() {
+	local input="$1"
+	local needle="$2"
+	# Use printf + sed; escape needle for BRE (basic regex)
+	local escaped_needle
+	escaped_needle=$(printf '%s' "$needle" | sed 's/[[\.*^$()+?{|]/\\&/g' 2>/dev/null) || escaped_needle="$needle"
+	printf '%s' "$input" | sed "s/${escaped_needle}/[STRIPPED]/g" 2>/dev/null
+}
+
+# Truncate a string to at most max_chars UTF-8 characters.
+_compass_truncate() {
+	local input="$1"
+	local max_chars="${2:-0}"
+	if [[ "$max_chars" -le 0 ]]; then
+		printf '%s' "$input"
+		return
+	fi
+	printf '%s' "$input" | cut -c "1-${max_chars}" 2>/dev/null
+}
+
+# Full sanitization pipeline. Echoes the sanitized string.
+#   $1 — raw input string
+#   $2 — max chars (0 = no truncation)
+compass_sanitize() {
+	local input="$1"
+	local max_chars="${2:-0}"
+
+	local s
+	s=$(_compass_strip_control_chars "$input")
+
+	local seq
+	for seq in "${_COMPASS_STRIP_SEQUENCES[@]}"; do
+		s=$(_compass_strip_literal "$s" "$seq")
+	done
+
+	s=$(_compass_truncate "$s" "$max_chars")
+	printf '%s' "$s"
+}

package/plugins/compass/scripts/lib/compass-transcript.sh

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+# Prior assistant turn reader for Compass.
+#
+# Resolves the most recent assistant turn from the session transcript so
+# the evaluator can operate on the pair {prior_assistant_turn, context}
+# rather than context alone — avoiding false positives on question-answer
+# turns (see ADR-001).
+#
+# Resolution order:
+#   1. CLAUDE_TRANSCRIPT_PATH env var → parse as JSONL, find most recent
+#      entry with role:"assistant"
+#   2. Onlooker JSONL event log (~/.onlooker/logs/onlooker-events.jsonl)
+#      filtered by session_id and event_type:"session.prompt", most recent
+#      assistant-role entry
+#   3. Empty string — degrades gracefully; evaluator runs on context alone
+#
+# Exposes:
+#   compass_read_prior_turn <session_id> <max_chars> <max_age_seconds>
+#     Echoes the prior assistant turn text (possibly empty).
+
+_compass_transcript_from_path() {
+	local transcript_path="$1"
+	local session_id="$2"
+	local max_age_seconds="$3"
+
+	[[ -f "$transcript_path" ]] || return 1
+
+	local now
+	now=$(date +%s 2>/dev/null) || now=0
+
+	# Parse JSONL: find most recent entry with role=assistant within max_age_seconds.
+	# Each line is a JSON object. We want the last one matching our criteria.
+	local prior_turn=""
+	local line
+	while IFS= read -r line; do
+		[[ -z "$line" ]] && continue
+		local role ts content
+		role=$(printf '%s' "$line" | jq -r '.role // empty' 2>/dev/null) || continue
+		[[ "$role" == "assistant" ]] || continue
+
+		# Age check — skip entries older than max_age_seconds.
+		if [[ "$max_age_seconds" -gt 0 ]]; then
+			ts=$(printf '%s' "$line" | jq -r '.timestamp // empty' 2>/dev/null) || ts=""
+			if [[ -n "$ts" ]]; then
+				local entry_time
+				entry_time=$(date -d "$ts" +%s 2>/dev/null) \
+					|| entry_time=$(date -jf '%Y-%m-%dT%H:%M:%SZ' "$ts" +%s 2>/dev/null) \
+					|| entry_time=0
+				local age=$(( now - entry_time ))
+				[[ "$age" -gt "$max_age_seconds" ]] && continue
+			fi
+		fi
+
+		content=$(printf '%s' "$line" | jq -r '.content // .text // empty' 2>/dev/null) || continue
+		[[ -n "$content" ]] && prior_turn="$content"
+	done < "$transcript_path"
+
+	[[ -n "$prior_turn" ]] || return 1
+	printf '%s' "$prior_turn"
+}
+
+_compass_transcript_from_event_log() {
+	local session_id="$1"
+	local max_age_seconds="$2"
+	local log_path="${ONLOOKER_EVENTS_LOG:-${ONLOOKER_DIR:-$HOME/.onlooker}/logs/onlooker-events.jsonl}"
+
+	[[ -f "$log_path" ]] || return 1
+	[[ -n "$session_id" && "$session_id" != "unknown" ]] || return 1
+
+	local now
+	now=$(date +%s 2>/dev/null) || now=0
+
+	local prior_turn=""
+	local line
+	while IFS= read -r line; do
+		[[ -z "$line" ]] && continue
+
+		local sid etype role
+		sid=$(printf '%s' "$line" | jq -r '.session_id // empty' 2>/dev/null) || continue
+		[[ "$sid" == "$session_id" ]] || continue
+
+		etype=$(printf '%s' "$line" | jq -r '.event_type // empty' 2>/dev/null) || continue
+		[[ "$etype" == "session.prompt" ]] || continue
+
+		role=$(printf '%s' "$line" | jq -r '.payload.role // empty' 2>/dev/null) || continue
+		[[ "$role" == "assistant" ]] || continue
+
+		if [[ "$max_age_seconds" -gt 0 ]]; then
+			local ts entry_time
+			ts=$(printf '%s' "$line" | jq -r '.timestamp // empty' 2>/dev/null) || ts=""
+			if [[ -n "$ts" ]]; then
+				entry_time=$(date -d "$ts" +%s 2>/dev/null) \
+					|| entry_time=$(date -jf '%Y-%m-%dT%H:%M:%SZ' "$ts" +%s 2>/dev/null) \
+					|| entry_time=0
+				local age=$(( now - entry_time ))
+				[[ "$age" -gt "$max_age_seconds" ]] && continue
+			fi
+		fi
+
+		local content
+		content=$(printf '%s' "$line" | jq -r '.payload.content // .payload.text // empty' 2>/dev/null) || continue
+		[[ -n "$content" ]] && prior_turn="$content"
+	done < "$log_path"
+
+	[[ -n "$prior_turn" ]] || return 1
+	printf '%s' "$prior_turn"
+}
+
+# Read the prior assistant turn.
+#   $1 — session_id
+#   $2 — max_chars (from config: transcript.prior_turn_chars_max)
+#   $3 — max_age_seconds (from config: transcript.transcript_max_age_seconds)
+# Echoes the sanitized, truncated prior assistant turn, or empty string.
+compass_read_prior_turn() {
+	local session_id="${1:-unknown}"
+	local max_chars="${2:-800}"
+	local max_age_seconds="${3:-300}"
+
+	local raw=""
+
+	# Source 1: CLAUDE_TRANSCRIPT_PATH
+	if [[ -n "${CLAUDE_TRANSCRIPT_PATH:-}" ]]; then
+		raw=$(_compass_transcript_from_path "$CLAUDE_TRANSCRIPT_PATH" "$session_id" "$max_age_seconds") || raw=""
+	fi
+
+	# Source 2: Onlooker event log
+	if [[ -z "$raw" ]]; then
+		raw=$(_compass_transcript_from_event_log "$session_id" "$max_age_seconds") || raw=""
+	fi
+
+	[[ -z "$raw" ]] && return 0
+
+	# Sanitize and truncate — compass-sanitizer.sh must be sourced by the caller.
+	compass_sanitize "$raw" "$max_chars"
+}