@onlooker-community/ecosystem 0.15.2 → 0.17.0

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

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# Config resolution for Governor.
+#
+# Reads three layers, latest wins:
+#   1. plugins/governor/config.json (defaults shipped with the plugin)
+#   2. ~/.claude/settings.json
+#   3. <repo>/.claude/settings.json
+#
+# Exposes:
+#   governor_config_load <repo_root>     # populates _GOVERNOR_CONFIG (JSON)
+#   governor_config_get <jq-path>        # echoes string value (empty if unset)
+#   governor_config_get_json <jq-path>   # echoes JSON value (null if unset)
+#   governor_config_enabled              # 0 if governor.enabled is true
+#   governor_config_enforcement          # echoes "soft" or "hard"
+
+_GOVERNOR_CONFIG="{}"
+
+governor_config_load() {
+	local repo_root="${1:-}"
+	local plugin_root="${CLAUDE_PLUGIN_ROOT:-}"
+	local home_dir="${HOME:-}"
+
+	local merged="{}"
+	local file
+
+	file="${plugin_root}/config.json"
+	if [[ -f "$file" ]]; then
+		local defaults
+		defaults=$(jq '.' "$file" 2>/dev/null) || defaults="{}"
+		merged=$(jq -n --argjson a "$merged" --argjson b "$defaults" '$a * $b' 2>/dev/null) \
+			|| merged="$defaults"
+	fi
+
+	local repo_settings=""
+	[[ -n "$repo_root" ]] && repo_settings="${repo_root}/.claude/settings.json"
+
+	for file in "${home_dir}/.claude/settings.json" "$repo_settings"; do
+		[[ -n "$file" && -f "$file" ]] || continue
+		local overlay
+		overlay=$(jq '{ governor: (.governor // {}) }' "$file" 2>/dev/null) || continue
+		[[ -z "$overlay" ]] && continue
+		local attempt
+		if attempt=$(jq -n --argjson a "$merged" --argjson b "$overlay" '
+			def deepmerge($a; $b):
+				if ($a|type) == "object" and ($b|type) == "object" then
+					reduce (($a|keys) + ($b|keys) | unique)[] as $k
+						({}; .[$k] = deepmerge($a[$k]; $b[$k]))
+				elif $b == null then $a
+				else $b end;
+			deepmerge($a; $b)
+		' 2>/dev/null) && [[ -n "$attempt" ]]; then
+			merged="$attempt"
+		fi
+	done
+
+	_GOVERNOR_CONFIG="$merged"
+}
+
+governor_config_get() {
+	local path="$1"
+	printf '%s' "$_GOVERNOR_CONFIG" | jq -r "${path} // empty" 2>/dev/null
+}
+
+governor_config_get_json() {
+	local path="$1"
+	printf '%s' "$_GOVERNOR_CONFIG" | jq -c "${path}" 2>/dev/null
+}
+
+governor_config_enabled() {
+	local v
+	v=$(governor_config_get '.governor.enabled')
+	[[ "$v" == "true" ]]
+}
+
+governor_config_enforcement() {
+	local v
+	v=$(governor_config_get '.governor.enforcement')
+	printf '%s' "${v:-soft}"
+}

package/plugins/governor/scripts/lib/governor-estimate.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# Token estimation for the governor pre-call gate.
+#
+# Uses a tier-table approach: estimate from tool input JSON size with a
+# per-content-type characters-per-token ratio, then multiply by a
+# configurable safety margin.
+#
+# Tier table (characters per token):
+#   ASCII prose      4.0
+#   code / JSON      3.0
+#   mixed            2.5
+#   non-Latin        1.5
+#
+# Safety margin (config: governor.estimation.safety_margin, default 1.3)
+# is applied before the gate check. Hard stop margin
+# (governor.estimation.hard_stop_margin, default 1.5) is the threshold
+# for a blocking decision regardless of enforcement mode.
+#
+# Estimation method tag emitted in governor.gate.checked: "tier_table"
+#
+# Exposes:
+#   governor_estimate_tokens <json_input>   # echoes integer estimate
+#   governor_estimate_cost <tokens> <model> # echoes float USD estimate
+#   governor_estimate_method                # echoes "tier_table"
+
+governor_estimate_method() {
+	printf 'tier_table'
+}
+
+# Detect content tier from a sample of text.
+# Returns one of: ascii_prose code_json mixed non_latin
+_governor_detect_tier() {
+	local sample="${1:-}"
+	local len=${#sample}
+	[[ $len -eq 0 ]] && { printf 'ascii_prose'; return 0; }
+
+	# Check for structural characters that signal code/JSON
+	local struct_count
+	struct_count=$(printf '%s' "$sample" | tr -cd '{}[]():;=><' | wc -c 2>/dev/null) \
+		|| struct_count=0
+	struct_count=$(printf '%s' "$struct_count" | tr -d ' ')
+
+	# >= 10% structural → code/JSON
+	if (( struct_count * 10 >= len )); then
+		printf 'code_json'
+		return 0
+	fi
+
+	# Non-ASCII byte presence signals non-Latin
+	local ascii_count
+	ascii_count=$(printf '%s' "$sample" | tr -cd '[:print:][:space:]' | wc -c 2>/dev/null) \
+		|| ascii_count=$len
+	ascii_count=$(printf '%s' "$ascii_count" | tr -d ' ')
+
+	if (( ascii_count * 10 < len * 7 )); then
+		printf 'non_latin'
+		return 0
+	fi
+
+	# 5–9% structural → mixed (prose with embedded code/JSON)
+	if (( struct_count * 20 >= len )); then
+		printf 'mixed'
+		return 0
+	fi
+
+	printf 'ascii_prose'
+}
+
+# Estimate token count from a JSON input string.
+# Usage: tokens=$(governor_estimate_tokens "$json_input")
+governor_estimate_tokens() {
+	local json_input="${1:-}"
+	local safety_margin="${2:-}"
+
+	[[ -z "$safety_margin" ]] && {
+		safety_margin=$(governor_config_get '.governor.estimation.safety_margin' 2>/dev/null)
+		safety_margin="${safety_margin:-1.3}"
+	}
+
+	local char_count=${#json_input}
+	[[ $char_count -eq 0 ]] && { printf '100'; return 0; }
+
+	local sample="${json_input:0:2000}"
+	local tier
+	tier=$(_governor_detect_tier "$sample")
+
+	local chars_per_token
+	case "$tier" in
+		code_json)  chars_per_token="3.0" ;;
+		mixed)      chars_per_token="2.5" ;;
+		non_latin)  chars_per_token="1.5" ;;
+		*)          chars_per_token="4.0" ;;
+	esac
+
+	# Single awk pass for fractional chars_per_token and safety margin
+	local tokens
+	tokens=$(awk "BEGIN { printf \"%d\", int($char_count / $chars_per_token * $safety_margin + 0.999) }" 2>/dev/null) \
+		|| tokens=$(( char_count * 2 ))
+	(( tokens < 1 )) && tokens=1
+
+	printf '%s' "$tokens"
+}
+
+# Rough USD cost estimate from token count.
+# Uses Sonnet-class pricing as a conservative default (~$3/M input, $15/M output).
+# governor is not aware of the actual model being spawned, so this is a
+# planning-time upper bound.
+#
+# Usage: cost=$(governor_estimate_cost 5000)
+governor_estimate_cost() {
+	local tokens="${1:-0}"
+
+	# $3 per 1M input + $15 per 1M output; assume 50/50 split → ~$9/M blended
+	awk "BEGIN { printf \"%.6f\", ($tokens / 1000000.0) * 9.0 }" 2>/dev/null \
+		|| printf '0.0'
+}

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

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# Canonical governor.* event emission.
+#
+# Thin wrapper around the ecosystem plugin's onlooker-event.mjs `emit` mode.
+# Every emission is validated against @onlooker-community/schema v2.4.0+
+# before being appended to ~/.onlooker/logs/onlooker-events.jsonl.
+#
+# Usage:
+#   governor_emit_event "governor.gate.checked" '{"session_id":"...","decision":"allow",...}'
+
+_GOVERNOR_PLUGIN_NAME="governor"
+
+_governor_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
+}
+
+_governor_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 governor.* event. Returns 0 on success, non-zero on failure.
+governor_emit_event() {
+	local event_type="${1:-}"
+	local payload="${2:-}"
+
+	[[ -z "$event_type" || -z "$payload" ]] && return 1
+
+	local event_js
+	event_js=$(_governor_event_js_path) || return 1
+
+	local session_id
+	session_id=$(_governor_session_id)
+
+	local params
+	params=$(jq -n \
+		--arg plugin "$_GOVERNOR_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
+	local stderr_file
+	stderr_file=$(mktemp -t governor-event-err.XXXXXX 2>/dev/null) || stderr_file="/tmp/governor-event-err.$$"
+	event=$(printf '%s' "$params" \
+		| ONLOOKER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}" \
+		  ONLOOKER_PLUGIN_NAME="$_GOVERNOR_PLUGIN_NAME" \
+		  node "$event_js" emit 2>"$stderr_file") || {
+		printf 'governor_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/governor/scripts/lib/governor-ledger.sh

@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+# JSONL ledger read/write for the governor plugin.
+#
+# Two-phase accounting model:
+#
+#   1. PreToolUse (gate): writes a "reservation" record inside the gate
+#      lock with estimated_tokens > 0. This ensures concurrent spawns
+#      each see the others' in-flight cost before deciding to allow.
+#
+#   2. PostToolUse (completion): writes a "Task" record with
+#      estimated_tokens = -(original estimate) to cancel the reservation,
+#      plus actual_tokens = observed count (if available). Net effect:
+#
+#        in-flight:  estimated_tokens(reservation) = N_est
+#        completed:  estimated_tokens(Task) = -N_est, actual_tokens = N_act
+#        total:      N_est + (-N_est) + N_act = N_act  ✓
+#
+# governor_ledger_total_tokens sums (.estimated_tokens + .actual_tokens)
+# across all records so the running total is always:
+#   (in-flight reservation estimates) + (completed actuals)
+#
+# Requires portable-lock.sh to be sourced beforehand.
+
+GOVERNOR_LEDGER_MAX_RETRIES=3
+GOVERNOR_LEDGER_LOCK_TIMEOUT=5
+
+governor_ledger_path() {
+	local session_id="${1:-unknown}"
+	local dir="${ONLOOKER_DIR:-${HOME}/.onlooker}/governance/ledgers"
+	local safe_id
+	safe_id=$(printf '%s' "$session_id" | tr -c 'a-zA-Z0-9-' '_')
+	printf '%s/%s.jsonl' "$dir" "$safe_id"
+}
+
+governor_ledger_poison_path() {
+	local ledger_path="${1:-}"
+	printf '%s.poisoned' "$ledger_path"
+}
+
+governor_ledger_is_poisoned() {
+	local session_id="${1:-}"
+	local ledger_path
+	ledger_path=$(governor_ledger_path "$session_id")
+	[[ -f "$(governor_ledger_poison_path "$ledger_path")" ]]
+}
+
+# Append a record to the ledger under the ledger's own write lock.
+# Safe to call from PostToolUse and other hooks that do not already hold
+# the gate lock. For writing inside the gate lock use governor_ledger_write_direct.
+#
+# Usage: governor_ledger_append "$session_id" "$record_json"
+governor_ledger_append() {
+	local session_id="${1:-}"
+	local record="${2:-}"
+
+	[[ -z "$session_id" || -z "$record" ]] && return 1
+
+	local ledger_path
+	ledger_path=$(governor_ledger_path "$session_id")
+	local lock_path="${ledger_path}.lock"
+
+	mkdir -p "$(dirname "$ledger_path")" 2>/dev/null || return 1
+
+	local attempt=0
+	local unrecorded_tokens=0
+	unrecorded_tokens=$(printf '%s' "$record" | jq -r '.estimated_tokens // 0' 2>/dev/null) \
+		|| unrecorded_tokens=0
+
+	while (( attempt < GOVERNOR_LEDGER_MAX_RETRIES )); do
+		if lock_acquire "$lock_path" "$GOVERNOR_LEDGER_LOCK_TIMEOUT"; then
+			printf '%s\n' "$(printf '%s' "$record" | jq -c . 2>/dev/null)" >> "$ledger_path" 2>/dev/null
+			local write_ok=$?
+			lock_release "$lock_path"
+			if (( write_ok == 0 )); then
+				return 0
+			fi
+		fi
+		attempt=$(( attempt + 1 ))
+	done
+
+	_governor_ledger_poison "$session_id" "$ledger_path" "$unrecorded_tokens"
+	return 1
+}
+
+# Write a record directly to the ledger file without acquiring the write
+# lock. ONLY call this when you already hold the gate lock, which serializes
+# access. The gate lock is the same as the write lock (same .lock path), so
+# re-acquiring it here would deadlock.
+#
+# Usage: governor_ledger_write_direct "$ledger_path" "$record_json"
+governor_ledger_write_direct() {
+	local ledger_path="${1:-}"
+	local record="${2:-}"
+
+	[[ -z "$ledger_path" || -z "$record" ]] && return 1
+
+	mkdir -p "$(dirname "$ledger_path")" 2>/dev/null || return 1
+	printf '%s\n' "$(printf '%s' "$record" | jq -c . 2>/dev/null)" >> "$ledger_path" 2>/dev/null
+}
+
+_governor_ledger_poison() {
+	local session_id="${1:-}"
+	local ledger_path="${2:-}"
+	local unrecorded_tokens="${3:-0}"
+
+	touch "$(governor_ledger_poison_path "$ledger_path")" 2>/dev/null || true
+
+	local poison_payload
+	poison_payload=$(jq -n \
+		--arg sid "$session_id" \
+		--arg aid "${CLAUDE_SESSION_ID:-unknown}" \
+		--arg err "write failed after ${GOVERNOR_LEDGER_MAX_RETRIES} attempts" \
+		--argjson retries "$GOVERNOR_LEDGER_MAX_RETRIES" \
+		--argjson tok "$unrecorded_tokens" \
+		'{
+			session_id: $sid,
+			agent_id: $aid,
+			error: $err,
+			retry_count: $retries,
+			ledger_poisoned: true,
+			unrecorded_tokens: $tok
+		}' 2>/dev/null) || poison_payload="{}"
+
+	governor_emit_event "governor.ledger.write_failed" "$poison_payload" || true
+}
+
+# Running total of tokens for a session.
+#
+# Uses the two-phase model: each record contributes
+#   .estimated_tokens + (.actual_tokens // 0)
+#
+# In-flight reservations:  estimated_tokens > 0, no actual_tokens → counts N_est
+# Completed Task records:  estimated_tokens = -N_est, actual_tokens = N_act → counts N_act
+# Net: in-flight estimates + completed actuals.
+#
+# Usage: tokens=$(governor_ledger_total_tokens "$session_id")
+governor_ledger_total_tokens() {
+	local session_id="${1:-}"
+	local ledger_path
+	ledger_path=$(governor_ledger_path "$session_id")
+
+	[[ -f "$ledger_path" ]] || { printf '0'; return 0; }
+
+	jq -s '[.[] | ((.estimated_tokens // 0) + (.actual_tokens // 0))] | add // 0' \
+		"$ledger_path" 2>/dev/null || printf '0'
+}
+
+# Running total of cost for a session (same two-phase logic as tokens).
+# Usage: cost=$(governor_ledger_total_cost "$session_id")
+governor_ledger_total_cost() {
+	local session_id="${1:-}"
+	local ledger_path
+	ledger_path=$(governor_ledger_path "$session_id")
+
+	[[ -f "$ledger_path" ]] || { printf '0'; return 0; }
+
+	jq -s '[.[] | ((.cost_usd_estimated // 0) + (.cost_usd_actual // 0))] | add // 0' \
+		"$ledger_path" 2>/dev/null || printf '0'
+}
+
+# Count completed Task calls (excludes reservation records).
+# Usage: calls=$(governor_ledger_call_count "$session_id")
+governor_ledger_call_count() {
+	local session_id="${1:-}"
+	local ledger_path
+	ledger_path=$(governor_ledger_path "$session_id")
+
+	[[ -f "$ledger_path" ]] || { printf '0'; return 0; }
+
+	jq -s '[.[] | select(.agent_type == "Task" and .record_type != "reservation")] | length' \
+		"$ledger_path" 2>/dev/null || printf '0'
+}

package/plugins/scribe/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "scribe",
+  "version": "0.2.0",
+  "description": "Intent documentation from agent activity. Captures why changes were made — problem context, decisions, tradeoffs — and distills them into readable artifacts at session end.",
+  "author": {
+    "name": "Onlooker Community",
+    "email": "community@onlooker.dev"
+  },
+  "homepage": "https://onlooker.dev",
+  "license": "MIT",
+  "requires": ["ecosystem"]
+}

package/plugins/scribe/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.2.0](https://github.com/onlooker-community/ecosystem/compare/scribe-v0.1.0...scribe-v0.2.0) (2026-06-01)
+
+
+### Features
+
+* **scribe:** intent documentation from agent activity :pencil2: ([#50](https://github.com/onlooker-community/ecosystem/issues/50)) ([f0a95d1](https://github.com/onlooker-community/ecosystem/commit/f0a95d1058e36d1bb5f0f645964d9e88e8f98b66))

package/plugins/scribe/config.json

@@ -0,0 +1,20 @@
+{
+  "scribe": {
+    "enabled": true,
+    "evaluator": {
+      "model": "claude-haiku-4-5-20251001",
+      "timeout": 60,
+      "max_tokens": 2048,
+      "temperature": 0.3
+    },
+    "capture": {
+      "min_turns": 3,
+      "prompt_max_chars": 1000,
+      "transcript_chars_max": 40000
+    },
+    "output": {
+      "mirror_to_project": false,
+      "project_dir": "docs/decisions"
+    }
+  }
+}

package/plugins/scribe/hooks/hooks.json

@@ -0,0 +1,37 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/scribe-session-start.sh"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/scribe-capture.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/scribe-stop.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/scribe/scripts/hooks/scribe-capture.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# Scribe UserPromptSubmit hook — initial intent capture.
+#
+# Fires on every user prompt. On the FIRST turn of a session (captured_prompt
+# is null in state), extracts and stores the prompt text as the problem
+# statement seed for later distillation.
+#
+# Subsequent turns are ignored — the full transcript is available at Stop
+# time, so there is no need to accumulate per-turn captures.
+#
+# Hook contract:
+#   - Always exits 0. Never blocks a user prompt.
+#   - Errors are written to stderr only; stdout is kept clean.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+# shellcheck source=../lib/scribe-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/scribe-config.sh"
+
+INPUT=$(cat)
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+PROMPT=$(printf '%s' "$INPUT" | jq -r '.prompt // ""' 2>/dev/null) || PROMPT=""
+
+_done() { exit 0; }
+
+[[ -z "$SESSION_ID" || -z "$PROMPT" ]] && _done
+
+scribe_config_load "$CWD"
+
+if ! scribe_config_enabled; then
+	_done
+fi
+
+ONLOOKER_DIR="${ONLOOKER_DIR:-${HOME}/.onlooker}"
+STATE_FILE="${ONLOOKER_DIR}/scribe/sessions/${SESSION_ID}.json"
+
+# Only capture if no prompt has been stored yet for this session.
+if [[ -f "$STATE_FILE" ]]; then
+	existing=$(jq -r '.captured_prompt // "null"' "$STATE_FILE" 2>/dev/null) || existing="null"
+	[[ "$existing" != "null" && -n "$existing" ]] && _done
+fi
+
+# Truncate prompt to configured max chars.
+max_chars=$(scribe_config_get '.scribe.capture.prompt_max_chars')
+[[ -z "$max_chars" || "$max_chars" == "null" ]] && max_chars="1000"
+
+truncated="${PROMPT:0:$max_chars}"
+timestamp=$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) || timestamp=""
+
+# Upsert state — preserve existing keys, update captured_prompt + captured_at.
+if [[ -f "$STATE_FILE" ]]; then
+	updated=$(jq \
+		--arg p "$truncated" \
+		--arg ts "$timestamp" \
+		'.captured_prompt = $p | .captured_at = $ts' \
+		"$STATE_FILE" 2>/dev/null) || updated=""
+	if [[ -n "$updated" ]]; then
+		printf '%s\n' "$updated" > "$STATE_FILE" || true
+	fi
+else
+	mkdir -p "$(dirname "$STATE_FILE")" 2>/dev/null || true
+	jq -n \
+		--arg sid "$SESSION_ID" \
+		--arg p "$truncated" \
+		--arg ts "$timestamp" \
+		'{session_id: $sid, captured_prompt: $p, captured_at: $ts}' \
+		2>/dev/null > "$STATE_FILE" || true
+fi
+
+_done

package/plugins/scribe/scripts/hooks/scribe-session-start.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Scribe SessionStart hook.
+#
+# Fires at every session start. Responsibilities:
+#   1. Skip silently when scribe.enabled is false.
+#   2. Create storage directories.
+#   3. Initialize session state file:
+#      - captured_prompt: null (populated by scribe-capture.sh on first turn)
+#      - captured_at: null
+#
+# Hook contract:
+#   - Always exits 0. Never blocks SessionStart.
+#   - Errors are written to stderr only; stdout is kept clean.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+# shellcheck source=../lib/scribe-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/scribe-config.sh"
+
+INPUT=$(cat)
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+
+_done() { exit 0; }
+
+scribe_config_load "$CWD"
+
+if ! scribe_config_enabled; then
+	_done
+fi
+
+export _HOOK_SESSION_ID="$SESSION_ID"
+
+ONLOOKER_DIR="${ONLOOKER_DIR:-${HOME}/.onlooker}"
+SCRIBE_SESSION_DIR="${ONLOOKER_DIR}/scribe/sessions"
+mkdir -p "$SCRIBE_SESSION_DIR" 2>/dev/null || true
+
+[[ -z "$SESSION_ID" ]] && _done
+
+STATE_FILE="${SCRIBE_SESSION_DIR}/${SESSION_ID}.json"
+
+jq -n \
+	--arg sid "$SESSION_ID" \
+	'{
+		session_id: $sid,
+		captured_prompt: null,
+		captured_at: null
+	}' 2>/dev/null > "$STATE_FILE" || {
+	printf 'scribe-session-start: failed to write state file %s\n' "$STATE_FILE" >&2
+	_done
+}
+
+_done