@onlooker-community/ecosystem 0.24.0 → 0.25.1

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

@@ -0,0 +1,249 @@
+#!/usr/bin/env bash
+# Assayer Stop hook.
+#
+# Triggered by Stop. Off by default — gated on assayer.enabled in config.
+# When enabled, it reads the just-finished session's transcript, extracts the
+# agent's testable success claims from its final message, and cross-checks each
+# against the actual Bash command results in the same transcript. Each claim is
+# classified corroborated / contradicted / unverified and emitted as an event.
+#
+# Hook contract:
+#   - Always exits 0. Advisory only — never blocks Stop.
+#   - Skips silently if disabled, no git context, no transcript, or no claims.
+#   - Recursion guard: exits immediately if ASSAYER_NESTED=1 to prevent a
+#     claude -p subprocess from re-triggering this hook on its own Stop.
+#   - Errors from `claude -p` are swallowed; worst case is no audit written.
+
+set -uo pipefail
+
+# Recursion guard — must be first.
+[[ "${ASSAYER_NESTED:-}" == "1" ]] && exit 0
+export ASSAYER_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/assayer-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/assayer-config.sh"
+# shellcheck source=../lib/assayer-project-key.sh
+source "${PLUGIN_ROOT}/scripts/lib/assayer-project-key.sh"
+# shellcheck source=../lib/assayer-ulid.sh
+source "${PLUGIN_ROOT}/scripts/lib/assayer-ulid.sh"
+# shellcheck source=../lib/assayer-transcript.sh
+source "${PLUGIN_ROOT}/scripts/lib/assayer-transcript.sh"
+# shellcheck source=../lib/assayer-extract.sh
+source "${PLUGIN_ROOT}/scripts/lib/assayer-extract.sh"
+# shellcheck source=../lib/assayer-verify.sh
+source "${PLUGIN_ROOT}/scripts/lib/assayer-verify.sh"
+# shellcheck source=../lib/assayer-events.sh
+CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" source "${PLUGIN_ROOT}/scripts/lib/assayer-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=""
+TRANSCRIPT_PATH=$(printf '%s' "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null) || TRANSCRIPT_PATH=""
+[[ -z "$TRANSCRIPT_PATH" ]] && TRANSCRIPT_PATH="${CLAUDE_TRANSCRIPT_PATH:-}"
+
+export _HOOK_SESSION_ID="${SESSION_ID:-unknown}"
+
+_done() { exit 0; }
+
+# ---------------------------------------------------------------------------
+# Config + prerequisites
+# ---------------------------------------------------------------------------
+
+REPO_ROOT=$(assayer_project_repo_root "$CWD")
+[[ -z "$REPO_ROOT" ]] && _done
+
+CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" assayer_config_load "$REPO_ROOT"
+assayer_config_enabled || _done
+
+PROJECT_KEY=$(assayer_project_key "$CWD")
+[[ -z "$PROJECT_KEY" ]] && _done
+
+command -v claude >/dev/null 2>&1 || _done
+command -v jq >/dev/null 2>&1 || _done
+
+[[ -f "$TRANSCRIPT_PATH" ]] || _done
+
+# ---------------------------------------------------------------------------
+# Read transcript: final message + command evidence
+# ---------------------------------------------------------------------------
+
+FINAL_MESSAGE_CHARS=$(CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" assayer_config_final_message_chars)
+FINAL_MESSAGE=$(assayer_final_assistant_message "$TRANSCRIPT_PATH" "$FINAL_MESSAGE_CHARS")
+[[ -z "$FINAL_MESSAGE" ]] && _done
+
+COMMANDS=$(assayer_collect_commands "$TRANSCRIPT_PATH")
+COMMAND_COUNT=$(printf '%s' "$COMMANDS" | jq 'length' 2>/dev/null) || COMMAND_COUNT=0
+
+# ---------------------------------------------------------------------------
+# Extract claims via claude -p
+# ---------------------------------------------------------------------------
+
+MAX_CLAIMS=$(CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" assayer_config_max_claims)
+MIN_CONFIDENCE=$(CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" assayer_config_min_confidence)
+EVAL_MODEL=$(CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" assayer_config_model)
+TIMEOUT_SECS=$(CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" assayer_config_timeout)
+
+PROMPT_FILE=$(mktemp -t assayer-prompt.XXXXXX 2>/dev/null) || PROMPT_FILE="/tmp/assayer-prompt.$$"
+trap 'rm -f "$PROMPT_FILE"' EXIT
+assayer_build_extraction_prompt "$FINAL_MESSAGE" "$MAX_CLAIMS" >"$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" ]] && _done
+
+CLAIMS=$(assayer_parse_claims "$RESPONSE")
+CLAIM_COUNT=$(printf '%s' "$CLAIMS" | jq 'length' 2>/dev/null) || CLAIM_COUNT=0
+
+# ---------------------------------------------------------------------------
+# Audit
+# ---------------------------------------------------------------------------
+
+AUDIT_ID=$(assayer_ulid)
+AUDIT_START=$(python3 -c 'import time; print(int(time.time()*1000))' 2>/dev/null || echo 0)
+
+started_payload=$(jq -n \
+	--arg audit_id "$AUDIT_ID" \
+	--argjson claim_count "$CLAIM_COUNT" \
+	--arg trigger "stop" \
+	--argjson command_count "${COMMAND_COUNT:-0}" \
+	'{audit_id: $audit_id, claim_count: $claim_count, trigger: $trigger, command_count: $command_count}')
+assayer_emit_event "assayer.audit.started" "$started_payload" || true
+
+ONLOOKER_BASE="${ONLOOKER_DIR:-$HOME/.onlooker}"
+ASSAYER_DIR="${ONLOOKER_BASE}/assayer/${PROJECT_KEY}"
+mkdir -p "$ASSAYER_DIR" 2>/dev/null || true
+
+count_corroborated=0
+count_contradicted=0
+count_unverified=0
+checked_claims="[]"
+
+while IFS= read -r claim; do
+	[[ -z "$claim" ]] && continue
+
+	# Confidence floor — skip low-confidence extractions. Compare with awk via
+	# -v bindings (not string-interpolated into code), so an LLM- or
+	# config-supplied value is treated as a number and a non-numeric value
+	# degrades to 0 instead of executing as code.
+	conf=$(printf '%s' "$claim" | jq -r '.confidence // 0.6' 2>/dev/null) || conf="0.6"
+	if awk -v a="$conf" -v b="$MIN_CONFIDENCE" 'BEGIN { exit !(a >= b) }' 2>/dev/null; then
+		keep=1
+	else
+		keep=0
+	fi
+	[[ "$keep" != "1" ]] && continue
+
+	claim_text=$(printf '%s' "$claim" | jq -r '.text // ""' 2>/dev/null) || claim_text=""
+	claim_type=$(printf '%s' "$claim" | jq -r '.type // "generic"' 2>/dev/null) || claim_type="generic"
+	[[ -z "$claim_text" ]] && continue
+
+	verdict_obj=$(assayer_classify_claim "$claim" "$COMMANDS")
+	verdict=$(printf '%s' "$verdict_obj" | jq -r '.verdict // "unverified"' 2>/dev/null) || verdict="unverified"
+
+	case "$verdict" in
+	contradicted)
+		count_contradicted=$((count_contradicted + 1))
+		evidence_command=$(printf '%s' "$verdict_obj" | jq -r '.evidence_command // ""' 2>/dev/null) || evidence_command=""
+		excerpt=$(printf '%s' "$verdict_obj" | jq -r '.excerpt // ""' 2>/dev/null) || excerpt=""
+		contradicted_payload=$(jq -n \
+			--arg audit_id "$AUDIT_ID" \
+			--arg claim "$claim_text" \
+			--arg claim_type "$claim_type" \
+			--arg evidence_command "$evidence_command" \
+			--arg result_excerpt "$excerpt" \
+			--argjson confidence "$conf" \
+			'{audit_id: $audit_id, claim: $claim, claim_type: $claim_type,
+			  evidence_command: $evidence_command, result_excerpt: $result_excerpt,
+			  confidence: $confidence}')
+		assayer_emit_event "assayer.claim.contradicted" "$contradicted_payload" || true
+		;;
+	corroborated)
+		count_corroborated=$((count_corroborated + 1))
+		;;
+	*)
+		count_unverified=$((count_unverified + 1))
+		reason=$(printf '%s' "$verdict_obj" | jq -r '.reason // "no_evidence"' 2>/dev/null) || reason="no_evidence"
+		unverified_payload=$(jq -n \
+			--arg audit_id "$AUDIT_ID" \
+			--arg claim "$claim_text" \
+			--arg claim_type "$claim_type" \
+			--arg reason "$reason" \
+			'{audit_id: $audit_id, claim: $claim, claim_type: $claim_type, reason: $reason}')
+		assayer_emit_event "assayer.claim.unverified" "$unverified_payload" || true
+		;;
+	esac
+
+	checked_claims=$(printf '%s' "$checked_claims" | jq -c \
+		--arg text "$claim_text" \
+		--arg verdict "$verdict" \
+		'. + [{text: $text, verdict: $verdict}]' 2>/dev/null) || true
+done < <(printf '%s' "$CLAIMS" | jq -c '.[]' 2>/dev/null)
+
+# ---------------------------------------------------------------------------
+# Audit summary
+# ---------------------------------------------------------------------------
+
+AUDIT_END=$(python3 -c 'import time; print(int(time.time()*1000))' 2>/dev/null || echo 0)
+DURATION_MS=$((AUDIT_END - AUDIT_START))
+[[ "$DURATION_MS" -lt 0 ]] && DURATION_MS=0
+
+VERDICT=$(assayer_audit_verdict "$count_contradicted" "$count_corroborated" "$count_unverified")
+
+complete_payload=$(jq -n \
+	--arg audit_id "$AUDIT_ID" \
+	--argjson claim_count "$CLAIM_COUNT" \
+	--argjson corroborated "$count_corroborated" \
+	--argjson contradicted "$count_contradicted" \
+	--argjson unverified "$count_unverified" \
+	--arg verdict "$VERDICT" \
+	--argjson duration_ms "$DURATION_MS" \
+	'{audit_id: $audit_id, claim_count: $claim_count,
+	  corroborated: $corroborated, contradicted: $contradicted,
+	  unverified: $unverified, verdict: $verdict, duration_ms: $duration_ms}')
+assayer_emit_event "assayer.audit.complete" "$complete_payload" || true
+
+# Advisory file for review in the next session.
+SAFE_SESSION_ID=$(printf '%s' "${SESSION_ID:-unknown}" | tr -c 'a-zA-Z0-9-' '_')
+jq -n \
+	--arg audit_id "$AUDIT_ID" \
+	--arg session_id "${SESSION_ID:-unknown}" \
+	--argjson claim_count "$CLAIM_COUNT" \
+	--argjson corroborated "$count_corroborated" \
+	--argjson contradicted "$count_contradicted" \
+	--argjson unverified "$count_unverified" \
+	--arg verdict "$VERDICT" \
+	--argjson claims "$checked_claims" \
+	'{audit_id: $audit_id, session_id: $session_id, claim_count: $claim_count,
+	  corroborated: $corroborated, contradicted: $contradicted,
+	  unverified: $unverified, verdict: $verdict, claims: $claims}' \
+	>"${ASSAYER_DIR}/audit-${SAFE_SESSION_ID}.json" 2>/dev/null || true
+
+_done

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

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# Config loading for Assayer.
+# Reads the repo's .claude/settings.json assayer.* keys, falling back to the
+# plugin's own config.json defaults.
+
+_ASSAYER_CONFIG_JSON=""
+_ASSAYER_PLUGIN_CONFIG_JSON=""
+
+assayer_config_load() {
+	local repo_root="${1:-}"
+
+	_ASSAYER_PLUGIN_CONFIG_JSON=""
+	local plugin_config="${CLAUDE_PLUGIN_ROOT:-}/config.json"
+	if [[ -f "$plugin_config" ]]; then
+		_ASSAYER_PLUGIN_CONFIG_JSON=$(cat "$plugin_config" 2>/dev/null) || _ASSAYER_PLUGIN_CONFIG_JSON=""
+	fi
+
+	_ASSAYER_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 block
+			block=$(printf '%s' "$settings" | jq -c '.assayer // empty' 2>/dev/null) || block=""
+			[[ -n "$block" ]] && _ASSAYER_CONFIG_JSON="$block"
+		fi
+	fi
+}
+
+# Get a single scalar value. Checks settings.json first, then plugin config.json.
+assayer_config_get() {
+	local key="$1"
+
+	if [[ -n "$_ASSAYER_CONFIG_JSON" ]]; then
+		local val
+		val=$(printf '%s' "$_ASSAYER_CONFIG_JSON" | jq -r "${key} // empty" 2>/dev/null) || val=""
+		[[ -n "$val" && "$val" != "null" ]] && {
+			printf '%s' "$val"
+			return 0
+		}
+	fi
+
+	if [[ -n "$_ASSAYER_PLUGIN_CONFIG_JSON" ]]; then
+		local val
+		val=$(printf '%s' "$_ASSAYER_PLUGIN_CONFIG_JSON" | jq -r ".assayer${key} // empty" 2>/dev/null) || val=""
+		[[ -n "$val" && "$val" != "null" ]] && {
+			printf '%s' "$val"
+			return 0
+		}
+	fi
+}
+
+assayer_config_enabled() {
+	local val
+	val=$(assayer_config_get '.enabled')
+	[[ "$val" == "true" ]]
+}
+
+assayer_config_model() {
+	local val
+	val=$(assayer_config_get '.evaluation.model')
+	printf '%s' "${val:-claude-haiku-4-5-20251001}"
+}
+
+assayer_config_timeout() {
+	local val
+	val=$(assayer_config_get '.evaluation.timeout_seconds')
+	printf '%s' "${val:-60}"
+}
+
+assayer_config_max_claims() {
+	local val
+	val=$(assayer_config_get '.max_claims')
+	printf '%s' "${val:-12}"
+}
+
+assayer_config_min_confidence() {
+	local val
+	val=$(assayer_config_get '.min_confidence')
+	printf '%s' "${val:-0.5}"
+}
+
+assayer_config_final_message_chars() {
+	local val
+	val=$(assayer_config_get '.final_message_chars')
+	printf '%s' "${val:-6000}"
+}

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

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# Canonical assayer.* event emission.
+# Thin wrapper around the ecosystem plugin's onlooker-event.mjs `emit` mode.
+# Every emission is validated against @onlooker-community/schema before being
+# appended to ~/.onlooker/logs/onlooker-events.jsonl.
+#
+# Usage:
+#   assayer_emit_event "assayer.audit.started" '{"audit_id":"...","claim_count":3}'
+
+_ASSAYER_PLUGIN_NAME="assayer"
+
+_assayer_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
+}
+
+_assayer_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 assayer.* event. Returns 0 on success, non-zero on failure.
+assayer_emit_event() {
+	local event_type="${1:-}"
+	local payload="${2:-}"
+
+	[[ -z "$event_type" || -z "$payload" ]] && return 1
+
+	local event_js
+	event_js=$(_assayer_event_js_path) || {
+		printf 'assayer-events: cannot locate onlooker-event.mjs\n' >&2
+		return 1
+	}
+
+	local session_id
+	session_id=$(_assayer_session_id)
+
+	local params
+	params=$(jq -n \
+		--arg plugin "$_ASSAYER_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 stderr_file
+	stderr_file=$(mktemp -t assayer-event-err.XXXXXX 2>/dev/null) || stderr_file="/tmp/assayer-event-err.$$"
+	event=$(printf '%s' "$params" \
+		| ONLOOKER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}" \
+			ONLOOKER_PLUGIN_NAME="$_ASSAYER_PLUGIN_NAME" \
+			node "$event_js" emit 2>"$stderr_file") || {
+		printf 'assayer_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/assayer/scripts/lib/assayer-extract.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# Claim extraction for Assayer.
+#
+# The language-understanding half of the plugin: an LLM reads the agent's
+# final message and pulls out *testable success claims* — assertions that some
+# command or check succeeded ("I ran the tests, they pass", "the build is
+# green", "lint is clean"). Each claim is tagged with a type and a
+# command_keyword that the deterministic verifier (assayer-verify.sh) uses to
+# locate the command that would corroborate or contradict it.
+#
+# The LLM does not judge truth — it only identifies claims and what command
+# would settle them. The factual cross-check is pure bash, so it stays
+# deterministic and testable.
+
+# Write the extraction prompt for a final assistant message to stdout.
+#   $1 — final assistant message text
+#   $2 — max_claims
+assayer_build_extraction_prompt() {
+	local message="${1:-}"
+	local max_claims="${2:-12}"
+
+	printf '%s\n' 'You are auditing an AI coding agent'"'"'s final message to its user.'
+	printf '%s\n' 'Extract every TESTABLE SUCCESS CLAIM: a statement asserting that a command,'
+	printf '%s\n' 'test, build, lint, or type check was run and SUCCEEDED. Ignore plans, intentions,'
+	printf '%s\n' 'hedged statements ("should pass"), and claims about code that no shell command'
+	printf '%s\n' 'could confirm.'
+	printf '\n'
+	printf '%s\n' 'Return JSON only — no prose, no markdown fences. A JSON array, possibly empty:'
+	printf '%s\n' '['
+	printf '%s\n' '  {'
+	printf '%s\n' '    "text": "the exact claim, quoted from the message",'
+	printf '%s\n' '    "type": "tests_pass|build_succeeds|lint_clean|types_check|command_succeeds|generic",'
+	printf '%s\n' '    "command_keyword": "a lowercase substring you expect in the verifying shell command, e.g. test, build, lint, tsc",'
+	printf '%s\n' '    "confidence": 0.0..1.0'
+	printf '%s\n' '  }'
+	printf '%s\n' ']'
+	printf '\n'
+	printf '%s\n' "Extract at most ${max_claims} claims, highest-confidence first."
+	printf '\n'
+	printf '%s\n' '---AGENT FINAL MESSAGE---'
+	printf '%s\n' "$message"
+	printf '%s\n' '---END MESSAGE---'
+}
+
+# Parse a claude -p response into a clean JSON array of claims.
+# Strips markdown fences, validates it is a JSON array, and drops malformed
+# entries. Echoes a compact JSON array (or "[]").
+#   $1 — raw response text
+assayer_parse_claims() {
+	local raw="${1:-}"
+	[[ -z "$raw" ]] && {
+		printf '[]'
+		return 0
+	}
+
+	# Strip leading/trailing markdown fences if present.
+	local clean
+	clean=$(printf '%s' "$raw" | sed -e 's/^```json//' -e 's/^```//' -e 's/```$//')
+
+	# Validate as a JSON array; keep only well-formed claim objects with a
+	# non-empty text and a recognized type.
+	local parsed
+	parsed=$(printf '%s' "$clean" | jq -c '
+		if type == "array" then
+			[ .[]
+			  | select(type == "object")
+			  | select((.text // "") != "")
+			  | {
+				  text: .text,
+				  type: (
+					if (.type // "") | test("^(tests_pass|build_succeeds|lint_clean|types_check|command_succeeds|generic)$")
+					then .type else "generic" end
+				  ),
+				  command_keyword: ((.command_keyword // "") | ascii_downcase),
+				  confidence: (
+					if (.confidence | type) == "number" then .confidence else 0.6 end
+				  )
+				}
+			]
+		else
+			[]
+		end
+	' 2>/dev/null) || parsed="[]"
+
+	[[ -z "$parsed" || "$parsed" == "null" ]] && parsed="[]"
+	printf '%s' "$parsed"
+}

package/plugins/assayer/scripts/lib/assayer-project-key.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Project key derivation for Assayer.
+# Mirrors echo/archivist/tribunal: stable 12-char hex key derived from the git
+# remote or repo root, surviving renames, clones, and worktrees.
+
+_assayer_sha256_first12() {
+	local input="$1"
+	if command -v shasum >/dev/null 2>&1; then
+		printf '%s' "$input" | shasum -a 256 2>/dev/null | cut -c1-12
+	elif command -v sha256sum >/dev/null 2>&1; then
+		printf '%s' "$input" | sha256sum 2>/dev/null | cut -c1-12
+	else
+		return 1
+	fi
+}
+
+assayer_project_remote_url() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" || ! -d "$cwd" ]] && return 0
+	git -C "$cwd" remote get-url origin 2>/dev/null || true
+}
+
+assayer_project_repo_root() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" || ! -d "$cwd" ]] && return 0
+
+	if ! git -C "$cwd" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+		return 0
+	fi
+
+	local common_dir toplevel
+	common_dir=$(git -C "$cwd" rev-parse --git-common-dir 2>/dev/null) || return 0
+
+	if [[ -n "$common_dir" && "$common_dir" != /* ]]; then
+		common_dir="$(cd "$cwd" && cd "$common_dir" 2>/dev/null && pwd -P)" || common_dir=""
+	fi
+
+	if [[ -n "$common_dir" && -d "$common_dir" ]]; then
+		toplevel="$(cd "$common_dir/.." 2>/dev/null && pwd -P)" || toplevel=""
+	fi
+
+	if [[ -z "$toplevel" ]]; then
+		toplevel=$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null || true)
+		[[ -n "$toplevel" ]] && toplevel="$(cd "$toplevel" 2>/dev/null && pwd -P)"
+	fi
+
+	printf '%s' "$toplevel"
+}
+
+assayer_project_key() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" ]] && cwd="$(pwd)"
+
+	local remote
+	remote=$(assayer_project_remote_url "$cwd")
+	if [[ -n "$remote" ]]; then
+		_assayer_sha256_first12 "remote:$remote"
+		return 0
+	fi
+
+	local root
+	root=$(assayer_project_repo_root "$cwd")
+	if [[ -n "$root" ]]; then
+		_assayer_sha256_first12 "root:$root"
+		return 0
+	fi
+
+	return 0
+}

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

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# Transcript reader for Assayer.
+#
+# The Stop hook payload carries `transcript_path` — a JSONL file already
+# committed to disk before Stop fires (same field tribunal and compass read).
+# Assayer needs two things from it:
+#
+#   1. The final assistant message — the text the agent left the user with,
+#      where claims like "I ran the tests, they pass" live.
+#   2. The session's Bash commands paired with their result status — the
+#      factual record to check those claims against.
+#
+# Claude Code transcripts represent a Bash invocation as a `tool_use` block
+# (name "Bash", with `.input.command`) on an assistant line, and its outcome
+# as a `tool_result` block on a following user line carrying the same
+# `tool_use_id` and an `is_error` flag. There is no per-call numeric exit code
+# in the transcript, so `is_error` is the success/failure signal.
+
+# Echo the final assistant message text (text blocks of the last assistant
+# turn that contains any), truncated to max_chars. Empty if unavailable.
+#   $1 — transcript_path
+#   $2 — max_chars (default 6000)
+assayer_final_assistant_message() {
+	local transcript_path="${1:-}"
+	local max_chars="${2:-6000}"
+
+	[[ -f "$transcript_path" ]] || return 0
+
+	local text
+	text=$(jq -s -r '
+		[ .[]
+		  | select(.type == "assistant")
+		  | select(any(.message.content[]?; .type == "text"))
+		]
+		| last
+		| if . == null then ""
+		  else [ .message.content[]? | select(.type == "text") | .text ] | join("\n")
+		  end
+	' "$transcript_path" 2>/dev/null) || text=""
+
+	[[ -z "$text" ]] && return 0
+	printf '%s' "${text:0:$max_chars}"
+}
+
+# Echo a JSON array of the session's Bash commands paired with result status:
+#   [ { "command": "...", "is_error": true|false, "excerpt": "..." }, ... ]
+# Ordered as they appear in the transcript. `is_error` is false when the
+# matching tool_result is absent or its is_error flag is not true.
+#   $1 — transcript_path
+assayer_collect_commands() {
+	local transcript_path="${1:-}"
+
+	[[ -f "$transcript_path" ]] || {
+		printf '[]'
+		return 0
+	}
+
+	local out
+	out=$(jq -s -c '
+		(
+			[ .[]
+			  | select(.type == "assistant")
+			  | .message.content[]?
+			  | select(.type == "tool_use" and .name == "Bash")
+			  | { id: .id, command: (.input.command // "") }
+			]
+		) as $calls
+		|
+		(
+			[ .[]
+			  | select(.type == "user")
+			  | .message.content[]?
+			  | select(.type == "tool_result")
+			  | {
+				  id: .tool_use_id,
+				  is_error: (.is_error == true),
+				  excerpt: (
+					if (.content | type) == "string" then .content
+					elif (.content | type) == "array" then
+					  ([ .content[]? | select(.type == "text") | .text ] | join("\n"))
+					else "" end
+				  )
+				}
+			]
+		) as $results
+		|
+		[ $calls[]
+		  | . as $c
+		  | {
+			  command: $c.command,
+			  is_error: (first($results[] | select(.id == $c.id) | .is_error) // false),
+			  excerpt: ((first($results[] | select(.id == $c.id) | .excerpt) // "")[0:240])
+			}
+		]
+	' "$transcript_path" 2>/dev/null) || out=""
+
+	[[ -z "$out" || "$out" == "null" ]] && out="[]"
+	printf '%s' "$out"
+}