@onlooker-community/ecosystem 0.23.1 → 0.25.0

package/plugins/warden/README.md

@@ -0,0 +1,185 @@
+# Warden
+
+Untrusted-content gate enforcing the Agents Rule of Two.
+
+Warden scans content flowing into the agent through `WebFetch` and `Read` for prompt-injection patterns. When it finds a threat, it closes a session-scoped **content gate** that blocks `Write`, `Edit`, `MultiEdit`, and `Bash` until the user explicitly clears it.
+
+Grounded in Meta's *Agents Rule of Two*: an agent should hold no more than two of {access to private data, ability to take external actions, processing of untrusted content} at once. A coding agent in a real repository already holds the first two — your source and secrets, plus the ability to write files and run commands. The moment it ingests untrusted content (a fetched page, a file of unknown provenance) it holds all three: the dangerous configuration in which untrusted content can steer private data into external actions. Warden cannot un-read content, so it removes the *external-actions* property instead — closing the gate keeps the agent reading and reasoning while a human reviews the situation. Three-of-three collapses back to two-of-three, with the user as the release valve.
+
+Warden is a sibling plugin to [`ecosystem`](../../) and assumes the Onlooker observability substrate (`~/.onlooker/`) is present.
+
+## How it works
+
+Detection and enforcement are split across two hook surfaces, mediated only by the on-disk gate lock — the surfaces never call each other. See [ADR-001](docs/adr/001-detect-after-ingest-gate-before-action.md).
+
+| Surface | What Warden does |
+|---------|------------------|
+| `PostToolUse` (`WebFetch`, `Read`) | Extracts ingested content from `tool_response`, applies the source and skip-glob filters and length cap, and runs the hybrid scanner. A strong pattern hit closes the gate immediately; a weak hit escalates to the evaluator. On a positive verdict it closes the session-scoped gate and emits `warden.threat.detected`. PostToolUse cannot block the read — and deliberately does not, because reading is how the threat is discovered. |
+| `PreToolUse` (`Write`, `Edit`, `MultiEdit`, `Bash`) | Pure lock check: if the gate is closed it returns `{"decision":"block", …}` and emits `warden.gate.blocked`; otherwise it allows silently. No model call, no command parsing. |
+| `SessionStart` | Initializes Warden for the session. A new session always starts with the gate open, even if a prior session saw a threat. |
+| `/warden` skill | The user-facing control surface — reports gate status and is the only sanctioned way to clear a closed gate. |
+
+### Hybrid detection
+
+Detection is a two-stage funnel, balancing coverage against cost and data egress:
+
+1. **Pattern floor** (`warden-patterns.sh`) — a curated regex set mapped to five threat types: `prompt_injection`, `instruction_override`, `credential_exfiltration`, `command_injection`, and `social_engineering`. **Strong** signatures (explicit override/exfil/command-injection phrasing) score `detection.strong_pattern_confidence` (default `0.9`) and close the gate with no model call. **Weak** signatures (social-engineering pressure, soft instruction-shaped imperatives) score `detection.weak_pattern_confidence` (default `0.5`) — below `close_threshold` — and are treated as borderline.
+2. **LLM escalation** (`warden-evaluator.sh`) — borderline content is sanitized and sent to N parallel Haiku judges (majority vote). The gate closes only if the panel judges it an injection with confidence `≥ close_threshold`.
+
+Clean content (no signature) never reaches the model. Set `escalation.enabled: false` for a zero-egress, pattern-only posture.
+
+### Fail-soft posture
+
+- Detection never blocks the read — `PostToolUse` cannot. If escalation errors, Warden falls back to the deterministic pattern verdict.
+- Enforcement is a pure lock check, trivially fail-closed: a present lock always blocks.
+- Event emission is best-effort; a schema-validation or emit failure is logged to stderr and never blocks a session.
+
+## Activation
+
+Warden is **off by default**. Enable per-project in `.claude/settings.json`:
+
+```json
+{
+  "warden": {
+    "enabled": true
+  }
+}
+```
+
+Or globally in `~/.claude/settings.json`.
+
+## Configuration
+
+All keys are optional. Unset keys fall back to the plugin's `config.json` defaults.
+
+```json
+{
+  "warden": {
+    "enabled": false,
+    "scan": {
+      "sources": ["web_fetch", "file_read"],
+      "max_content_chars": 20000,
+      "skip_globs": ["**/*.lock", "**/*.sum", "**/node_modules/**", "**/.git/**", "**/dist/**", "**/build/**"],
+      "store_snippet": true,
+      "snippet_max_chars": 240
+    },
+    "detection": {
+      "close_threshold": 0.65,
+      "strong_pattern_confidence": 0.9,
+      "weak_pattern_confidence": 0.5
+    },
+    "escalation": {
+      "enabled": true,
+      "borderline_only": true,
+      "model": "claude-haiku-4-5-20251001",
+      "n": 3,
+      "temperature": 0.0,
+      "max_output_tokens": 192,
+      "sample_timeout_seconds": 12,
+      "min_valid_samples": 2
+    },
+    "gate": {
+      "blocked_tools": ["Write", "Edit", "MultiEdit", "Bash"],
+      "clear_policy": "user_override_only"
+    }
+  }
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `enabled` | `false` | Must be `true` for any scanning or gating to run. |
+| `scan.sources` | `["web_fetch", "file_read"]` | Which ingestion sources to scan. Matches the schema's `source_type` enum. |
+| `scan.max_content_chars` | `20000` | Length cap on the content fed into detection. |
+| `scan.skip_globs` | lockfiles, `node_modules`, `.git`, `dist`, `build`, … | Globs whose reads are not scanned. |
+| `scan.store_snippet` | `true` | Whether to keep a flagged excerpt in the gate record and event payload. |
+| `scan.snippet_max_chars` | `240` | Maximum length of a stored snippet. |
+| `detection.close_threshold` | `0.65` | Confidence at or above which a verdict closes the gate. |
+| `detection.strong_pattern_confidence` | `0.9` | Score assigned to strong pattern hits — above threshold, closes without a model call. |
+| `detection.weak_pattern_confidence` | `0.5` | Score assigned to weak pattern hits — below threshold, escalates to the evaluator. |
+| `escalation.enabled` | `true` | Whether borderline content escalates to the LLM evaluator. `false` is a zero-egress, pattern-only posture. |
+| `escalation.borderline_only` | `true` | Escalate only weak/borderline hits, never clean content. |
+| `escalation.model` | `claude-haiku-4-5-20251001` | Model used for the evaluator panel. |
+| `escalation.n` | `3` | Number of parallel evaluator samples (majority vote). |
+| `escalation.temperature` | `0.0` | Sampling temperature for the evaluator. |
+| `escalation.max_output_tokens` | `192` | Token ceiling per evaluator sample. |
+| `escalation.sample_timeout_seconds` | `12` | Per-sample wall-clock timeout. |
+| `escalation.min_valid_samples` | `2` | Minimum valid samples required to form a verdict. |
+| `gate.blocked_tools` | `["Write", "Edit", "MultiEdit", "Bash"]` | Tools blocked while the gate is closed. |
+| `gate.clear_policy` | `user_override_only` | How a closed gate may be cleared. Only explicit user override is supported. |
+
+On escalation, only a sanitized, length-capped excerpt of the ingested content is sent to the evaluator model. Setting `escalation.enabled: false` disables all egress — Warden then relies on the deterministic pattern floor alone.
+
+## The gate model
+
+The gate is a single session-scoped lock with two states:
+
+- **Open** (default — file absent, or `{"state":"open"}`) — `Write`, `Edit`, `MultiEdit`, and `Bash` are allowed.
+- **Closed** (`{"state":"closed", …}`) — those operations are blocked at `PreToolUse`.
+
+The detection hook **closes** the gate on a positive scan. Once closed, it can be **cleared only by the user** via the `/warden` skill (`clear_policy: user_override_only`) — Warden does not auto-clear in this release. The gate is session-scoped: a brand-new session starts open even if a prior session saw a threat, because the untrusted content lives in a specific session's context.
+
+Clearing the gate re-enables write-class tools but does not remove the flagged content from the conversation — it is still in context. The skill reminds the user of this.
+
+## Storage layout
+
+```text
+~/.onlooker/warden/sessions/<session_id>/
+└── gate.json
+```
+
+`gate.json` when the gate is closed:
+
+```json
+{
+  "state": "closed",
+  "closed_at": 1717000000,
+  "threat": {
+    "threat_id": "01J…",
+    "source_type": "web_fetch",
+    "threat_type": "credential_exfiltration",
+    "confidence": 0.9,
+    "source_url": "https://…",
+    "source_path": null,
+    "snippet": "…sanitized excerpt…",
+    "matched_pattern": "…",
+    "detection_method": "pattern_strong"
+  }
+}
+```
+
+The local record keeps forensic fields (`threat_id`, `matched_pattern`, `detection_method`). The emitted `warden.threat.detected` event carries only the schema-permitted fields — warden payloads use `additionalProperties: false`. State is keyed by `session_id`, not by repository: the gate guards a single session's context.
+
+## Events emitted
+
+Warden emits the canonical `warden.*` event surface from [`@onlooker-community/schema`](https://github.com/onlooker-community/schema) (v2.4.0+). All events land in `~/.onlooker/logs/onlooker-events.jsonl` and are validated against the schema before write.
+
+| Event | When | Payload |
+|-------|------|---------|
+| `warden.threat.detected` | A scan closes the gate. | `source_type`, `threat_type`, `confidence` (plus optional `source_url` / `source_path` / `snippet`) |
+| `warden.gate.blocked` | A write/edit/bash operation is blocked by a closed gate. | `blocked_operation`, `threat_source_type` |
+| `warden.threat.cleared` | The user clears the gate via `/warden`. | `source_type`, `cleared_by: user_override` |
+
+## The `/warden` skill
+
+`/warden` is the user-facing control surface for the gate that the hooks open and close automatically.
+
+- `/warden` or `/warden status` — prints whether the gate is OPEN or CLOSED. When closed, prints the recorded threat: `threat_type`, `source_type`, source URL/path, confidence, detection method, matched pattern, and the flagged snippet (when storage is enabled).
+- `/warden clear` (also `reopen`, `override`, `unblock`) — verifies the gate is closed, removes the lock, re-enables `Write`/`Edit`/`Bash`, and emits `warden.threat.cleared` with `cleared_by: user_override`.
+
+The skill resolves the active session automatically: it prefers `$CLAUDE_SESSION_ID`, falls back to the single closed gate when exactly one exists, and reports ambiguity if several sessions have closed gates (re-run with an explicit session id in that case). Closing is automatic; clearing is always a deliberate user decision.
+
+## Requirements
+
+- The `ecosystem` plugin installed (for the `~/.onlooker/` substrate and canonical event emission).
+- `claude` CLI on `PATH` (the evaluator shells out to `claude -p` when escalation is enabled).
+- `jq` for JSON manipulation.
+- `node` for canonical-event emission.
+
+## Architecture decisions
+
+Key decisions made during initial design are recorded in [`docs/adr/`](docs/adr/):
+
+- [ADR-001](docs/adr/001-detect-after-ingest-gate-before-action.md) — Detect after ingestion, gate before action (the detection/enforcement split and its Rule-of-Two mapping)
+
+See also the full plugin design in [`docs/design.md`](docs/design.md).

package/release-please-config.json

@@ -206,6 +206,22 @@
           "jsonpath": "$.version"
         }
       ]
+    },
+    "plugins/assayer": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "component": "assayer",
+      "draft": false,
+      "prerelease": false,
+      "extra-files": [
+        {
+          "type": "json",
+          "path": ".claude-plugin/plugin.json",
+          "jsonpath": "$.version"
+        }
+      ]
     }
   },
   "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"

package/test/bats/assayer-config.bats

@@ -0,0 +1,60 @@
+#!/usr/bin/env bats
+
+# Exercises Assayer config loading: defaults and per-project overrides.
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/assayer"
+	export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/assayer-config.sh"
+
+	REPO="${BATS_TEST_TMPDIR}/repo"
+	mkdir -p "${REPO}/.claude"
+}
+
+@test "disabled by default (no settings)" {
+	assayer_config_load "$REPO"
+	run assayer_config_enabled
+	[ "$status" -ne 0 ]
+}
+
+@test "enabled when settings opt in" {
+	printf '%s\n' '{"assayer":{"enabled":true}}' >"${REPO}/.claude/settings.json"
+	assayer_config_load "$REPO"
+	run assayer_config_enabled
+	[ "$status" -eq 0 ]
+}
+
+@test "default model is haiku" {
+	assayer_config_load "$REPO"
+	[ "$(assayer_config_model)" = "claude-haiku-4-5-20251001" ]
+}
+
+@test "model override is honored" {
+	printf '%s\n' '{"assayer":{"evaluation":{"model":"claude-opus-4-8"}}}' >"${REPO}/.claude/settings.json"
+	assayer_config_load "$REPO"
+	[ "$(assayer_config_model)" = "claude-opus-4-8" ]
+}
+
+@test "default max_claims is 12" {
+	assayer_config_load "$REPO"
+	[ "$(assayer_config_max_claims)" = "12" ]
+}
+
+@test "default min_confidence is 0.5" {
+	assayer_config_load "$REPO"
+	[ "$(assayer_config_min_confidence)" = "0.5" ]
+}
+
+@test "min_confidence override is honored" {
+	printf '%s\n' '{"assayer":{"min_confidence":0.8}}' >"${REPO}/.claude/settings.json"
+	assayer_config_load "$REPO"
+	[ "$(assayer_config_min_confidence)" = "0.8" ]
+}
+
+@test "default timeout is 60" {
+	assayer_config_load "$REPO"
+	[ "$(assayer_config_timeout)" = "60" ]
+}

package/test/bats/assayer-events.bats

@@ -0,0 +1,99 @@
+#!/usr/bin/env bats
+
+# Validates every emitted assayer.* event against @onlooker-community/schema.
+#
+# The assayer.* event types ship in @onlooker-community/schema; until the
+# installed version includes them, these tests skip rather than fail. Once the
+# ecosystem's schema dependency is bumped to a release that carries them, they
+# run for real. See plugins/assayer/README.md (Requirements).
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/assayer"
+	export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+	export ONLOOKER_EVENTS_LOG="${ONLOOKER_DIR}/logs/onlooker-events.jsonl"
+	mkdir -p "$(dirname "$ONLOOKER_EVENTS_LOG")"
+
+	export _ONLOOKER_EVENT_JS="${REPO_ROOT}/scripts/lib/onlooker-event.mjs"
+	export CLAUDE_SESSION_ID="bats-session-$$"
+
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/assayer-events.sh"
+}
+
+# Skip when the installed schema predates the assayer.* event types.
+_require_assayer_schema() {
+	if ! grep -q "assayer.audit.started" \
+		"${REPO_ROOT}/node_modules/@onlooker-community/schema/schemas/event.v1.json" 2>/dev/null; then
+		skip "installed @onlooker-community/schema has no assayer.* types yet"
+	fi
+}
+
+_validate_latest_event() {
+	local last
+	last=$(tail -n 1 "$ONLOOKER_EVENTS_LOG")
+	[ -n "$last" ] || return 1
+	printf '%s' "$last" | ONLOOKER_DIR="$ONLOOKER_DIR" \
+		node "${REPO_ROOT}/scripts/lib/onlooker-event.mjs" validate >/dev/null
+}
+
+# Valid 26-char Crockford Base32 ULID (no I, L, O, or U).
+AUDIT_ID="01J0000000000000000000AB34"
+
+@test "assayer.audit.started validates" {
+	_require_assayer_schema
+	local p
+	p=$(jq -n --arg a "$AUDIT_ID" '{audit_id: $a, claim_count: 3, trigger: "stop", command_count: 5}')
+	assayer_emit_event "assayer.audit.started" "$p"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "assayer.claim.contradicted validates" {
+	_require_assayer_schema
+	local p
+	p=$(jq -n --arg a "$AUDIT_ID" '{
+		audit_id: $a,
+		claim: "I ran the tests and they all pass.",
+		claim_type: "tests_pass",
+		evidence_command: "npm test",
+		result_excerpt: "1 failed, 32 passed",
+		confidence: 0.9
+	}')
+	assayer_emit_event "assayer.claim.contradicted" "$p"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "assayer.claim.unverified validates" {
+	_require_assayer_schema
+	local p
+	p=$(jq -n --arg a "$AUDIT_ID" '{audit_id: $a, claim: "The deploy is healthy.", claim_type: "generic", reason: "no_matching_command"}')
+	assayer_emit_event "assayer.claim.unverified" "$p"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "assayer.audit.complete validates" {
+	_require_assayer_schema
+	local p
+	p=$(jq -n --arg a "$AUDIT_ID" '{
+		audit_id: $a, claim_count: 3, corroborated: 1, contradicted: 1,
+		unverified: 1, verdict: "contradictions_found", duration_ms: 4200
+	}')
+	assayer_emit_event "assayer.audit.complete" "$p"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "emission fails on unknown event type" {
+	run assayer_emit_event "assayer.no.such.event" '{"audit_id":"x"}'
+	[ "$status" -ne 0 ]
+}
+
+@test "assayer_emit_event returns 1 when payload is empty" {
+	run assayer_emit_event "assayer.audit.started" ""
+	[ "$status" -ne 0 ]
+}

package/test/bats/assayer-extract.bats

@@ -0,0 +1,76 @@
+#!/usr/bin/env bats
+
+# Exercises claim parsing: assayer_parse_claims and the extraction prompt.
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/assayer"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/assayer-extract.sh"
+}
+
+@test "parses a clean JSON array of claims" {
+	run assayer_parse_claims '[{"text":"tests pass","type":"tests_pass","command_keyword":"test","confidence":0.9}]'
+	[ "$status" -eq 0 ]
+	[ "$(printf '%s' "$output" | jq 'length')" -eq 1 ]
+	[ "$(printf '%s' "$output" | jq -r '.[0].type')" = "tests_pass" ]
+}
+
+@test "strips markdown fences" {
+	local raw
+	raw=$'```json\n[{"text":"build ok","type":"build_succeeds","command_keyword":"build","confidence":0.8}]\n```'
+	run assayer_parse_claims "$raw"
+	[ "$status" -eq 0 ]
+	[ "$(printf '%s' "$output" | jq 'length')" -eq 1 ]
+}
+
+@test "drops malformed entries and entries without text" {
+	run assayer_parse_claims '[{"text":"ok","type":"generic","confidence":0.7},{"no_text":true},{"text":""}]'
+	[ "$status" -eq 0 ]
+	[ "$(printf '%s' "$output" | jq 'length')" -eq 1 ]
+}
+
+@test "coerces unknown type to generic" {
+	run assayer_parse_claims '[{"text":"thing","type":"made_up","command_keyword":"x","confidence":0.7}]'
+	[ "$status" -eq 0 ]
+	[ "$(printf '%s' "$output" | jq -r '.[0].type')" = "generic" ]
+}
+
+@test "defaults confidence when missing or non-numeric" {
+	run assayer_parse_claims '[{"text":"thing","type":"generic","command_keyword":"x"}]'
+	[ "$status" -eq 0 ]
+	[ "$(printf '%s' "$output" | jq -r '.[0].confidence')" = "0.6" ]
+}
+
+@test "lowercases command_keyword" {
+	run assayer_parse_claims '[{"text":"thing","type":"generic","command_keyword":"TEST","confidence":0.7}]'
+	[ "$status" -eq 0 ]
+	[ "$(printf '%s' "$output" | jq -r '.[0].command_keyword')" = "test" ]
+}
+
+@test "non-array input yields empty array" {
+	run assayer_parse_claims '{"text":"not an array"}'
+	[ "$status" -eq 0 ]
+	[ "$output" = "[]" ]
+}
+
+@test "garbage input yields empty array" {
+	run assayer_parse_claims 'I could not find any claims.'
+	[ "$status" -eq 0 ]
+	[ "$output" = "[]" ]
+}
+
+@test "empty input yields empty array" {
+	run assayer_parse_claims ""
+	[ "$status" -eq 0 ]
+	[ "$output" = "[]" ]
+}
+
+@test "extraction prompt includes the message and the JSON contract" {
+	run assayer_build_extraction_prompt "I ran the tests and they pass." 5
+	[ "$status" -eq 0 ]
+	[[ "$output" == *"I ran the tests and they pass."* ]]
+	[[ "$output" == *"TESTABLE SUCCESS CLAIM"* ]]
+	[[ "$output" == *"at most 5 claims"* ]]
+}

package/test/bats/assayer-project-key.bats

@@ -0,0 +1,58 @@
+#!/usr/bin/env bats
+
+# Exercises Assayer project-key derivation.
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/assayer"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/assayer-project-key.sh"
+
+	REPO="${BATS_TEST_TMPDIR}/repo"
+	mkdir -p "$REPO"
+	git -C "$REPO" init -q
+	git -C "$REPO" config user.email test@example.com
+	git -C "$REPO" config user.name test
+	(cd "$REPO" && printf 'x\n' >f && git add f && git commit -q -m init)
+}
+
+@test "key is 12 hex chars for a repo with a remote" {
+	git -C "$REPO" remote add origin https://example.com/foo/bar.git
+	run assayer_project_key "$REPO"
+	[ "$status" -eq 0 ]
+	[[ "$output" =~ ^[0-9a-f]{12}$ ]]
+}
+
+@test "key is stable across calls" {
+	git -C "$REPO" remote add origin https://example.com/foo/bar.git
+	a=$(assayer_project_key "$REPO")
+	b=$(assayer_project_key "$REPO")
+	[ "$a" = "$b" ]
+}
+
+@test "remote-keyed differs from root-keyed" {
+	local with_remote without_remote
+	without_remote=$(assayer_project_key "$REPO")
+	git -C "$REPO" remote add origin https://example.com/foo/bar.git
+	with_remote=$(assayer_project_key "$REPO")
+	[ "$with_remote" != "$without_remote" ]
+}
+
+@test "different remotes yield different keys" {
+	git -C "$REPO" remote add origin https://example.com/foo/one.git
+	local one
+	one=$(assayer_project_key "$REPO")
+	git -C "$REPO" remote set-url origin https://example.com/foo/two.git
+	local two
+	two=$(assayer_project_key "$REPO")
+	[ "$one" != "$two" ]
+}
+
+@test "non-repo cwd yields empty key" {
+	local non_repo="${BATS_TEST_TMPDIR}/not-a-repo"
+	mkdir -p "$non_repo"
+	run assayer_project_key "$non_repo"
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+}

package/test/bats/assayer-stop-hook.bats

@@ -0,0 +1,81 @@
+#!/usr/bin/env bats
+
+# Exercises the Assayer Stop hook's gating behavior. Does not invoke claude -p
+# (the hook bails before the extraction step when preconditions fail).
+# Verifies: disabled-by-default, no-git, recursion guard, no-transcript, and
+# stdout silence (advisory hook must never block Stop).
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/assayer"
+	export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+	HOOK="${PLUGIN_ROOT}/scripts/hooks/assayer-stop.sh"
+
+	REPO="${BATS_TEST_TMPDIR}/repo"
+	mkdir -p "$REPO"
+	git -C "$REPO" init -q
+	git -C "$REPO" config user.email test@example.com
+	git -C "$REPO" config user.name test
+	(cd "$REPO" && printf 'initial\n' >README.md && git add README.md && git commit -q -m init)
+
+	TRANSCRIPT="${BATS_TEST_TMPDIR}/transcript.jsonl"
+	printf '%s\n' '{"type":"assistant","message":{"content":[{"type":"text","text":"All tests pass."}]}}' >"$TRANSCRIPT"
+}
+
+_make_input() {
+	local cwd="${1:-$REPO}" sid="${2:-test-session}" transcript="${3:-$TRANSCRIPT}"
+	jq -n --arg cwd "$cwd" --arg sid "$sid" --arg tp "$transcript" \
+		'{cwd: $cwd, session_id: $sid, transcript_path: $tp}'
+}
+
+@test "exits 0 silently when assayer.enabled is false (default)" {
+	local input
+	input=$(_make_input)
+	run bash -c "printf '%s' '$input' | ONLOOKER_DIR='$ONLOOKER_DIR' '$HOOK'"
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+}
+
+@test "exits 0 when cwd is not a git repo" {
+	local non_repo="${BATS_TEST_TMPDIR}/not-a-repo"
+	mkdir -p "$non_repo"
+	local input
+	input=$(_make_input "$non_repo")
+	run bash -c "printf '%s' '$input' | ONLOOKER_DIR='$ONLOOKER_DIR' '$HOOK'"
+	[ "$status" -eq 0 ]
+}
+
+@test "recursion guard: ASSAYER_NESTED=1 causes immediate exit 0" {
+	mkdir -p "${REPO}/.claude"
+	printf '%s\n' '{"assayer":{"enabled":true}}' >"${REPO}/.claude/settings.json"
+	local input
+	input=$(_make_input)
+	run bash -c "printf '%s' '$input' | ASSAYER_NESTED=1 ONLOOKER_DIR='$ONLOOKER_DIR' '$HOOK'"
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+}
+
+@test "exits 0 when enabled but transcript is missing" {
+	mkdir -p "${REPO}/.claude"
+	printf '%s\n' '{"assayer":{"enabled":true}}' >"${REPO}/.claude/settings.json"
+	local input
+	input=$(_make_input "$REPO" "test-session" "${BATS_TEST_TMPDIR}/nope.jsonl")
+	run bash -c "printf '%s' '$input' | ONLOOKER_DIR='$ONLOOKER_DIR' '$HOOK'"
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+}
+
+@test "exits 0 when enabled but final message is empty" {
+	mkdir -p "${REPO}/.claude"
+	printf '%s\n' '{"assayer":{"enabled":true}}' >"${REPO}/.claude/settings.json"
+	# Transcript with no assistant text turn.
+	local empty_transcript="${BATS_TEST_TMPDIR}/empty.jsonl"
+	printf '%s\n' '{"type":"user","message":{"content":[{"type":"text","text":"hi"}]}}' >"$empty_transcript"
+	local input
+	input=$(_make_input "$REPO" "test-session" "$empty_transcript")
+	run bash -c "printf '%s' '$input' | ONLOOKER_DIR='$ONLOOKER_DIR' '$HOOK'"
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+}

package/test/bats/assayer-transcript.bats

@@ -0,0 +1,72 @@
+#!/usr/bin/env bats
+
+# Exercises the transcript reader against a synthetic JSONL transcript shaped
+# like a real Claude Code session log.
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/assayer"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/assayer-transcript.sh"
+
+	TRANSCRIPT="${BATS_TEST_TMPDIR}/transcript.jsonl"
+	{
+		# An assistant turn that runs a passing build, then a failing test.
+		printf '%s\n' '{"type":"assistant","message":{"content":[{"type":"text","text":"Running the build."},{"type":"tool_use","name":"Bash","id":"t1","input":{"command":"npm run build"}}]}}'
+		printf '%s\n' '{"type":"user","message":{"content":[{"type":"tool_result","tool_use_id":"t1","is_error":false,"content":"build ok"}]}}'
+		printf '%s\n' '{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Bash","id":"t2","input":{"command":"npm test"}}]}}'
+		printf '%s\n' '{"type":"user","message":{"content":[{"type":"tool_result","tool_use_id":"t2","is_error":true,"content":"1 failed"}]}}'
+		# A non-Bash tool call should be ignored.
+		printf '%s\n' '{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Read","id":"t3","input":{"file_path":"x"}}]}}'
+		# Final assistant message with the claims.
+		printf '%s\n' '{"type":"assistant","message":{"content":[{"type":"text","text":"Done. The build passes and the tests are green."}]}}'
+	} >"$TRANSCRIPT"
+}
+
+@test "final assistant message returns the last text turn" {
+	run assayer_final_assistant_message "$TRANSCRIPT" 6000
+	[ "$status" -eq 0 ]
+	[ "$output" = "Done. The build passes and the tests are green." ]
+}
+
+@test "final assistant message truncates to max_chars" {
+	run assayer_final_assistant_message "$TRANSCRIPT" 10
+	[ "$status" -eq 0 ]
+	[ "${#output}" -eq 10 ]
+}
+
+@test "missing transcript yields empty final message" {
+	run assayer_final_assistant_message "${BATS_TEST_TMPDIR}/nope.jsonl" 6000
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+}
+
+@test "collects Bash commands with their is_error status" {
+	run assayer_collect_commands "$TRANSCRIPT"
+	[ "$status" -eq 0 ]
+	[ "$(printf '%s' "$output" | jq 'length')" -eq 2 ]
+	[ "$(printf '%s' "$output" | jq -r '.[0].command')" = "npm run build" ]
+	[ "$(printf '%s' "$output" | jq -r '.[0].is_error')" = "false" ]
+	[ "$(printf '%s' "$output" | jq -r '.[1].command')" = "npm test" ]
+	[ "$(printf '%s' "$output" | jq -r '.[1].is_error')" = "true" ]
+}
+
+@test "captures the failing command's output excerpt" {
+	run assayer_collect_commands "$TRANSCRIPT"
+	[ "$status" -eq 0 ]
+	[ "$(printf '%s' "$output" | jq -r '.[1].excerpt')" = "1 failed" ]
+}
+
+@test "non-Bash tool calls are excluded" {
+	run assayer_collect_commands "$TRANSCRIPT"
+	[ "$status" -eq 0 ]
+	# Only the two Bash commands, never the Read call.
+	[ "$(printf '%s' "$output" | jq '[.[] | select(.command | contains("file"))] | length')" -eq 0 ]
+}
+
+@test "missing transcript yields empty command array" {
+	run assayer_collect_commands "${BATS_TEST_TMPDIR}/nope.jsonl"
+	[ "$status" -eq 0 ]
+	[ "$output" = "[]" ]
+}