@onlooker-community/ecosystem 0.15.2 → 0.17.0

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

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# Scribe Stop hook — intent distillation.
+#
+# Fires when the agent session ends. Reads the full session transcript,
+# runs a Haiku extraction pass to identify the problem context, decisions,
+# tradeoffs, and constraints, then writes a Markdown intent document to
+# ~/.onlooker/scribe/<project_key>/<date>-<session>.md.
+#
+# Skip conditions (all silent):
+#   - scribe.enabled is false
+#   - no transcript_path in hook input, or file is unreadable
+#   - session has fewer turns than scribe.capture.min_turns
+#
+# Hook contract:
+#   - Always exits 0. Never blocks Stop.
+#   - 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"
+# shellcheck source=../lib/scribe-events.sh
+source "${PLUGIN_ROOT}/scripts/lib/scribe-events.sh"
+# shellcheck source=../lib/scribe-project-key.sh
+source "${PLUGIN_ROOT}/scripts/lib/scribe-project-key.sh"
+# shellcheck source=../lib/scribe-extract.sh
+source "${PLUGIN_ROOT}/scripts/lib/scribe-extract.sh"
+# shellcheck source=../lib/scribe-distill.sh
+source "${PLUGIN_ROOT}/scripts/lib/scribe-distill.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=""
+TRANSCRIPT_PATH=$(printf '%s' "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null) || TRANSCRIPT_PATH=""
+
+export _HOOK_SESSION_ID="$SESSION_ID"
+
+_done() { exit 0; }
+
+[[ -z "$SESSION_ID" ]] && _done
+
+scribe_config_load "$CWD"
+
+if ! scribe_config_enabled; then
+	_done
+fi
+
+if [[ -z "$TRANSCRIPT_PATH" || ! -f "$TRANSCRIPT_PATH" ]]; then
+	_done
+fi
+
+_distill_rc=0
+output_path=$(scribe_distill "$SESSION_ID" "$CWD" "$TRANSCRIPT_PATH") || _distill_rc=$?
+if [[ $_distill_rc -ne 0 ]]; then
+	# rc=2 means below min_turns — silent skip, not an error.
+	[[ $_distill_rc -ne 2 ]] && printf 'scribe-stop: distillation failed for session %s\n' "$SESSION_ID" >&2
+	_done
+fi
+
+[[ -n "$output_path" ]] && printf 'scribe: intent document written → %s\n' "$output_path" >&2
+
+_done

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

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Config resolution for Scribe.
+#
+# Reads three layers, latest wins:
+#   1. plugins/scribe/config.json (defaults shipped with the plugin)
+#   2. ~/.claude/settings.json
+#   3. <repo>/.claude/settings.json
+#
+# Exposes:
+#   scribe_config_load <repo_root>     # populates _SCRIBE_CONFIG (JSON)
+#   scribe_config_get <jq-path>        # echoes string value (empty if unset)
+#   scribe_config_get_json <jq-path>   # echoes JSON value (null if unset)
+#   scribe_config_enabled              # 0 if scribe.enabled is true
+
+_SCRIBE_CONFIG="{}"
+
+scribe_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 '{ scribe: (.scribe // {}) }' "$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
+
+	_SCRIBE_CONFIG="$merged"
+}
+
+scribe_config_get() {
+	local path="$1"
+	printf '%s' "$_SCRIBE_CONFIG" | jq -r "${path} // empty" 2>/dev/null
+}
+
+scribe_config_get_json() {
+	local path="$1"
+	printf '%s' "$_SCRIBE_CONFIG" | jq -c "${path}" 2>/dev/null
+}
+
+scribe_config_enabled() {
+	local v
+	v=$(scribe_config_get '.scribe.enabled')
+	[[ "$v" == "true" ]]
+}

package/plugins/scribe/scripts/lib/scribe-distill.sh

