@onlooker-community/ecosystem 0.3.3 → 0.5.0

package/.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "enabledPlugins": {
+    "ecosystem@onlooker-community": true
+  }
+}

package/.github/workflows/publish-npm.yml

@@ -93,9 +93,7 @@ jobs:
           cache: npm
 
       - run: npm ci
-      - run: npm run build
       - run: npm test
-      - run: npm run typecheck
 
   publish:
     name: Publish to npm
@@ -112,7 +110,6 @@ jobs:
           cache: npm
 
       - run: npm ci
-      - run: npm run build
 
       - name: Publish
         run: |

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.3.3"
+  ".": "0.5.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.5.0](https://github.com/onlooker-community/ecosystem/compare/v0.4.0...v0.5.0) (2026-05-22)
+
+
+### Features
+
+* **hooks:** add UserPromptSubmit turn and session duration trackers ([#12](https://github.com/onlooker-community/ecosystem/issues/12)) ([cbb7657](https://github.com/onlooker-community/ecosystem/commit/cbb7657979ed144efce506e6b487e037679b9462))
+
+## [0.4.0](https://github.com/onlooker-community/ecosystem/compare/v0.3.3...v0.4.0) (2026-05-22)
+
+
+### Features
+
+* **hooks:** add SessionStart and SessionEnd session trackers ([#10](https://github.com/onlooker-community/ecosystem/issues/10)) ([a48d680](https://github.com/onlooker-community/ecosystem/commit/a48d680dd24c98e79ef1c0401b07483ecebf9e8b))
+
 ## [0.3.3](https://github.com/onlooker-community/ecosystem/compare/v0.3.2...v0.3.3) (2026-05-22)
 
 

package/hooks/hooks.json

@@ -40,6 +40,20 @@
         ]
       }
     ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/turn-tracker.sh"
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/session-duration-tracker.sh"
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "*",
@@ -61,6 +75,28 @@
           }
         ]
       }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/session-start-tracker.sh"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/session-end-tracker.sh"
