@onlooker-community/ecosystem 0.28.1 → 0.29.0

package/test/bats/inspector-events.bats

@@ -0,0 +1,156 @@
+#!/usr/bin/env bats
+
+# Validates every emitted inspector.* event against @onlooker-community/schema.
+#
+# The inspector.* 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.
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/inspector"
+	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/inspector-events.sh"
+}
+
+_require_inspector_schema() {
+	if ! grep -q "inspector.check.passed" \
+		"${REPO_ROOT}/node_modules/@onlooker-community/schema/schemas/event.v1.json" 2>/dev/null; then
+		skip "installed @onlooker-community/schema has no inspector.* 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
+}
+
+@test "inspector.check.passed validates" {
+	_require_inspector_schema
+	local p
+	p=$(jq -n '{
+		file_path: "/repo/src/a.ts",
+		file_path_relative: "src/a.ts",
+		tool_name: "Edit",
+		check_name: "biome",
+		check_kind: "lint",
+		argv: ["biome", "check", "/repo/src/a.ts"],
+		duration_ms: 124,
+		project_key: "a1b2c3d4e5f6"
+	}')
+	inspector_emit_event "inspector.check.passed" "$p"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "inspector.check.failed validates" {
+	_require_inspector_schema
+	local p
+	p=$(jq -n '{
+		file_path: "/repo/src/a.ts",
+		file_path_relative: "src/a.ts",
+		tool_name: "Edit",
+		check_name: "tsc",
+		check_kind: "typecheck",
+		argv: ["tsc", "--noEmit"],
+		duration_ms: 980,
+		exit_code: 2,
+		issue_count: 3,
+		output_excerpt: "src/a.ts:42:5 - Type error",
+		output_truncated: false,
+		project_key: "a1b2c3d4e5f6"
+	}')
+	inspector_emit_event "inspector.check.failed" "$p"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "inspector.check.failed validates with null issue_count" {
+	_require_inspector_schema
+	local p
+	p=$(jq -n '{
+		file_path: "/repo/src/a.ts",
+		tool_name: "Edit",
+		check_name: "mystery-linter",
+		check_kind: "lint",
+		exit_code: 1,
+		issue_count: null
+	}')
+	inspector_emit_event "inspector.check.failed" "$p"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "inspector.check.skipped (per-check) validates" {
+	_require_inspector_schema
+	local p
+	p=$(jq -n '{
+		file_path: "/repo/scripts/deploy.sh",
+		file_path_relative: "scripts/deploy.sh",
+		tool_name: "Edit",
+		check_name: "shellcheck",
+		check_kind: "lint",
+		reason: "tool_missing",
+		project_key: "a1b2c3d4e5f6"
+	}')
+	inspector_emit_event "inspector.check.skipped" "$p"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "inspector.check.skipped (whole-file) validates" {
+	_require_inspector_schema
+	local p
+	p=$(jq -n '{
+		file_path: "/repo/node_modules/foo/index.js",
+		file_path_relative: "node_modules/foo/index.js",
+		tool_name: "Write",
+		reason: "excluded_path",
+		project_key: "a1b2c3d4e5f6"
+	}')
+	inspector_emit_event "inspector.check.skipped" "$p"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "inspector.run.completed validates" {
+	_require_inspector_schema
+	local p
+	p=$(jq -n '{
+		file_path: "/repo/src/a.ts",
+		file_path_relative: "src/a.ts",
+		tool_name: "Edit",
+		checks_run: 2,
+		checks_passed: 1,
+		checks_failed: 1,
+		checks_skipped: 0,
+		duration_ms: 1080,
+		project_key: "a1b2c3d4e5f6"
+	}')
+	inspector_emit_event "inspector.run.completed" "$p"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "emission rejects an unknown event type" {
+	run inspector_emit_event "inspector.no.such.event" '{"file_path":"x"}'
+	[ "$status" -ne 0 ]
+}
+
+@test "inspector_emit_event returns 1 when payload is empty" {
+	run inspector_emit_event "inspector.check.passed" ""
+	[ "$status" -ne 0 ]
+}

package/test/bats/inspector-post-write-hook.bats

@@ -0,0 +1,164 @@
+#!/usr/bin/env bats
+
+# Exercises the Inspector PostToolUse hook's end-to-end behavior.
+# Uses fake check commands (sh -c) so the suite has no external lint deps.
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	# These tests assert on the event log, so they require a schema that
+	# accepts inspector.* events. Skip when the installed package is too old.
+	if ! grep -q "inspector.check.passed" \
+		"${BATS_TEST_DIRNAME}/../../node_modules/@onlooker-community/schema/schemas/event.v1.json" 2>/dev/null; then
+		skip "installed @onlooker-community/schema has no inspector.* types yet"
+	fi
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/inspector"
+	HOOK="${PLUGIN_ROOT}/scripts/hooks/inspector-post-write.sh"
+	export ONLOOKER_EVENTS_LOG="${ONLOOKER_DIR}/logs/onlooker-events.jsonl"
+	mkdir -p "$(dirname "$ONLOOKER_EVENTS_LOG")"
+
+	REPO="${BATS_TEST_TMPDIR}/repo"
+	mkdir -p "${REPO}/src" "${REPO}/.claude" "${REPO}/node_modules/foo"
+	git -C "$REPO" init -q
+	git -C "$REPO" remote add origin "https://example.com/test-${BATS_TEST_NUMBER}.git"
+	printf 'sample\n' >"${REPO}/src/sample.ts"
+	printf 'sample\n' >"${REPO}/src/sample.py"
+	printf 'sample\n' >"${REPO}/node_modules/foo/index.ts"
+}
+
+_input() {
+	local cwd="${1:-$REPO}" tool="${2:-Edit}" path="${3:-${REPO}/src/sample.ts}"
+	jq -n --arg cwd "$cwd" --arg tool "$tool" --arg p "$path" --arg sid "test-${BATS_TEST_NUMBER}" \
+		'{cwd:$cwd, session_id:$sid, tool_name:$tool, tool_input:{file_path:$p}}'
+}
+
+_settings() {
+	cat >"${REPO}/.claude/settings.json"
+}
+
+_event_count() {
+	local et="$1"
+	if [[ -f "$ONLOOKER_EVENTS_LOG" ]]; then
+		jq -c "select(.event_type == \"$et\")" "$ONLOOKER_EVENTS_LOG" | wc -l | tr -d ' '
+	else
+		printf '0'
+	fi
+}
+
+_run_hook() {
+	local input="$1"
+	printf '%s' "$input" | ONLOOKER_DIR="$ONLOOKER_DIR" CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" bash "$HOOK"
+}
+
+@test "exits 0 silently when inspector.enabled is false (default)" {
+	run _run_hook "$(_input)"
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+	[ ! -f "$ONLOOKER_EVENTS_LOG" ] || [ "$(_event_count inspector.run.completed)" = "0" ]
+}
+
+@test "exits 0 when tool_name is not Write/Edit/MultiEdit" {
+	echo '{"inspector":{"enabled":true,"checks":{".ts":[{"name":"t","kind":"lint","argv":["true"]}]}}}' | _settings
+	run _run_hook "$(_input "$REPO" "Bash")"
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+	[ "$(_event_count inspector.run.completed)" = "0" ]
+}
+
+@test "recursion guard: INSPECTOR_NESTED=1 causes immediate exit 0" {
+	echo '{"inspector":{"enabled":true,"checks":{".ts":[{"name":"t","kind":"lint","argv":["true"]}]}}}' | _settings
+	run bash -c "printf '%s' '$(_input)' | INSPECTOR_NESTED=1 ONLOOKER_DIR='$ONLOOKER_DIR' CLAUDE_PLUGIN_ROOT='$PLUGIN_ROOT' '$HOOK'"
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+	[ "$(_event_count inspector.run.completed)" = "0" ]
+}
+
+@test "files in excluded_paths emit a single .skipped event and produce no agent output" {
+	echo '{"inspector":{"enabled":true,"checks":{".ts":[{"name":"t","kind":"lint","argv":["true"]}]}}}' | _settings
+	run _run_hook "$(_input "$REPO" "Write" "${REPO}/node_modules/foo/index.ts")"
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+	[ "$(_event_count inspector.check.skipped)" = "1" ]
+	[ "$(_event_count inspector.run.completed)" = "0" ]
+	# The skipped reason must be excluded_path.
+	[ "$(jq -r 'select(.event_type=="inspector.check.skipped").payload.reason' "$ONLOOKER_EVENTS_LOG")" = "excluded_path" ]
+}
+
+@test "extensions with no configured checks emit a single .skipped with no_extension_match" {
+	echo '{"inspector":{"enabled":true,"checks":{".ts":[{"name":"t","kind":"lint","argv":["true"]}]}}}' | _settings
+	run _run_hook "$(_input "$REPO" "Edit" "${REPO}/src/sample.py")"
+	[ "$status" -eq 0 ]
+	[ "$(_event_count inspector.check.skipped)" = "1" ]
+	[ "$(jq -r 'select(.event_type=="inspector.check.skipped").payload.reason' "$ONLOOKER_EVENTS_LOG")" = "no_extension_match" ]
+}
+
+@test "a passing check emits .passed and silences agent-facing stdout by default" {
+	echo '{"inspector":{"enabled":true,"checks":{".ts":[{"name":"clean","kind":"lint","argv":["true"]}]}}}' | _settings
+	run _run_hook "$(_input)"
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+	[ "$(_event_count inspector.check.passed)" = "1" ]
+	[ "$(_event_count inspector.run.completed)" = "1" ]
+}
+
+@test "show_clean_runs surfaces the file header for passing checks" {
+	echo '{"inspector":{"enabled":true,"show_clean_runs":true,"checks":{".ts":[{"name":"clean","kind":"lint","argv":["true"]}]}}}' | _settings
+	run _run_hook "$(_input)"
+	[ "$status" -eq 0 ]
+	[[ "$output" == *"inspector: src/sample.ts"* ]]
+	[[ "$output" == *"✓ clean"* ]]
+}
+
+@test "a failing check emits .failed with exit_code and surfaces issue lines to the agent" {
+	cat <<'EOF' | _settings
+{"inspector":{"enabled":true,"checks":{".ts":[
+	{"name":"broken","kind":"lint","argv":["sh","-c","echo 'src/sample.ts:1:1 - Bad'; exit 2"]}
+]}}}
+EOF
+	run _run_hook "$(_input)"
+	[ "$status" -eq 0 ]
+	[[ "$output" == *"inspector: src/sample.ts"* ]]
+	[[ "$output" == *"✗ broken"* ]]
+	[[ "$output" == *"src/sample.ts:1:1 - Bad"* ]]
+	[ "$(_event_count inspector.check.failed)" = "1" ]
+	[ "$(jq -r 'select(.event_type=="inspector.check.failed").payload.exit_code' "$ONLOOKER_EVENTS_LOG")" = "2" ]
+}
+
+@test "a missing tool emits .skipped with tool_missing and produces no agent output" {
+	echo '{"inspector":{"enabled":true,"checks":{".ts":[{"name":"ghost","kind":"lint","argv":["this-tool-does-not-exist"]}]}}}' | _settings
+	run _run_hook "$(_input)"
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+	[ "$(_event_count inspector.check.skipped)" = "1" ]
+	[ "$(jq -r 'select(.event_type=="inspector.check.skipped").payload.reason' "$ONLOOKER_EVENTS_LOG")" = "tool_missing" ]
+}
+
+@test "run.completed aggregates pass/fail/skip counts" {
+	cat <<'EOF' | _settings
+{"inspector":{"enabled":true,"checks":{".ts":[
+	{"name":"clean", "kind":"lint",      "argv":["true"]},
+	{"name":"broken","kind":"typecheck", "argv":["sh","-c","echo 'oops'; exit 1"]},
+	{"name":"ghost", "kind":"lint",      "argv":["this-tool-does-not-exist"]}
+]}}}
+EOF
+	run _run_hook "$(_input)"
+	[ "$status" -eq 0 ]
+	local completed
+	completed=$(jq -c 'select(.event_type=="inspector.run.completed").payload' "$ONLOOKER_EVENTS_LOG")
+	[ "$(echo "$completed" | jq -r '.checks_run')" = "2" ]
+	[ "$(echo "$completed" | jq -r '.checks_passed')" = "1" ]
+	[ "$(echo "$completed" | jq -r '.checks_failed')" = "1" ]
+	[ "$(echo "$completed" | jq -r '.checks_skipped')" = "1" ]
+}
+
+@test "argv is expanded with the touched file path" {
+	echo '{"inspector":{"enabled":true,"checks":{".ts":[{"name":"echo-file","kind":"lint","argv":["sh","-c","echo $1; test -n \"$1\"","--","${file}"]}]}}}' | _settings
+	run _run_hook "$(_input)"
+	[ "$status" -eq 0 ]
+	local argv
+	argv=$(jq -c 'select(.event_type=="inspector.check.passed").payload.argv' "$ONLOOKER_EVENTS_LOG")
+	# The last argv slot should now hold the resolved touched file path.
+	[[ "$(echo "$argv" | jq -r '.[-1]')" == *"src/sample.ts" ]]
+}

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

@@ -0,0 +1,68 @@
+#!/usr/bin/env bats
+
+# Exercises Inspector's project-key derivation.
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/inspector"
+	export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/inspector-project-key.sh"
+}
+
+@test "produces a 12-char hex key from origin remote" {
+	REPO="${BATS_TEST_TMPDIR}/repo"
+	mkdir -p "$REPO"
+	git -C "$REPO" init -q
+	git -C "$REPO" remote add origin "https://example.com/widgets.git"
+
+	local key
+	key=$(inspector_project_key "$REPO")
+	[ "${#key}" = "12" ]
+	[[ "$key" =~ ^[0-9a-f]{12}$ ]]
+}
+
+@test "remote-derived key is stable across temp clones" {
+	REPO_A="${BATS_TEST_TMPDIR}/a"; mkdir -p "$REPO_A"
+	REPO_B="${BATS_TEST_TMPDIR}/b"; mkdir -p "$REPO_B"
+	git -C "$REPO_A" init -q
+	git -C "$REPO_B" init -q
+	git -C "$REPO_A" remote add origin "https://example.com/x.git"
+	git -C "$REPO_B" remote add origin "https://example.com/x.git"
+
+	local key_a key_b
+	key_a=$(inspector_project_key "$REPO_A")
+	key_b=$(inspector_project_key "$REPO_B")
+	[ "$key_a" = "$key_b" ]
+}
+
+@test "falls back to repo root when origin is missing" {
+	REPO="${BATS_TEST_TMPDIR}/no-remote"
+	mkdir -p "$REPO"
+	git -C "$REPO" init -q
+	local key
+	key=$(inspector_project_key "$REPO")
+	[ "${#key}" = "12" ]
+}
+
+@test "falls back to cwd when not a git repo" {
+	NOT_REPO="${BATS_TEST_TMPDIR}/not-git"
+	mkdir -p "$NOT_REPO"
+	local key
+	key=$(inspector_project_key "$NOT_REPO")
+	[ "${#key}" = "12" ]
+}
+
+@test "project_repo_root returns repo top-level for a git checkout" {
+	REPO="${BATS_TEST_TMPDIR}/repo2"
+	mkdir -p "$REPO/sub"
+	git -C "$REPO" init -q
+	local root expected
+	root=$(inspector_project_repo_root "$REPO/sub")
+	# Canonicalize both sides: macOS git resolves tmp paths through /private/,
+	# while $REPO retains the symlinked /var/folders/ prefix.
+	expected=$(cd "$REPO" && /bin/pwd -P 2>/dev/null || pwd)
+	root=$(cd "$root" && /bin/pwd -P 2>/dev/null || pwd)
+	[ "$root" = "$expected" ]
+}

package/test/bats/inspector-ulid.bats

@@ -0,0 +1,34 @@
+#!/usr/bin/env bats
+
+# Exercises Inspector's ULID generator.
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/inspector"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/inspector-ulid.sh"
+}
+
+@test "produces a 26-char Crockford Base32 ULID" {
+	local id
+	id=$(inspector_ulid)
+	[ "${#id}" = "26" ]
+	[[ "$id" =~ ^[0-9ABCDEFGHJKMNPQRSTVWXYZ]{26}$ ]]
+}
+
+@test "produces unique values on consecutive calls" {
+	local a b
+	a=$(inspector_ulid)
+	b=$(inspector_ulid)
+	[ "$a" != "$b" ]
+}
+
+@test "is lexicographically sortable across a short delay" {
+	local a b
+	a=$(inspector_ulid)
+	# Sleep is intentionally <1ms to avoid lengthening the suite, but
+	# even back-to-back invocations should not regress the timestamp prefix.
+	b=$(inspector_ulid)
+	[[ "$a" < "$b" || "$a" == "$b" ]] || [[ "${a:0:10}" == "${b:0:10}" ]]
+}

package/test/bats/onlooker-schema.bats

@@ -0,0 +1,111 @@
+#!/usr/bin/env bats
+
+# Exercises scripts/lib/onlooker-schema.sh — the bash wrappers around the
+# canonical event emitter (scripts/lib/onlooker-event.mjs). Events are
+# validated against the real installed @onlooker-community/schema.
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	load_validate_path
+	export _ONLOOKER_EVENT_JS="${REPO_ROOT}/scripts/lib/onlooker-event.mjs"
+	export ONLOOKER_PLUGIN_NAME="onlooker"
+	# shellcheck disable=SC1091
+	source "${REPO_ROOT}/scripts/lib/onlooker-schema.sh"
+}
+
+_fixture() {
+	cat "${REPO_ROOT}/test/fixtures/hook-inputs/${1}"
+}
+
+# --- onlooker_append_event -------------------------------------------------
+
+@test "onlooker_append_event appends a parseable line carrying the event_type" {
+	local line
+	line='{"event_type":"tool.file.read","payload":{"path":"/x"}}'
+	run onlooker_append_event "$line"
+	[ "$status" -eq 0 ]
+
+	local last
+	last=$(tail -n 1 "$ONLOOKER_EVENTS_LOG")
+	# Round-trips through jq (valid JSON) and preserves the event_type.
+	[ "$(printf '%s' "$last" | jq -r '.event_type')" = "tool.file.read" ]
+}
+
+@test "onlooker_append_event with empty input is a no-op returning 0" {
+	run onlooker_append_event ""
+	[ "$status" -eq 0 ]
+	# No log line written.
+	[ ! -s "$ONLOOKER_EVENTS_LOG" ]
+}
+
+@test "onlooker_append_event creates parent dirs when missing" {
+	# Point the log at a path whose parent does not yet exist.
+	export ONLOOKER_EVENTS_LOG="${ONLOOKER_DIR}/nested/deeper/onlooker-events.jsonl"
+	[ ! -d "$(dirname "$ONLOOKER_EVENTS_LOG")" ]
+
+	run onlooker_append_event '{"event_type":"tool.file.read"}'
+	[ "$status" -eq 0 ]
+	[ -d "$(dirname "$ONLOOKER_EVENTS_LOG")" ]
+	[ "$(tail -n 1 "$ONLOOKER_EVENTS_LOG" | jq -r '.event_type')" = "tool.file.read" ]
+}
+
+@test "onlooker_append_event appends rather than truncating" {
+	onlooker_append_event '{"event_type":"tool.file.read"}'
+	onlooker_append_event '{"event_type":"tool.shell.exec"}'
+	[ "$(wc -l <"$ONLOOKER_EVENTS_LOG" | tr -d ' ')" -eq 2 ]
+	[ "$(tail -n 1 "$ONLOOKER_EVENTS_LOG" | jq -r '.event_type')" = "tool.shell.exec" ]
+}
+
+# --- onlooker_event_from_hook ----------------------------------------------
+
+@test "onlooker_event_from_hook maps a mappable fixture to tool.file.read" {
+	local event
+	event=$(onlooker_event_from_hook "$(_fixture post-tool-use-read.json)")
+	[ -n "$event" ]
+	[ "$(printf '%s' "$event" | jq -r '.event_type')" = "tool.file.read" ]
+}
+
+@test "onlooker_event_from_hook output validates against the schema" {
+	local event
+	event=$(onlooker_event_from_hook "$(_fixture post-tool-use-read.json)")
+	[ -n "$event" ]
+	printf '%s' "$event" | node "$_ONLOOKER_EVENT_JS" validate
+}
+
+@test "onlooker_event_from_hook prints empty for an unmappable fixture" {
+	local event
+	event=$(onlooker_event_from_hook "$(_fixture session-start-startup.json)")
+	[ -z "$event" ]
+}
+
+@test "onlooker_event_from_hook with empty input returns 0 and prints nothing" {
+	run onlooker_event_from_hook ""
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+}
+
+# --- onlooker_emit_from_hook -----------------------------------------------
+
+@test "onlooker_emit_from_hook writes exactly one tool.file.read line" {
+	run onlooker_emit_from_hook "$(_fixture post-tool-use-read.json)"
+	[ "$status" -eq 0 ]
+
+	[ "$(wc -l <"$ONLOOKER_EVENTS_LOG" | tr -d ' ')" -eq 1 ]
+	[ "$(tail -n 1 "$ONLOOKER_EVENTS_LOG" | jq -r '.event_type')" = "tool.file.read" ]
+}
+
+@test "onlooker_emit_from_hook leaves the log empty for an unmappable fixture" {
+	run onlooker_emit_from_hook "$(_fixture session-start-startup.json)"
+	[ "$status" -eq 0 ]
+	[ ! -s "$ONLOOKER_EVENTS_LOG" ]
+}
+
+@test "onlooker_emit_from_hook records blocked=true for a failed Bash tool" {
+	run onlooker_emit_from_hook "$(_fixture post-tool-use-failure-bash.json)"
+	[ "$status" -eq 0 ]
+
+	local last
+	last=$(tail -n 1 "$ONLOOKER_EVENTS_LOG")
+	[ "$(printf '%s' "$last" | jq -r '.event_type')" = "tool.shell.exec" ]
+	[ "$(printf '%s' "$last" | jq -r '.payload.blocked')" = "true" ]
+}

package/test/bats/prompt-rules.bats

@@ -267,3 +267,101 @@ write_project_rules() {
   echo "$out" | grep -A2 "id: r1" | grep -q "fired: yes"
   echo "$out" | grep -A2 "id: r2" | grep -q "fired: no"
 }
+
+@test "project_path: appends .claude/prompt-rules.json to the given cwd" {
+  local path
+  path=$(prompt_rules_project_path "/some/where")
+  [ "$path" = "/some/where/.claude/prompt-rules.json" ]
+}
+
+@test "project_path: defaults to \$PWD when no cwd is given" {
+  local path expected
+  path=$(prompt_rules_project_path)
+  expected="$PWD/.claude/prompt-rules.json"
+  [ "$path" = "$expected" ]
+}
+
+@test "fired_path: builds path under the sessions dir from the session id" {
+  local path expected
+  path=$(prompt_rules_fired_path "sess-XYZ")
+  expected="$ONLOOKER_PROMPT_RULES_SESSIONS_DIR/sess-XYZ.json"
+  [ "$path" = "$expected" ]
+}
+
+@test "fired_path: defaults session id to 'unknown' when none is given" {
+  local path expected
+  path=$(prompt_rules_fired_path)
+  expected="$ONLOOKER_PROMPT_RULES_SESSIONS_DIR/unknown.json"
+  [ "$path" = "$expected" ]
+}
+
+@test "emit: appends a JSON event line with type, session, payload, and plugin" {
+  : >"$ONLOOKER_EVENTS_LOG"
+  run prompt_rules_emit "sess-emit" "prompt_rule.matched" '{"rule_id":"rule-1"}'
+  [ "$status" -eq 0 ]
+
+  local line
+  line=$(tail -1 "$ONLOOKER_EVENTS_LOG")
+  [ "$(echo "$line" | jq -r '.event_type')" = "prompt_rule.matched" ]
+  [ "$(echo "$line" | jq -r '.session_id')" = "sess-emit" ]
+  [ "$(echo "$line" | jq -r '.payload.rule_id')" = "rule-1" ]
+  # No ONLOOKER_PLUGIN_NAME exported in this test → defaults to "onlooker".
+  [ "$(echo "$line" | jq -r '.plugin')" = "onlooker" ]
+}
+
+@test "emit: honors ONLOOKER_PLUGIN_NAME for the plugin field" {
+  : >"$ONLOOKER_EVENTS_LOG"
+  ONLOOKER_PLUGIN_NAME="prompt-rules" prompt_rules_emit "sess-plugin" "prompt_rule.applied" '{"rule_id":"r9"}'
+
+  local line
+  line=$(tail -1 "$ONLOOKER_EVENTS_LOG")
+  [ "$(echo "$line" | jq -r '.plugin')" = "prompt-rules" ]
+}
+
+@test "emit: defaults payload to an empty object when none is given" {
+  : >"$ONLOOKER_EVENTS_LOG"
+  run prompt_rules_emit "sess-nopayload" "prompt_rule.matched"
+  [ "$status" -eq 0 ]
+
+  local line
+  line=$(tail -1 "$ONLOOKER_EVENTS_LOG")
+  [ "$(echo "$line" | jq -c '.payload')" = "{}" ]
+}
+
+@test "emit: defaults session id to 'unknown' when none is given" {
+  : >"$ONLOOKER_EVENTS_LOG"
+  prompt_rules_emit "" "prompt_rule.matched" '{}'
+
+  local line
+  line=$(tail -1 "$ONLOOKER_EVENTS_LOG")
+  [ "$(echo "$line" | jq -r '.session_id')" = "unknown" ]
+}
+
+@test "emit: includes a numeric turn field when ONLOOKER_TURN_NUMBER is exported" {
+  : >"$ONLOOKER_EVENTS_LOG"
+  ONLOOKER_TURN_NUMBER=7 prompt_rules_emit "sess-turn" "prompt_rule.matched" '{}'
+
+  local line
+  line=$(tail -1 "$ONLOOKER_EVENTS_LOG")
+  [ "$(echo "$line" | jq -r '.turn')" = "7" ]
+  [ "$(echo "$line" | jq -r '.turn | type')" = "number" ]
+}
+
+@test "emit: omits the turn field when ONLOOKER_TURN_NUMBER is unset" {
+  : >"$ONLOOKER_EVENTS_LOG"
+  # Guard against any ambient value leaking in from the environment.
+  unset ONLOOKER_TURN_NUMBER
+  prompt_rules_emit "sess-noturn" "prompt_rule.matched" '{}'
+
+  local line
+  line=$(tail -1 "$ONLOOKER_EVENTS_LOG")
+  [ "$(echo "$line" | jq -e 'has("turn")')" = "false" ] || \
+    [ "$(echo "$line" | jq 'has("turn")')" = "false" ]
+}
+
+@test "emit: returns 1 and writes nothing when event_type is empty" {
+  : >"$ONLOOKER_EVENTS_LOG"
+  run prompt_rules_emit "sess-empty" ""
+  [ "$status" -eq 1 ]
+  [ ! -s "$ONLOOKER_EVENTS_LOG" ]
+}