@@ -0,0 +1,239 @@
+#!/usr/bin/env bash
+# Distillation pipeline for Scribe.
+#
+# Orchestrates the full Stop-time flow:
+#   1. Load session state (captured initial prompt)
+#   2. Count transcript turns — skip if below min_turns
+#   3. Call scribe_extract_intent (Haiku pass)
+#   4. Format output as a readable Markdown document
+#   5. Write to ~/.onlooker/scribe/<project_key>/
+#   6. Optionally mirror to <repo_root>/<project_dir>/
+#   7. Emit scribe.distill.complete
+#
+# Exposes:
+#   scribe_distill <session_id> <cwd> <transcript_path>
+
+# shellcheck source=./scribe-extract.sh
+# (caller must source scribe-extract.sh before scribe-distill.sh)
+
+_scribe_format_document() {
+	local intent_json="${1:-}"
+	local session_id="${2:-unknown}"
+	local project_root="${3:-}"
+	local captured_prompt="${4:-}"
+	local date_str
+	date_str=$(date '+%Y-%m-%d' 2>/dev/null) || date_str="unknown"
+	local timestamp
+	timestamp=$(date '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) || timestamp="unknown"
+
+	local summary problem decisions_json tradeoffs_json constraints_json out_of_scope_json
+	summary=$(printf '%s' "$intent_json" | jq -r '.summary // ""' 2>/dev/null) || summary=""
+	problem=$(printf '%s' "$intent_json" | jq -r '.problem // ""' 2>/dev/null) || problem=""
+	decisions_json=$(printf '%s' "$intent_json" | jq -c '.decisions // []' 2>/dev/null) || decisions_json="[]"
+	tradeoffs_json=$(printf '%s' "$intent_json" | jq -c '.tradeoffs // []' 2>/dev/null) || tradeoffs_json="[]"
+	constraints_json=$(printf '%s' "$intent_json" | jq -c '.constraints // []' 2>/dev/null) || constraints_json="[]"
+	out_of_scope_json=$(printf '%s' "$intent_json" | jq -c '.out_of_scope // []' 2>/dev/null) || out_of_scope_json="[]"
+
+	local session_short="${session_id:0:8}"
+
+	{
+		printf '# Session Intent: %s\n\n' "$date_str"
+		[[ -n "$summary" ]] && printf '> %s\n\n' "$summary"
+
+		printf '## Problem\n\n'
+		if [[ -n "$problem" ]]; then
+			printf '%s\n\n' "$problem"
+		else
+			printf '*No problem statement extracted.*\n\n'
+		fi
+
+		printf '## Decisions\n\n'
+		local decision_count
+		decision_count=$(printf '%s' "$decisions_json" | jq 'length' 2>/dev/null) || decision_count=0
+		if [[ "$decision_count" -gt 0 ]]; then
+			local i
+			for ((i = 0; i < decision_count; i++)); do
+				local d r alts
+				d=$(printf '%s' "$decisions_json" | jq -r ".[$i].decision // \"\"" 2>/dev/null) || d=""
+				r=$(printf '%s' "$decisions_json" | jq -r ".[$i].reason // \"\"" 2>/dev/null) || r=""
+				alts=$(printf '%s' "$decisions_json" | jq -r ".[$i].alternatives // [] | .[]" 2>/dev/null) || alts=""
+				[[ -z "$d" ]] && continue
+				printf '- **%s** — %s\n' "$d" "$r"
+				if [[ -n "$alts" ]]; then
+					printf '  - *Considered:* '
+					local first=1
+					while IFS= read -r alt; do
+						[[ -z "$alt" ]] && continue
+						[[ "$first" -eq 0 ]] && printf ', '
+						printf '%s' "$alt"
+						first=0
+					done <<< "$alts"
+					printf '\n'
+				fi
+			done
+			printf '\n'
+		else
+			printf '*None noted.*\n\n'
+		fi
+
+		printf '## Tradeoffs\n\n'
+		local tradeoff_count
+		tradeoff_count=$(printf '%s' "$tradeoffs_json" | jq 'length' 2>/dev/null) || tradeoff_count=0
+		if [[ "$tradeoff_count" -gt 0 ]]; then
+			printf '%s' "$tradeoffs_json" | jq -r '.[]' 2>/dev/null | while IFS= read -r item; do
+				[[ -n "$item" ]] && printf '- %s\n' "$item"
+			done
+			printf '\n'
+		else
+			printf '*None noted.*\n\n'
+		fi
+
+		printf '## Constraints\n\n'
+		local constraint_count
+		constraint_count=$(printf '%s' "$constraints_json" | jq 'length' 2>/dev/null) || constraint_count=0
+		if [[ "$constraint_count" -gt 0 ]]; then
+			printf '%s' "$constraints_json" | jq -r '.[]' 2>/dev/null | while IFS= read -r item; do
+				[[ -n "$item" ]] && printf '- %s\n' "$item"
+			done
+			printf '\n'
+		else
+			printf '*None noted.*\n\n'
+		fi
+
+		printf '## Out of Scope\n\n'
+		local oos_count
+		oos_count=$(printf '%s' "$out_of_scope_json" | jq 'length' 2>/dev/null) || oos_count=0
+		if [[ "$oos_count" -gt 0 ]]; then
+			printf '%s' "$out_of_scope_json" | jq -r '.[]' 2>/dev/null | while IFS= read -r item; do
+				[[ -n "$item" ]] && printf '- %s\n' "$item"
+			done
+			printf '\n'
+		else
+			printf '*None noted.*\n\n'
+		fi
+
+		if [[ -n "$captured_prompt" ]]; then
+			printf '## Initial Prompt\n\n'
+			printf '```\n%s\n```\n\n' "$captured_prompt"
+		fi
+
+		printf '---\n'
+		printf '*Generated by scribe · session `%s` · %s*\n' "$session_short" "$timestamp"
+		[[ -n "$project_root" ]] && printf '*Project: `%s`*\n' "$project_root"
+	}
+}
+
+scribe_distill() {
+	local session_id="${1:-}"
+	local cwd="${2:-}"
+	local transcript_path="${3:-}"
+
+	[[ -z "$session_id" ]] && return 1
+
+	local onlooker_dir="${ONLOOKER_DIR:-${HOME}/.onlooker}"
+	local state_file="${onlooker_dir}/scribe/sessions/${session_id}.json"
+
+	# Load captured prompt from session state (best-effort).
+	local captured_prompt=""
+	if [[ -f "$state_file" ]]; then
+		captured_prompt=$(jq -r '.captured_prompt // ""' "$state_file" 2>/dev/null) || captured_prompt=""
+	fi
+
+	# Transcript is required for extraction.
+	if [[ -z "$transcript_path" || ! -f "$transcript_path" ]]; then
+		printf 'scribe_distill: no transcript available for session %s\n' "$session_id" >&2
+		return 1
+	fi
+
+	# Count turns; skip trivial sessions.
+	local min_turns
+	min_turns=$(scribe_config_get '.scribe.capture.min_turns') || min_turns="3"
+	[[ -z "$min_turns" || "$min_turns" == "null" ]] && min_turns="3"
+
+	local turn_count
+	turn_count=$(scribe_count_turns "$transcript_path")
+
+	if [[ "$turn_count" -lt "$min_turns" ]]; then
+		return 2
+	fi
+
+	# Resolve config.
+	local model timeout_s max_tokens temperature transcript_chars_max
+	model=$(scribe_config_get '.scribe.evaluator.model')
+	[[ -z "$model" || "$model" == "null" ]] && model="claude-haiku-4-5-20251001"
+	timeout_s=$(scribe_config_get '.scribe.evaluator.timeout')
+	[[ -z "$timeout_s" || "$timeout_s" == "null" ]] && timeout_s="60"
+	max_tokens=$(scribe_config_get '.scribe.evaluator.max_tokens')
+	[[ -z "$max_tokens" || "$max_tokens" == "null" ]] && max_tokens="2048"
+	temperature=$(scribe_config_get '.scribe.evaluator.temperature')
+	[[ -z "$temperature" || "$temperature" == "null" ]] && temperature="0.3"
+	transcript_chars_max=$(scribe_config_get '.scribe.capture.transcript_chars_max')
+	[[ -z "$transcript_chars_max" || "$transcript_chars_max" == "null" ]] && transcript_chars_max="40000"
+
+	# Run extraction.
+	local intent_json
+	intent_json=$(scribe_extract_intent \
+		"$transcript_path" "$model" "$timeout_s" "$max_tokens" "$temperature" "$transcript_chars_max") || {
+		printf 'scribe_distill: extraction failed for session %s\n' "$session_id" >&2
+		return 1
+	}
+
+	# Resolve project key and output paths.
+	local project_key project_root output_dir
+	project_key=$(scribe_project_key "$cwd")
+	project_root=$(scribe_project_repo_root "$cwd")
+
+	if [[ -n "$project_key" ]]; then
+		output_dir=$(scribe_project_dir "$project_key")
+	else
+		output_dir="${onlooker_dir}/scribe/unknown"
+	fi
+
+	mkdir -p "$output_dir" 2>/dev/null || {
+		printf 'scribe_distill: cannot create output dir %s\n' "$output_dir" >&2
+		return 1
+	}
+
+	local date_str
+	date_str=$(date '+%Y-%m-%d' 2>/dev/null) || date_str="unknown"
+	local session_short="${session_id:0:8}"
+	local filename="${date_str}-${session_short}.md"
+	local output_path="${output_dir}/${filename}"
+
+	# Format and write the document.
+	local doc
+	doc=$(_scribe_format_document \
+		"$intent_json" "$session_id" "$project_root" "$captured_prompt")
+
+	printf '%s\n' "$doc" > "$output_path" 2>/dev/null || {
+		printf 'scribe_distill: failed to write %s\n' "$output_path" >&2
+		return 1
+	}
+
+	# Mirror to project tree if configured.
+	local mirror artifacts=1
+	mirror=$(scribe_config_get '.scribe.output.mirror_to_project')
+	if [[ "$mirror" == "true" && -n "$project_root" ]]; then
+		local project_dir
+		project_dir=$(scribe_config_get '.scribe.output.project_dir')
+		[[ -z "$project_dir" || "$project_dir" == "null" ]] && project_dir="docs/decisions"
+		local mirror_dir="${project_root}/${project_dir}"
+		if mkdir -p "$mirror_dir" 2>/dev/null; then
+			if cp "$output_path" "${mirror_dir}/${filename}" 2>/dev/null; then
+				artifacts=2
+			fi
+		fi
+	fi
+
+	# Emit scribe.distill.complete.
+	local payload
+	payload=$(jq -n \
+		--arg sid "$session_id" \
+		--argjson cap 1 \
+		--argjson art "$artifacts" \
+		'{session_id: $sid, captures_processed: $cap, artifacts_produced: $art}') || payload=""
+
+	[[ -n "$payload" ]] && scribe_emit_event "scribe.distill.complete" "$payload" || true
+
+	printf '%s' "$output_path"
+}

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

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Canonical scribe.* event emission.
+#
+# Thin wrapper around the ecosystem plugin's onlooker-event.mjs `emit` mode.
+# Every emission is validated against @onlooker-community/schema before being
+# appended to $ONLOOKER_EVENTS_LOG (defaults to $ONLOOKER_DIR/logs/onlooker-events.jsonl).
+#
+# Usage:
+#   scribe_emit_event "scribe.distill.complete" '{"session_id":"...","captures_processed":1,...}'
+
+_SCRIBE_PLUGIN_NAME="scribe"
+
+_scribe_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
+}
+
+_scribe_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'
+}
+
+scribe_emit_event() {
+	local event_type="${1:-}"
+	local payload="${2:-}"
+
+	[[ -z "$event_type" || -z "$payload" ]] && return 1
+
+	local event_js
+	event_js=$(_scribe_event_js_path) || return 1
+
+	local session_id
+	session_id=$(_scribe_session_id)
+
+	local params
+	params=$(jq -n \
+		--arg plugin "$_SCRIBE_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 scribe-event-err.XXXXXX 2>/dev/null) || stderr_file="/tmp/scribe-event-err.$$"
+	event=$(printf '%s' "$params" \
+		| ONLOOKER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}" \
+		  ONLOOKER_PLUGIN_NAME="$_SCRIBE_PLUGIN_NAME" \
+		  node "$event_js" emit 2>"$stderr_file") || {
+		printf 'scribe_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/scribe/scripts/lib/scribe-extract.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# Intent extraction for Scribe.
+#
+# Reads a session transcript and runs a Haiku pass to extract structured
+# intent documentation: the problem being solved, decisions made and why,
+# tradeoffs, constraints, and what was explicitly left out.
+#
+# This is documentation from intent, not from code. The output answers
+# WHY, not WHAT — git logs and code comments cover what.
+#
+# Exposes:
+#   scribe_count_turns <transcript_path>
+#     Echoes the number of user turns found in the transcript (integer).
+#
+#   scribe_extract_intent <transcript_path> <model> <timeout> <max_tokens> <temperature>
+#     Echoes a JSON object on success, empty string on failure.
+#     JSON shape:
+#       {
+#         "problem":      string,
+#         "decisions":    [{decision, reason, alternatives:[]}],
+#         "tradeoffs":    [string],
+#         "constraints":  [string],
+#         "out_of_scope": [string],
+#         "summary":      string
+#       }
+
+_SCRIBE_EXTRACT_PROMPT='You are an intent documentation assistant. Analyze this agent session transcript and extract structured documentation about WHY changes were made — the problem context, decisions, tradeoffs, and constraints that shaped the work. This is documentation from intent, not from code.
+
+Do NOT describe what was done. Focus exclusively on why decisions were made.
+
+Return a JSON object with exactly these keys:
+{
+  "problem": "1-3 sentences: what problem or goal initiated this session",
+  "decisions": [
+    {
+      "decision": "what was decided",
+      "reason": "why this approach was chosen",
+      "alternatives": ["alternative that was considered but rejected"]
+    }
+  ],
+  "tradeoffs": ["tradeoff description — what was gained vs. given up"],
+  "constraints": ["constraint that shaped decisions"],
+  "out_of_scope": ["what was explicitly not done, and why"],
+  "summary": "2-3 sentences: executive summary of the session intent and key decisions"
+}
+
+Rules:
+- All fields are required; use empty arrays [] if no items found
+- Keep each item to 1-2 sentences
+- Return ONLY the JSON object — no prose, no markdown fences, no explanation
+
+'
+
+scribe_count_turns() {
+	local transcript_path="${1:-}"
+	[[ -f "$transcript_path" ]] || { printf '0'; return 0; }
+
+	local count=0
+	local line
+	while IFS= read -r line; do
+		[[ -z "$line" ]] && continue
+		local role
+		role=$(printf '%s' "$line" | jq -r '.role // empty' 2>/dev/null) || continue
+		[[ "$role" == "user" ]] && count=$((count + 1))
+	done < "$transcript_path"
+
+	printf '%s' "$count"
+}
+
+scribe_extract_intent() {
+	local transcript_path="${1:-}"
+	local model="${2:-claude-haiku-4-5-20251001}"
+	local timeout_s="${3:-60}"
+	local max_tokens="${4:-2048}"
+	local temperature="${5:-0.3}"
+	local transcript_chars_max="${6:-40000}"
+
+	[[ -f "$transcript_path" ]] || return 1
+
+	local transcript_content
+	transcript_content=$(jq -r '
+		select(.role != null) |
+		if .role == "user" then
+			"[User]\n" + (
+				if (.content | type) == "array" then
+					[.content[] | select(.type == "text") | .text] | join("\n")
+				else
+					(.content // "")
+				end
+			)
+		elif .role == "assistant" then
+			"[Assistant]\n" + (
+				if (.content | type) == "array" then
+					[.content[] | select(.type == "text") | .text] | join("\n")
+				else
+					(.content // "")
+				end
+			)
+		else empty end
+	' "$transcript_path" 2>/dev/null | head -c "$transcript_chars_max") || transcript_content=""
+
+	[[ -z "$transcript_content" ]] && return 1
+
+	local prompt_file
+	prompt_file=$(mktemp -t scribe-extract.XXXXXX 2>/dev/null) || prompt_file="/tmp/scribe-extract.$$"
+	trap 'rm -f "$prompt_file"' RETURN
+
+	{
+		printf '%s' "$_SCRIBE_EXTRACT_PROMPT"
+		printf '<session_transcript>\n'
+		printf '%s\n' "$transcript_content"
+		printf '</session_transcript>\n'
+	} > "$prompt_file"
+
+	if ! command -v claude >/dev/null 2>&1; then
+		printf 'scribe_extract_intent: claude CLI not found\n' >&2
+		return 1
+	fi
+
+	local claude_args=(-p --max-turns 1 --model "$model" --max-tokens "$max_tokens")
+
+	local response=""
+	if command -v timeout >/dev/null 2>&1; then
+		response=$(timeout "$timeout_s" claude "${claude_args[@]}" < "$prompt_file" 2>/dev/null) || response=""
+	elif command -v gtimeout >/dev/null 2>&1; then
+		response=$(gtimeout "$timeout_s" claude "${claude_args[@]}" < "$prompt_file" 2>/dev/null) || response=""
+	else
+		response=$(claude "${claude_args[@]}" < "$prompt_file" 2>/dev/null) || response=""
+	fi
+
+	[[ -z "$response" ]] && return 1
+
+	# Strip markdown fences if present.
+	local clean
+	clean=$(printf '%s' "$response" \
+		| sed -e 's/^```json[[:space:]]*//' -e 's/^```[[:space:]]*//' -e 's/[[:space:]]*```$//')
+
+	# Validate all required keys from the extraction prompt.
+	if ! printf '%s' "$clean" | jq -e \
+		'.problem and (.decisions | type == "array") and (.tradeoffs | type == "array") and (.constraints | type == "array") and (.out_of_scope | type == "array") and .summary' \
+		>/dev/null 2>&1; then
+		printf 'scribe_extract_intent: response missing required keys\n' >&2
+		return 1
+	fi
+
+	printf '%s' "$clean"
+}