+          }
+        ]
+      }
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlooker-community/ecosystem",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "description": "Agents, skills, hooks, commands, rules, and MCP configurations that power [Onlooker](https://onlooker.dev)",
   "author": {
     "name": "Onlooker Community",

package/scripts/hooks/session-duration-tracker.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Onlooker Session Duration Tracker
+# Invoked by UserPromptSubmit when the user submits a prompt.
+#
+# Updates session_duration_ms on the tracker and injects turn + elapsed time
+# into Claude's context via UserPromptSubmit additionalContext.
+#
+# Usage:
+#   echo "$INPUT" | session-duration-tracker.sh
+
+set -uo pipefail # No -e: never block prompt submission
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../lib/validate-path.sh"
+source "$SCRIPT_DIR/../lib/session-tracker.sh"
+
+hook_register "session-duration-tracker" "Session Duration Tracker" "Surfaces session elapsed time on each user prompt"
+
+INPUT=$(cat)
+hook_set_context "$INPUT" "UserPromptSubmit"
+
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
+
+session_tracker_update_duration "$SESSION_ID" || hook_failure "Failed to update session duration"
+
+CONTEXT=$(session_tracker_build_duration_context "$SESSION_ID")
+if [[ -n "$CONTEXT" ]]; then
+	jq -n \
+		--arg ctx "$CONTEXT" \
+		'{
+			hookSpecificOutput: {
+				hookEventName: "UserPromptSubmit",
+				additionalContext: $ctx
+			}
+		}'
+fi
+
+hook_success
+exit 0

package/scripts/hooks/session-end-tracker.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Onlooker Session End Tracker
+# Invoked by SessionEnd (matcher: *) when a session ends.
+#
+# Emits session.end with duration and turn count, then cleans up hook bus dirs.
+# Default SessionEnd budget is 1.5s — keep this hook fast.
+#
+# Usage:
+#   echo "$INPUT" | session-end-tracker.sh
+
+set -uo pipefail # No -e: never block session termination
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../lib/validate-path.sh"
+source "$SCRIPT_DIR/../lib/onlooker-schema.sh"
+source "$SCRIPT_DIR/../lib/tool-history.sh"
+source "$SCRIPT_DIR/../lib/session-tracker.sh"
+
+hook_register "session-end-tracker" "Session End Tracker" "Records session.end and cleans up session resources"
+
+INPUT=$(cat)
+hook_set_context "$INPUT" "SessionEnd"
+
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
+
+PAYLOAD=$(session_tracker_build_end_payload "$SESSION_ID" "$INPUT")
+if [[ -n "$PAYLOAD" ]]; then
+	session_tracker_emit "$SESSION_ID" "session.end" "$PAYLOAD" \
+		|| hook_failure "Failed to emit session.end"
+fi
+
+hook_bus_cleanup
+
+hook_success
+exit 0

package/scripts/hooks/session-start-tracker.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Onlooker Session Start Tracker
+# Invoked by SessionStart (matcher: *) when a session starts or resumes.
+#
+# Initializes per-session tracker state and emits session.start for
+# startup, resume, and clear sources (compact is metadata-only).
+#
+# Usage:
+#   echo "$INPUT" | session-start-tracker.sh
+
+set -uo pipefail # No -e: never block session startup
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../lib/validate-path.sh"
+source "$SCRIPT_DIR/../lib/onlooker-schema.sh"
+source "$SCRIPT_DIR/../lib/tool-history.sh"
+source "$SCRIPT_DIR/../lib/session-tracker.sh"
+
+hook_register "session-start-tracker" "Session Start Tracker" "Records session.start and initializes session tracker"
+
+INPUT=$(cat)
+hook_set_context "$INPUT" "SessionStart"
+
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
+SOURCE=$(echo "$INPUT" | jq -r '.source // "startup"')
+
+session_tracker_record_start "$SESSION_ID" "$INPUT" || hook_failure "Failed to record session start metadata"
+
+# Compaction reuses the session; do not emit another session.start.
+if [[ "$SOURCE" != "compact" ]]; then
+	PAYLOAD=$(session_tracker_build_start_payload "$INPUT")
+	if [[ -n "$PAYLOAD" ]]; then
+		session_tracker_emit "$SESSION_ID" "session.start" "$PAYLOAD" \
+			|| hook_failure "Failed to emit session.start"
+	fi
+fi
+
+hook_success
+exit 0

package/scripts/hooks/turn-tracker.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Onlooker Turn Tracker
+# Invoked by UserPromptSubmit when the user submits a prompt.
+#
+# Advances per-session turn_number (first prompt stays at turn 1) and emits
+# canonical session.prompt for telemetry.
+#
+# Usage:
+#   echo "$INPUT" | turn-tracker.sh
+
+set -uo pipefail # No -e: never block prompt submission
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../lib/validate-path.sh"
+source "$SCRIPT_DIR/../lib/onlooker-schema.sh"
+source "$SCRIPT_DIR/../lib/tool-history.sh"
+source "$SCRIPT_DIR/../lib/session-tracker.sh"
+source "$SCRIPT_DIR/../lib/turn-tracker.sh"
+
+hook_register "turn-tracker" "Turn Tracker" "Tracks conversation turns and emits session.prompt"
+
+INPUT=$(cat)
+hook_set_context "$INPUT" "UserPromptSubmit"
+
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
+PROMPT=$(echo "$INPUT" | jq -r '.prompt // ""')
+
+turn_tracker_on_user_prompt "$SESSION_ID" || hook_failure "Failed to advance turn state"
+turn_state_export "$SESSION_ID"
+
+PAYLOAD=$(turn_tracker_build_prompt_payload "$SESSION_ID" "$PROMPT")
+if [[ -n "$PAYLOAD" ]]; then
+	session_tracker_emit "$SESSION_ID" "session.prompt" "$PAYLOAD" \
+		|| hook_failure "Failed to emit session.prompt"
+fi
+
+hook_success
+exit 0

package/scripts/lib/session-tracker.sh

@@ -0,0 +1,252 @@
+#!/usr/bin/env bash
+# Session lifecycle helpers — session.start / session.end canonical events.
+#
+# Source after validate-path.sh, onlooker-schema.sh, and tool-history.sh:
+#   source "$CLAUDE_PLUGIN_ROOT/scripts/lib/session-tracker.sh"
+
+# Milliseconds since epoch (macOS-compatible).
+session_tracker_now_ms() {
+	if [[ "$(uname)" == "Darwin" ]]; then
+		python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null || date +%s000
+	else
+		date +%s%3N 2>/dev/null || date +%s000
+	fi
+}
+
+# Optional git_branch and git_commit for a working directory (empty when not a repo).
+session_tracker_git_context() {
+	local cwd="${1:-}"
+	local branch="" commit=""
+	[[ -z "$cwd" ]] && return 0
+
+	if git -C "$cwd" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+		branch=$(git -C "$cwd" branch --show-current 2>/dev/null) || branch=""
+		commit=$(git -C "$cwd" rev-parse --short HEAD 2>/dev/null) || commit=""
+	fi
+
+	printf '%s\n%s' "$branch" "$commit"
+}
+
+# Map Claude Code SessionEnd reason to schema end_reason.
+session_tracker_map_end_reason() {
+	local reason="${1:-other}"
+	case "$reason" in
+	clear | logout | prompt_input_exit) echo "user_exit" ;;
+	timeout) echo "timeout" ;;
+	error) echo "error" ;;
+	task_complete) echo "task_complete" ;;
+	*) echo "unknown" ;;
+	esac
+}
+
+# Merge session start metadata into the per-session tracker file.
+# Usage: session_tracker_record_start "$SESSION_ID" "$INPUT_JSON"
+session_tracker_record_start() {
+	local session_id="${1:-}"
+	local input_json="${2:-}"
+	[[ -z "$session_id" || "$session_id" == "null" || -z "$input_json" ]] && return 0
+
+	turn_state_ensure_session "$session_id" || return 1
+
+	local tracker_file="$ONLOOKER_SESSION_TRACKERS_DIR/$session_id"
+	local now_ms source model cwd transcript_path agent_type
+	now_ms=$(session_tracker_now_ms)
+	source=$(echo "$input_json" | jq -r '.source // ""' 2>/dev/null) || source=""
+	model=$(echo "$input_json" | jq -r '.model // ""' 2>/dev/null) || model=""
+	cwd=$(echo "$input_json" | jq -r '.cwd // ""' 2>/dev/null) || cwd=""
+	transcript_path=$(echo "$input_json" | jq -r '.transcript_path // ""' 2>/dev/null) || transcript_path=""
+	agent_type=$(echo "$input_json" | jq -r '.agent_type // ""' 2>/dev/null) || agent_type=""
+
+	local temp_file
+	temp_file=$(mktemp)
+	if ! jq \
+		--argjson start_ms "$now_ms" \
+		--arg source "$source" \
+		--arg model "$model" \
+		--arg cwd "$cwd" \
+		--arg transcript "$transcript_path" \
+		--arg agent_type "$agent_type" \
+		'.start_time_ms = $start_ms
+		| .start_source = (if $source != "" then $source else .start_source end)
+		| .model = (if $model != "" then $model else .model end)
+		| .cwd = (if $cwd != "" then $cwd else .cwd end)
+		| .transcript_path = (if $transcript != "" then $transcript else .transcript_path end)
+		| .agent_type = (if $agent_type != "" then $agent_type else .agent_type end)' \
+		"$tracker_file" >"$temp_file" 2>/dev/null; then
+		rm -f "$temp_file"
+		return 1
+	fi
+	mv "$temp_file" "$tracker_file"
+}
+
+# Build session.start payload JSON from hook input and tracker state.
+# Usage: payload=$(session_tracker_build_start_payload "$INPUT_JSON")
+session_tracker_build_start_payload() {
+	local input_json="${1:-}"
+	local cwd
+	cwd=$(echo "$input_json" | jq -r '.cwd // ""' 2>/dev/null) || cwd=""
+	[[ -z "$cwd" ]] && cwd="$(pwd)"
+
+	local git_lines branch commit
+	git_lines=$(session_tracker_git_context "$cwd")
+	branch=$(echo "$git_lines" | sed -n '1p')
+	commit=$(echo "$git_lines" | sed -n '2p')
+
+	jq -n \
+		--arg wd "$cwd" \
+		--arg branch "$branch" \
+		--arg commit "$commit" \
+		'{
+			working_directory: $wd
+		}
+		+ (if $branch != "" then {git_branch: $branch} else {} end)
+		+ (if $commit != "" then {git_commit: $commit} else {} end)'
+}
+
+# Build session.end payload JSON from hook input and tracker file.
+# Usage: payload=$(session_tracker_build_end_payload "$SESSION_ID" "$INPUT_JSON")
+session_tracker_build_end_payload() {
+	local session_id="${1:-}"
+	local input_json="${2:-}"
+	[[ -z "$session_id" || "$session_id" == "null" ]] && return 1
+
+	local tracker_file="$ONLOOKER_SESSION_TRACKERS_DIR/$session_id"
+	local now_ms start_ms turn_count reason end_reason duration_ms
+	now_ms=$(session_tracker_now_ms)
+	reason=$(echo "$input_json" | jq -r '.reason // "other"' 2>/dev/null) || reason="other"
+	end_reason=$(session_tracker_map_end_reason "$reason")
+
+	if [[ -f "$tracker_file" ]]; then
+		start_ms=$(jq -r '.start_time_ms // 0' "$tracker_file" 2>/dev/null) || start_ms=0
+		turn_count=$(jq -r '.turn_number // 1' "$tracker_file" 2>/dev/null) || turn_count=1
+	else
+		start_ms=0
+		turn_count=1
+	fi
+
+	if [[ "$start_ms" =~ ^[0-9]+$ ]] && (( start_ms > 0 )); then
+		duration_ms=$((now_ms - start_ms))
+	else
+		duration_ms=0
+	fi
+	(( duration_ms < 0 )) && duration_ms=0
+
+	jq -n \
+		--argjson duration_ms "$duration_ms" \
+		--argjson turn_count "$turn_count" \
+		--arg end_reason "$end_reason" \
+		'{
+			duration_ms: $duration_ms,
+			turn_count: $turn_count,
+			end_reason: $end_reason
+		}'
+}
+
+# Elapsed session time in milliseconds (0 when start_time_ms is unset).
+# Usage: duration_ms=$(session_tracker_duration_ms "$SESSION_ID")
+session_tracker_duration_ms() {
+	local session_id="${1:-}"
+	[[ -z "$session_id" || "$session_id" == "null" ]] && echo 0 && return 0
+
+	local tracker_file="$ONLOOKER_SESSION_TRACKERS_DIR/$session_id"
+	local now_ms start_ms duration_ms
+	now_ms=$(session_tracker_now_ms)
+
+	if [[ ! -f "$tracker_file" ]]; then
+		echo 0
+		return 0
+	fi
+
+	start_ms=$(jq -r '.start_time_ms // 0' "$tracker_file" 2>/dev/null) || start_ms=0
+	if [[ ! "$start_ms" =~ ^[0-9]+$ ]] || (( start_ms <= 0 )); then
+		echo 0
+		return 0
+	fi
+
+	duration_ms=$((now_ms - start_ms))
+	(( duration_ms < 0 )) && duration_ms=0
+	echo "$duration_ms"
+}
+
+# Human-readable duration for hook context (e.g. "12m 34s", "45s").
+# Usage: label=$(session_tracker_format_duration 754000)
+session_tracker_format_duration() {
+	local duration_ms="${1:-0}"
+	[[ ! "$duration_ms" =~ ^[0-9]+$ ]] && duration_ms=0
+
+	local total_sec=$((duration_ms / 1000))
+	local hours=$((total_sec / 3600))
+	local minutes=$(((total_sec % 3600) / 60))
+	local seconds=$((total_sec % 60))
+
+	if (( hours > 0 )); then
+		printf '%dh %dm' "$hours" "$minutes"
+	elif (( minutes > 0 )); then
+		printf '%dm %ds' "$minutes" "$seconds"
+	else
+		printf '%ds' "$seconds"
+	fi
+}
+
+# Persist session_duration_ms on the per-session tracker file.
+# Usage: session_tracker_update_duration "$SESSION_ID"
+session_tracker_update_duration() {
+	local session_id="${1:-}"
+	[[ -z "$session_id" || "$session_id" == "null" ]] && return 0
+
+	turn_state_ensure_session "$session_id" || return 1
+
+	local tracker_file="$ONLOOKER_SESSION_TRACKERS_DIR/$session_id"
+	local duration_ms
+	duration_ms=$(session_tracker_duration_ms "$session_id")
+
+	local temp_file
+	temp_file=$(mktemp)
+	if ! jq --argjson duration_ms "$duration_ms" \
+		'.session_duration_ms = $duration_ms' \
+		"$tracker_file" >"$temp_file" 2>/dev/null; then
+		rm -f "$temp_file"
+		return 1
+	fi
+	mv "$temp_file" "$tracker_file"
+}
+
+# Build additionalContext line for UserPromptSubmit (turn + elapsed time).
+# Usage: context=$(session_tracker_build_duration_context "$SESSION_ID")
+session_tracker_build_duration_context() {
+	local session_id="${1:-}"
+	local duration_ms turn_number elapsed
+	duration_ms=$(session_tracker_duration_ms "$session_id")
+	elapsed=$(session_tracker_format_duration "$duration_ms")
+
+	if [[ -f "$ONLOOKER_SESSION_TRACKERS_DIR/$session_id" ]]; then
+		turn_number=$(jq -r '.turn_number // 1' "$ONLOOKER_SESSION_TRACKERS_DIR/$session_id" 2>/dev/null) || turn_number=1
+	else
+		turn_number=1
+	fi
+
+	printf 'Onlooker session: turn %s · elapsed %s' "$turn_number" "$elapsed"
+}
+
+# Emit a validated canonical session event and append to logs.
+# Usage: session_tracker_emit "$SESSION_ID" "session.start" "$payload_json"
+session_tracker_emit() {
+	local session_id="${1:-}"
+	local event_type="${2:-}"
+	local payload_json="${3:-}"
+	[[ -z "$session_id" || -z "$event_type" || -z "$payload_json" ]] && return 0
+
+	local params event
+	params=$(jq -n \
+		--arg plugin "${ONLOOKER_PLUGIN_NAME:-onlooker}" \
+		--arg sid "$session_id" \
+		--arg type "$event_type" \
+		--argjson payload "$payload_json" \
+		'{plugin: $plugin, session_id: $sid, event_type: $type, payload: $payload}')
+
+	event=$(printf '%s' "$params" | ONLOOKER_DIR="$ONLOOKER_DIR" ONLOOKER_PLUGIN_NAME="$ONLOOKER_PLUGIN_NAME" \
+		node "${_ONLOOKER_EVENT_JS:-${CLAUDE_PLUGIN_ROOT:-}/scripts/lib/onlooker-event.mjs}" emit 2>/dev/null) || return 1
+
+	tool_history_append "$session_id" "$event" || return 1
+	onlooker_append_event "$event" || return 1
+}

package/scripts/lib/turn-tracker.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Turn tracking helpers for UserPromptSubmit hooks.
+#
+# Source after validate-path.sh, onlooker-schema.sh, tool-history.sh, session-tracker.sh:
+#   source "$CLAUDE_PLUGIN_ROOT/scripts/lib/turn-tracker.sh"
+
+# Truncate prompt text for session.prompt input_summary.
+# Usage: summary=$(turn_tracker_summarize_prompt "$PROMPT")
+turn_tracker_summarize_prompt() {
+	local prompt="${1:-}"
+	[[ -z "$prompt" ]] && return 0
+
+	local summary
+	summary=$(printf '%s' "$prompt" | tr '\n' ' ' | sed 's/  */ /g' | sed 's/^ //;s/ $//')
+	if ((${#summary} > 200)); then
+		summary="${summary:0:200}…"
+	fi
+	printf '%s' "$summary"
+}
+
+# Advance turn state when the user submits a prompt (first prompt stays at turn 1).
+# Usage: turn_tracker_on_user_prompt "$SESSION_ID"
+turn_tracker_on_user_prompt() {
+	local session_id="${1:-}"
+	[[ -z "$session_id" || "$session_id" == "null" ]] && return 0
+
+	turn_state_ensure_session "$session_id" || return 1
+
+	local tracker_file="$ONLOOKER_SESSION_TRACKERS_DIR/$session_id"
+	local seen
+	seen=$(jq -r '.user_prompts_seen // false' "$tracker_file" 2>/dev/null) || seen="false"
+
+	if [[ "$seen" == "true" ]]; then
+		turn_state_next_turn "$session_id" || return 1
+	else
+		local temp_file
+		temp_file=$(mktemp)
+		if ! jq '.user_prompts_seen = true | .turn_tool_seq = 0' \
+			"$tracker_file" >"$temp_file" 2>/dev/null; then
+			rm -f "$temp_file"
+			return 1
+		fi
+		mv "$temp_file" "$tracker_file"
+	fi
+}
+
+# Build session.prompt payload for the current turn.
+# Usage: payload=$(turn_tracker_build_prompt_payload "$SESSION_ID" "$PROMPT")
+turn_tracker_build_prompt_payload() {
+	local session_id="${1:-}"
+	local prompt="${2:-}"
+	[[ -z "$session_id" || "$session_id" == "null" ]] && return 1
+
+	local turn_number summary
+	if [[ -f "$ONLOOKER_SESSION_TRACKERS_DIR/$session_id" ]]; then
+		turn_number=$(jq -r '.turn_number // 1' "$ONLOOKER_SESSION_TRACKERS_DIR/$session_id" 2>/dev/null) || turn_number=1
+	else
+		turn_number=1
+	fi
+
+	summary=$(turn_tracker_summarize_prompt "$prompt")
+
+	jq -n \
+		--argjson turn_number "$turn_number" \
+		--arg summary "$summary" \
+		'{turn_number: $turn_number}
+		+ (if $summary != "" then {input_summary: $summary} else {} end)'
+}

package/test/bats/config.bats

@@ -84,6 +84,52 @@ setup_file() {
   [[ "$hook_cmd" == *tool-history-tracker.sh ]]
 }
 
+@test "hooks.json UserPromptSubmit references turn and session-duration trackers" {
+  run jq -e '.hooks.UserPromptSubmit[0].hooks | length == 2' "${REPO_ROOT}/hooks/hooks.json"
+  [ "$status" -eq 0 ]
+
+  local turn_cmd duration_cmd
+  turn_cmd=$(jq -r '.hooks.UserPromptSubmit[0].hooks[0].command' "${REPO_ROOT}/hooks/hooks.json")
+  duration_cmd=$(jq -r '.hooks.UserPromptSubmit[0].hooks[1].command' "${REPO_ROOT}/hooks/hooks.json")
+  [[ "$turn_cmd" == *turn-tracker.sh ]]
+  [[ "$duration_cmd" == *session-duration-tracker.sh ]]
+
+  for hook_cmd in "$turn_cmd" "$duration_cmd"; do
+    local script_path="${hook_cmd//\$CLAUDE_PLUGIN_ROOT/$REPO_ROOT}"
+    script_path="${script_path//\"/}"
+    run test -x "$script_path"
+    [ "$status" -eq 0 ]
+  done
+}
+
+@test "hooks.json SessionStart references session-start-tracker" {
+  run jq -e '.hooks.SessionStart[0].matcher == "*"' "${REPO_ROOT}/hooks/hooks.json"
+  [ "$status" -eq 0 ]
+
+  local hook_cmd
+  hook_cmd=$(jq -r '.hooks.SessionStart[0].hooks[0].command' "${REPO_ROOT}/hooks/hooks.json")
+  [[ "$hook_cmd" == *session-start-tracker.sh ]]
+
+  local script_path="${hook_cmd//\$CLAUDE_PLUGIN_ROOT/$REPO_ROOT}"
+  script_path="${script_path//\"/}"
+  run test -x "$script_path"
+  [ "$status" -eq 0 ]
+}
+
+@test "hooks.json SessionEnd references session-end-tracker" {
+  run jq -e '.hooks.SessionEnd[0].matcher == "*"' "${REPO_ROOT}/hooks/hooks.json"
+  [ "$status" -eq 0 ]
+
+  local hook_cmd
+  hook_cmd=$(jq -r '.hooks.SessionEnd[0].hooks[0].command' "${REPO_ROOT}/hooks/hooks.json")
+  [[ "$hook_cmd" == *session-end-tracker.sh ]]
+
+  local script_path="${hook_cmd//\$CLAUDE_PLUGIN_ROOT/$REPO_ROOT}"
+  script_path="${script_path//\"/}"
+  run test -x "$script_path"
+  [ "$status" -eq 0 ]
+}
+
 @test "plugin.json is valid JSON" {
   run jq -e '.name and .version' "${REPO_ROOT}/.claude-plugin/plugin.json"
   [ "$status" -eq 0 ]

package/test/bats/session-tracker.bats

@@ -0,0 +1,75 @@
+#!/usr/bin/env bats
+
+setup() {
+  # shellcheck source=../helpers/setup.bash
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  load_validate_path
+  export CLAUDE_PLUGIN_ROOT="${REPO_ROOT}"
+  # shellcheck source=../../scripts/lib/session-tracker.sh
+  source "${REPO_ROOT}/scripts/lib/onlooker-schema.sh"
+  source "${REPO_ROOT}/scripts/lib/tool-history.sh"
+  source "${REPO_ROOT}/scripts/lib/session-tracker.sh"
+}
+
+@test "session-start-tracker emits session.start for startup source" {
+  local fixture="${REPO_ROOT}/test/fixtures/hook-inputs/session-start-startup.json"
+  local history_file="${ONLOOKER_SESSION_HISTORY_DIR}/session-start-001.jsonl"
+  rm -f "$history_file"
+
+  run bash -c "cat '${fixture}' | '${REPO_ROOT}/scripts/hooks/session-start-tracker.sh' 2>/dev/null"
+  [ "$status" -eq 0 ]
+
+  [ -f "$history_file" ]
+  jq -e '.event_type == "session.start"
+    and .session_id == "session-start-001"
+    and .payload.working_directory == "/project/repo"' \
+    "$history_file" >/dev/null
+
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/session-start-001"
+  jq -e '.start_source == "startup" and (.start_time_ms | type) == "number"' "$tracker" >/dev/null
+}
+
+@test "session-start-tracker does not emit session.start for compact source" {
+  local fixture="${REPO_ROOT}/test/fixtures/hook-inputs/session-start-compact.json"
+  local history_file="${ONLOOKER_SESSION_HISTORY_DIR}/session-start-002.jsonl"
+  rm -f "$history_file"
+
+  run bash -c "cat '${fixture}' | '${REPO_ROOT}/scripts/hooks/session-start-tracker.sh' 2>/dev/null"
+  [ "$status" -eq 0 ]
+  [ ! -f "$history_file" ]
+
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/session-start-002"
+  jq -e '.start_source == "compact"' "$tracker" >/dev/null
+}
+
+@test "session-end-tracker emits session.end with duration and turn count" {
+  local start_fixture="${REPO_ROOT}/test/fixtures/hook-inputs/session-start-startup.json"
+  local end_fixture="${REPO_ROOT}/test/fixtures/hook-inputs/session-end-other.json"
+  local session_id="session-end-001"
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/${session_id}"
+  local history_file="${ONLOOKER_SESSION_HISTORY_DIR}/${session_id}.jsonl"
+
+  rm -f "$history_file" "$tracker"
+
+  # Seed tracker as if session had been running
+  turn_state_ensure_session "$session_id"
+  local past_ms
+  past_ms=$(python3 -c 'import time; print(int((time.time() - 2) * 1000))' 2>/dev/null || echo 0)
+  jq --argjson start_ms "$past_ms" '.start_time_ms = $start_ms | .turn_number = 3' "$tracker" >"${tracker}.tmp"
+  mv "${tracker}.tmp" "$tracker"
+
+  run bash -c "cat '${end_fixture}' | '${REPO_ROOT}/scripts/hooks/session-end-tracker.sh' 2>/dev/null"
+  [ "$status" -eq 0 ]
+
+  jq -e '.event_type == "session.end"
+    and .session_id == "session-end-001"
+    and .payload.turn_count == 3
+    and .payload.end_reason == "unknown"
+    and (.payload.duration_ms | type) == "number"
+    and .payload.duration_ms >= 0' \
+    "$history_file" >/dev/null
+}
+
+@test "session_tracker_map_end_reason maps logout to user_exit" {
+  [ "$(session_tracker_map_end_reason logout)" = "user_exit" ]
+}

package/test/bats/user-prompt-submit-tracker.bats

@@ -0,0 +1,74 @@
+#!/usr/bin/env bats
+
+setup() {
+  # shellcheck source=../helpers/setup.bash
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  load_validate_path
+  export CLAUDE_PLUGIN_ROOT="${REPO_ROOT}"
+  source "${REPO_ROOT}/scripts/lib/onlooker-schema.sh"
+  source "${REPO_ROOT}/scripts/lib/tool-history.sh"
+  source "${REPO_ROOT}/scripts/lib/session-tracker.sh"
+  source "${REPO_ROOT}/scripts/lib/turn-tracker.sh"
+}
+
+@test "turn-tracker emits session.prompt on first user prompt at turn 1" {
+  local fixture="${REPO_ROOT}/test/fixtures/hook-inputs/user-prompt-submit.json"
+  local session_id="prompt-session-001"
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/${session_id}"
+  local history_file="${ONLOOKER_SESSION_HISTORY_DIR}/${session_id}.jsonl"
+  rm -f "$tracker" "$history_file"
+
+  turn_state_ensure_session "$session_id"
+  jq '.start_time_ms = 1000' "$tracker" >"${tracker}.tmp" && mv "${tracker}.tmp" "$tracker"
+
+  run bash -c "cat '${fixture}' | '${REPO_ROOT}/scripts/hooks/turn-tracker.sh' 2>/dev/null"
+  [ "$status" -eq 0 ]
+
+  jq -e '.turn_number == 1 and .user_prompts_seen == true' "$tracker" >/dev/null
+  jq -e '.event_type == "session.prompt"
+    and .payload.turn_number == 1
+    and (.payload.input_summary | contains("UserPromptSubmit"))' \
+    "$history_file" >/dev/null
+}
+
+@test "turn-tracker increments turn on second user prompt" {
+  local fixture="${REPO_ROOT}/test/fixtures/hook-inputs/user-prompt-submit-turn2.json"
+  local session_id="prompt-session-002"
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/${session_id}"
+  rm -f "$tracker"
+
+  turn_state_ensure_session "$session_id"
+  jq '.user_prompts_seen = true | .turn_number = 1' "$tracker" >"${tracker}.tmp" && mv "${tracker}.tmp" "$tracker"
+
+  cat "$fixture" | "${REPO_ROOT}/scripts/hooks/turn-tracker.sh" >/dev/null 2>&1
+
+  jq -e '.turn_number == 2 and .turn_tool_seq == 0' "$tracker" >/dev/null
+}
+
+@test "session-duration-tracker outputs additionalContext with elapsed time" {
+  local fixture="${REPO_ROOT}/test/fixtures/hook-inputs/user-prompt-submit.json"
+  local session_id="prompt-session-001"
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/${session_id}"
+  rm -f "$tracker"
+
+  turn_state_ensure_session "$session_id"
+  local past_ms
+  past_ms=$(python3 -c 'import time; print(int((time.time() - 65) * 1000))' 2>/dev/null || echo 0)
+  jq --argjson start_ms "$past_ms" \
+    '.start_time_ms = $start_ms | .turn_number = 2' \
+    "$tracker" >"${tracker}.tmp" && mv "${tracker}.tmp" "$tracker"
+
+  run bash -c "cat '${fixture}' | '${REPO_ROOT}/scripts/hooks/session-duration-tracker.sh' 2>/dev/null"
+  [ "$status" -eq 0 ]
+
+  echo "$output" | jq -e \
+    '.hookSpecificOutput.hookEventName == "UserPromptSubmit"
+    and (.hookSpecificOutput.additionalContext | contains("turn 2"))
+    and (.hookSpecificOutput.additionalContext | contains("elapsed"))' >/dev/null
+
+  jq -e '(.session_duration_ms | type) == "number" and .session_duration_ms >= 60000' "$tracker" >/dev/null
+}
+
+@test "session_tracker_format_duration renders minutes and seconds" {
+  [ "$(session_tracker_format_duration 65000)" = "1m 5s" ]
+}

package/test/fixtures/hook-inputs/session-end-other.json

@@ -0,0 +1,7 @@
+{
+  "session_id": "session-end-001",
+  "transcript_path": "/tmp/transcript.jsonl",
+  "cwd": "/project/repo",
+  "hook_event_name": "SessionEnd",
+  "reason": "other"
+}

package/test/fixtures/hook-inputs/session-start-compact.json

@@ -0,0 +1,8 @@
+{
+  "session_id": "session-start-002",
+  "transcript_path": "/tmp/transcript.jsonl",
+  "cwd": "/project/repo",
+  "hook_event_name": "SessionStart",
+  "source": "compact",
+  "model": "claude-sonnet-4-6"
+}

package/test/fixtures/hook-inputs/session-start-startup.json

@@ -0,0 +1,8 @@
+{
+  "session_id": "session-start-001",
+  "transcript_path": "/tmp/transcript.jsonl",
+  "cwd": "/project/repo",
+  "hook_event_name": "SessionStart",
+  "source": "startup",
+  "model": "claude-sonnet-4-6"
+}

package/test/fixtures/hook-inputs/user-prompt-submit-turn2.json

@@ -0,0 +1,8 @@
+{
+  "session_id": "prompt-session-002",
+  "transcript_path": "/tmp/transcript.jsonl",
+  "cwd": "/project/repo",
+  "permission_mode": "default",
+  "hook_event_name": "UserPromptSubmit",
+  "prompt": "Follow-up prompt for turn increment test"
+}

package/test/fixtures/hook-inputs/user-prompt-submit.json

@@ -0,0 +1,8 @@
+{
+  "session_id": "prompt-session-001",
+  "transcript_path": "/tmp/transcript.jsonl",
+  "cwd": "/project/repo",
+  "permission_mode": "default",
+  "hook_event_name": "UserPromptSubmit",
+  "prompt": "Add turn tracking hooks for UserPromptSubmit"
+}