create-merlin-brain 3.11.0 → 3.13.0

package/files/hooks/security-scanner.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+#
+# Merlin Hook: security-scanner.sh
+# Event: PreToolUse (Write, Edit, Bash, NotebookEdit)
+#
+# Scans content being written/executed for:
+#   A) Prompt injection patterns
+#   B) Secret/credential leaks
+#   C) Data exfiltration patterns
+#
+# Exit 2 + JSON {"decision":"block","reason":"..."} to block.
+# Exit 0 to allow.
+#
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LOG_DIR="${HOME}/.claude/merlin"
+LOG_FILE="${LOG_DIR}/security.log"
+
+# Source shared analytics if available
+[ -f "${HOOKS_DIR}/lib/analytics.sh" ] && . "${HOOKS_DIR}/lib/analytics.sh"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Read input from stdin
+# ─────────────────────────────────────────────────────────────────────────────
+input=""
+if [ ! -t 0 ]; then
+  input=$(cat 2>/dev/null || true)
+fi
+
+[ -z "$input" ] && { echo '{}'; exit 0; }
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Extract content to scan
+# ─────────────────────────────────────────────────────────────────────────────
+tool_name=""
+content=""
+file_path=""
+
+if command -v jq >/dev/null 2>&1; then
+  tool_name=$(echo "$input" | jq -r '.tool_name // empty' 2>/dev/null || true)
+  file_path=$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null || true)
+  # Write/NotebookEdit → content; Edit → new_string; Bash → command
+  content=$(echo "$input" | jq -r '
+    .tool_input.content //
+    .tool_input.new_string //
+    .tool_input.command //
+    empty' 2>/dev/null || true)
+else
+  # Fallback: crude extraction without jq
+  tool_name=$(echo "$input" | grep -o '"tool_name":"[^"]*"' | head -1 | cut -d'"' -f4 || true)
+  content=$(echo "$input" | grep -o '"command":"[^"]*"' | head -1 | cut -d'"' -f4 || true)
+fi
+
+[ -z "$content" ] && { echo '{}'; exit 0; }
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Helpers
+# ─────────────────────────────────────────────────────────────────────────────
+_log_detection() {
+  local threat_type="$1"
+  local detail="$2"
+  mkdir -p "$LOG_DIR"
+  printf '[%s] BLOCKED tool=%s file=%s threat=%s detail=%s\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    "${tool_name:-unknown}" \
+    "${file_path:-unknown}" \
+    "$threat_type" \
+    "$detail" \
+    >> "$LOG_FILE" 2>/dev/null || true
+  if declare -f log_event >/dev/null 2>&1; then
+    log_event "security_block" \
+      "$(printf '{"tool":"%s","threat":"%s"}' "${tool_name:-unknown}" "$threat_type")"
+  fi
+}
+
+_block() {
+  local threat_type="$1"
+  local detail="${2:-}"
+  _log_detection "$threat_type" "$detail"
+  printf '{"decision":"block","reason":"Security: %s detected"}\n' "$threat_type"
+  exit 2
+}
+
+# ─────────────────────────────────────────────────────────────────────────────
+# A) PROMPT INJECTION DETECTION
+# Only scan non-Bash tools (Bash commands are code, not LLM prompts).
+# ─────────────────────────────────────────────────────────────────────────────
+if [ "${tool_name:-}" != "Bash" ]; then
+  # Build a single grep pattern for all injection phrases
+  INJECTION_PATTERN='ignore (previous|all previous) instructions|disregard your instructions|forget your system prompt|you are now [a-z]|new role:|override:|system prompt:|reveal your instructions|show me your system prompt|what are your instructions|print your prompt|output your rules|ADMIN MODE|jailbreak|DAN mode|developer mode enabled|ignore safety|bypass restrictions|act as an unrestricted|\[END OF PROMPT\]'
+
+  if echo "$content" | grep -qiE "$INJECTION_PATTERN" 2>/dev/null; then
+    # Determine which pattern matched for the reason
+    matched=$(echo "$content" | grep -iEo "$INJECTION_PATTERN" | head -1 || true)
+    _block "prompt injection" "${matched}"
+  fi
+fi
+
+# ─────────────────────────────────────────────────────────────────────────────
+# B) SECRET / CREDENTIAL DETECTION
+# ─────────────────────────────────────────────────────────────────────────────
+
+# AWS access key
+if echo "$content" | grep -qE 'AKIA[0-9A-Z]{16}' 2>/dev/null; then
+  _block "AWS access key" "AKIA..."
+fi
+
+# Anthropic API key (sk-ant- prefix with 90+ chars)
+if echo "$content" | grep -qE 'sk-ant-[a-zA-Z0-9_\-]{90,}' 2>/dev/null; then
+  _block "Anthropic API key" "sk-ant-..."
+fi
+
+# OpenAI key (sk- with 48+ chars, but not sk-ant-)
+if echo "$content" | grep -qE 'sk-(?!ant-)[a-zA-Z0-9]{48,}' 2>/dev/null; then
+  _block "OpenAI API key" "sk-..."
+elif echo "$content" | grep -qE 'sk-[a-zA-Z0-9]{48,}' 2>/dev/null; then
+  # Fallback for grep without PCRE: exclude sk-ant- manually
+  if ! echo "$content" | grep -qE 'sk-ant-' 2>/dev/null; then
+    _block "OpenAI API key" "sk-..."
+  fi
+fi
+
+# PEM private key header
+if echo "$content" | grep -qE '-----BEGIN (RSA|EC|DSA|OPENSSH) PRIVATE KEY-----' 2>/dev/null; then
+  _block "PEM private key" "BEGIN PRIVATE KEY"
+fi
+
+# Generic credential assignment — exclude common placeholders
+if echo "$content" | grep -qiE '(password|secret|api_key|apikey|token|auth)\s*[:=]\s*["\x27][^"'\'']{8,}["\x27]' 2>/dev/null; then
+  # Allow placeholder values
+  if ! echo "$content" | grep -qiE '(password|secret|api_key|apikey|token|auth)\s*[:=]\s*["\x27][^"'\'']*?(YOUR_|REPLACE_ME|TODO|CHANGEME|example|placeholder|xxx+|<[^>]+>|\$\{[^}]+\}|%\([^)]+\))' 2>/dev/null; then
+    _block "credential assignment" "password/secret/api_key/token"
+  fi
+fi
+
+# ─────────────────────────────────────────────────────────────────────────────
+# C) DATA EXFILTRATION PATTERNS
+# Targets Bash commands specifically; also catches these in scripts being written.
+# ─────────────────────────────────────────────────────────────────────────────
+EXFIL_PATTERN='curl[^|]*POST[^|]*\$\(cat|wget[^|]*-O-[^|]*\|[^|]*curl|\$\(cat [^)]*\)\s*\|\s*(curl|wget|nc |netcat)|env\s*\|\s*(curl|wget)|printenv[^|]*\|\s*(curl|wget)'
+
+if echo "$content" | grep -qE "$EXFIL_PATTERN" 2>/dev/null; then
+  matched=$(echo "$content" | grep -Eo "$EXFIL_PATTERN" | head -1 || true)
+  _block "data exfiltration" "${matched}"
+fi
+
+# ─────────────────────────────────────────────────────────────────────────────
+# All checks passed — allow
+# ─────────────────────────────────────────────────────────────────────────────
+echo '{}'
+exit 0

package/files/hooks/session-end-memory-sync.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+#
+# Merlin Hook: Stop — Auto-Memory Sync
+# Extracts session decisions (recent commits, CLAUDE.md changes) and
+# persists them to Sights cloud via merlin_write_state.
+# Always exits 0 — never blocks Claude Code shutdown.
+# Runs asynchronously so session close is instant.
+#
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source shared libraries defensively
+[ -f "${HOOKS_DIR}/lib/analytics.sh" ] && . "${HOOKS_DIR}/lib/analytics.sh"
+
+# ── Main sync logic (runs in background) ────────────────────────
+_merlin_memory_sync() {
+  local merlin_dir="${HOME}/.claude/merlin"
+  local api_url="${MERLIN_API_URL:-https://api.merlin.build}"
+  local api_key="${MERLIN_API_KEY:-}"
+  local state_file="${merlin_dir}/session-memory.json"
+  local cwd="${PWD:-$(pwd)}"
+
+  # Need API key to write to cloud
+  [ -z "${api_key}" ] && return 0
+
+  # Must be in a git repo to extract decisions
+  git -C "${cwd}" rev-parse --git-dir >/dev/null 2>&1 || return 0
+
+  # ── Collect recent commits (last 10 from this session, up to 2h old) ──
+  local commit_log=""
+  commit_log=$(git -C "${cwd}" log \
+    --oneline \
+    --since="2 hours ago" \
+    --max-count=10 \
+    --no-merges \
+    2>/dev/null) || true
+
+  # ── Detect CLAUDE.md changes this session ──────────────────────
+  local claude_md_changed="false"
+  local claude_md_diff=""
+  if git -C "${cwd}" diff --name-only HEAD~1 HEAD 2>/dev/null | grep -q "CLAUDE.md"; then
+    claude_md_changed="true"
+    claude_md_diff=$(git -C "${cwd}" diff HEAD~1 HEAD -- CLAUDE.md 2>/dev/null | head -40) || true
+  fi
+
+  # Nothing interesting to sync — skip API call
+  if [ -z "${commit_log}" ] && [ "${claude_md_changed}" = "false" ]; then
+    return 0
+  fi
+
+  # ── Build state payload ─────────────────────────────────────────
+  local repo_name
+  repo_name=$(basename "${cwd}")
+  local timestamp
+  timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  # Escape values for JSON (basic — avoids jq dependency)
+  local safe_commits
+  safe_commits=$(echo "${commit_log}" | tr '"' "'" | tr '\n' '|')
+  local safe_diff
+  safe_diff=$(echo "${claude_md_diff}" | tr '"' "'" | tr '\n' '|' | head -c 500)
+
+  local payload
+  payload=$(printf '{"repo":"%s","timestamp":"%s","commits":"%s","claude_md_changed":%s,"claude_md_diff":"%s"}' \
+    "${repo_name}" "${timestamp}" "${safe_commits}" "${claude_md_changed}" "${safe_diff}")
+
+  # Write to local state file as fallback
+  mkdir -p "${merlin_dir}" 2>/dev/null || true
+  echo "${payload}" > "${state_file}" 2>/dev/null || true
+
+  # ── Push to Sights API if available ────────────────────────────
+  curl -s \
+    --max-time 8 \
+    --request POST \
+    --header "Content-Type: application/json" \
+    --header "x-api-key: ${api_key}" \
+    --data "${payload}" \
+    "${api_url}/api/memory/session-end" \
+    >/dev/null 2>&1 || true
+
+  # Log the sync event
+  if type log_event >/dev/null 2>&1; then
+    log_event "memory_sync" "$(printf '{"repo":"%s","commits_synced":%d,"claude_md_changed":%s}' \
+      "${repo_name}" \
+      "$(echo "${commit_log}" | grep -c . || echo 0)" \
+      "${claude_md_changed}")"
+  fi
+}
+
+# Fire and forget — never delay session shutdown
+_merlin_memory_sync &
+
+# Claude Code command hooks must output valid JSON to stdout
+echo '{}'
+exit 0

package/files/hooks/session-end.sh

@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 #
 # Merlin Hook: SessionEnd / Stop
-# Saves checkpoint and finalizes session analytics.
+# Saves checkpoint, finalizes session analytics, and writes a structured
+# session summary to ~/.claude/merlin/sessions/ for future restore/search.
 # Always exits 0 — never blocks Claude Code shutdown.
 #
 set -euo pipefail
@@ -19,11 +20,283 @@ log_event "session_end" '{}'
 # Finalize session analytics (adds endTime, duration, summary)
 finalize_session
 
+# ── Session Summary ──────────────────────────────────────────────────────────
+# Write a structured session summary to ~/.claude/merlin/sessions/ so that
+# merlin_session_restore and merlin_session_search can provide continuity.
+
+SESSIONS_DIR="${HOME}/.claude/merlin/sessions"
+mkdir -p "${SESSIONS_DIR}" 2>/dev/null || true
+
+# Only generate summary when jq is available — keeps the fallback path clean
+if command -v jq >/dev/null 2>&1; then
+
+  TIMESTAMP="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  EPOCH_NOW="$(date +%s)"
+
+  # ── Duration ────────────────────────────────────────────────────────────────
+  SESSION_DURATION=0
+  if [ -f "${MERLIN_SESSION_FILE}" ]; then
+    dur="$(jq -r '.durationSeconds // 0' "${MERLIN_SESSION_FILE}" 2>/dev/null || echo 0)"
+    SESSION_DURATION="${dur}"
+  fi
+
+  # ── Files modified via git diff --stat ──────────────────────────────────────
+  FILES_MODIFIED_JSON="[]"
+  if command -v git >/dev/null 2>&1 && git rev-parse --git-dir >/dev/null 2>&1; then
+    # Uncommitted changes (staged + unstaged) compared to HEAD
+    raw_files="$(git diff --stat HEAD 2>/dev/null | awk 'NR>1 || /\|/' | grep '|' | awk '{print $1}' | head -20 || true)"
+    # Also catch files changed in the last session via log since session start
+    sid="$(jq -r '.id // ""' "${MERLIN_SESSION_FILE}" 2>/dev/null || echo "")"
+    start_epoch="$(echo "${sid}" | cut -d'-' -f1 2>/dev/null || echo "${EPOCH_NOW}")"
+    if [ -n "${start_epoch}" ] && [ "${start_epoch}" -gt 0 ] 2>/dev/null; then
+      recent_files="$(git log --since="@${start_epoch}" --name-only --pretty=format: 2>/dev/null | sort -u | head -20 || true)"
+      all_files="$(printf '%s\n%s' "${raw_files}" "${recent_files}" | sort -u | grep -v '^$' || true)"
+    else
+      all_files="${raw_files}"
+    fi
+    if [ -n "${all_files}" ]; then
+      FILES_MODIFIED_JSON="$(echo "${all_files}" | jq -R . | jq -sc . 2>/dev/null || echo "[]")"
+    fi
+  fi
+
+  # ── Recent commits ──────────────────────────────────────────────────────────
+  COMMITS_JSON="[]"
+  if command -v git >/dev/null 2>&1 && git rev-parse --git-dir >/dev/null 2>&1; then
+    sid="$(jq -r '.id // ""' "${MERLIN_SESSION_FILE}" 2>/dev/null || echo "")"
+    start_epoch="$(echo "${sid}" | cut -d'-' -f1 2>/dev/null || echo "")"
+    if [ -n "${start_epoch}" ] && [ "${start_epoch}" -gt 0 ] 2>/dev/null; then
+      commits="$(git log --since="@${start_epoch}" --pretty=format:"%s" 2>/dev/null | head -10 || true)"
+    else
+      commits="$(git log -5 --pretty=format:"%s" 2>/dev/null || true)"
+    fi
+    if [ -n "${commits}" ]; then
+      COMMITS_JSON="$(echo "${commits}" | jq -R . | jq -sc . 2>/dev/null || echo "[]")"
+    fi
+  fi
+
+  # ── Agents used (from analytics events) ─────────────────────────────────────
+  AGENTS_JSON="[]"
+  if [ -f "${MERLIN_SESSION_FILE}" ]; then
+    AGENTS_JSON="$(jq '[.events[] | select(.type == "agent_route") | .data.agent] | unique | map(select(. != null and . != ""))' \
+      "${MERLIN_SESSION_FILE}" 2>/dev/null || echo "[]")"
+  fi
+
+  # ── Text summary (built from commit messages + modified file count) ──────────
+  commit_count="$(echo "${COMMITS_JSON}" | jq 'length' 2>/dev/null || echo 0)"
+  file_count="$(echo "${FILES_MODIFIED_JSON}" | jq 'length' 2>/dev/null || echo 0)"
+
+  if [ "${commit_count}" -gt 0 ] 2>/dev/null; then
+    first_commit="$(echo "${COMMITS_JSON}" | jq -r '.[0] // ""' 2>/dev/null || echo "")"
+    SUMMARY_TEXT="Session with ${commit_count} commit(s) and ${file_count} file(s) modified. Latest: ${first_commit}"
+  elif [ "${file_count}" -gt 0 ] 2>/dev/null; then
+    SUMMARY_TEXT="Session with ${file_count} file(s) modified, no commits recorded."
+  else
+    SUMMARY_TEXT="Session completed. No file changes detected."
+  fi
+
+  # Truncate to keep summaries small
+  SUMMARY_TEXT="$(echo "${SUMMARY_TEXT}" | cut -c1-200)"
+
+  # ── Working directory ────────────────────────────────────────────────────────
+  WORK_DIR="${CLAUDE_WORKTREE_PATH:-$(pwd 2>/dev/null || echo "")}"
+
+  # ── Write session summary ────────────────────────────────────────────────────
+  SUMMARY_FILE="${SESSIONS_DIR}/session-${EPOCH_NOW}.json"
+  jq -n \
+    --arg ts "${TIMESTAMP}" \
+    --argjson dur "${SESSION_DURATION}" \
+    --argjson files "${FILES_MODIFIED_JSON}" \
+    --argjson commits "${COMMITS_JSON}" \
+    --argjson agents "${AGENTS_JSON}" \
+    --arg summary "${SUMMARY_TEXT}" \
+    --arg workdir "${WORK_DIR}" \
+    '{
+      timestamp: $ts,
+      duration_seconds: $dur,
+      files_modified: $files,
+      commits: $commits,
+      agents_used: $agents,
+      summary: $summary,
+      working_directory: $workdir
+    }' > "${SUMMARY_FILE}" 2>/dev/null || true
+
+  # Keep only the last 100 session summaries to cap disk usage
+  summary_count="$(ls -1 "${SESSIONS_DIR}"/session-*.json 2>/dev/null | wc -l | tr -d ' ' || echo 0)"
+  if [ "${summary_count}" -gt 100 ] 2>/dev/null; then
+    ls -1t "${SESSIONS_DIR}"/session-*.json 2>/dev/null | tail -n +"$((100 + 1))" | xargs rm -f 2>/dev/null || true
+  fi
+
+fi
+
 # If merlin CLI is available, save checkpoint in background
 if command -v merlin >/dev/null 2>&1; then
   merlin save-checkpoint "Session ended" >/dev/null 2>&1 &
 fi
 
+# ── Cost summary ──────────────────────────────────────────────────────────────
+# Read the session cost file written by the MCP server (if present).
+# Only prints when >0 routing calls were made.
+COST_FILE="${HOME}/.claude/merlin/session-cost.json"
+if [ -f "${COST_FILE}" ]; then
+  COST_SUMMARY=""
+  if command -v node >/dev/null 2>&1; then
+    COST_SUMMARY="$(node -e "
+try {
+  const d = JSON.parse(require('fs').readFileSync('${COST_FILE}', 'utf8'));
+  if (d.totalCalls > 0) {
+    const tot = (d.totalEstimatedCost || 0).toFixed(4);
+    const calls = d.totalCalls || 0;
+    const tc = d.tokenCounts || {};
+    const tokens = (tc.totalInput || 0) + (tc.totalOutput || 0);
+    const tokStr = tokens > 0 ? ', ' + Math.round(tokens/1000) + 'K tokens' : '';
+    process.stdout.write('Session cost: \$' + tot + ' (' + calls + ' call' + (calls !== 1 ? 's' : '') + tokStr + ')');
+  }
+} catch(e) {}
+" 2>/dev/null || true)"
+  elif command -v python3 >/dev/null 2>&1; then
+    COST_SUMMARY="$(python3 -c "
+import json, sys
+try:
+    with open('${COST_FILE}') as f:
+        d = json.load(f)
+    if d.get('totalCalls', 0) > 0:
+        tot = d.get('totalEstimatedCost', 0)
+        calls = d.get('totalCalls', 0)
+        tc = d.get('tokenCounts', {})
+        tokens = tc.get('totalInput', 0) + tc.get('totalOutput', 0)
+        tok_str = (', ' + str(round(tokens/1000)) + 'K tokens') if tokens > 0 else ''
+        plural = '' if calls == 1 else 's'
+        sys.stdout.write(f'Session cost: \${tot:.4f} ({calls} call{plural}{tok_str})')
+except Exception:
+    pass
+" 2>/dev/null || true)"
+  fi
+  if [ -n "${COST_SUMMARY}" ]; then
+    echo "[merlin] ${COST_SUMMARY}" >&2
+  fi
+fi
+
+# ── Outcome Tracking (RL-inspired prompt learning) ───────────────────────────
+# Classify this session's outcome and append to the learning log.
+# Classification is intentional kept simple — git diff + agents used only.
+# Never blocks shutdown; always best-effort.
+if command -v jq >/dev/null 2>&1 && command -v git >/dev/null 2>&1; then
+  LEARNING_DIR="${HOME}/.claude/merlin/learning"
+  mkdir -p "${LEARNING_DIR}" 2>/dev/null || true
+
+  OUTCOME_FILE="${LEARNING_DIR}/outcomes.jsonl"
+  OUTCOME_TS="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+
+  # Count files changed vs HEAD (uncommitted + committed this session)
+  OUTCOME_FILES_CHANGED=0
+  if git rev-parse --git-dir >/dev/null 2>&1; then
+    # Uncommitted
+    uncommitted="$(git diff --stat HEAD 2>/dev/null | tail -1 | grep -oE '[0-9]+ file' | grep -oE '[0-9]+' || echo 0)"
+    # Committed this session
+    sid_o="$(jq -r '.id // ""' "${MERLIN_SESSION_FILE}" 2>/dev/null || echo "")"
+    start_epoch_o="$(echo "${sid_o}" | cut -d'-' -f1 2>/dev/null || echo "")"
+    committed=0
+    if [ -n "${start_epoch_o}" ] && [ "${start_epoch_o}" -gt 0 ] 2>/dev/null; then
+      committed="$(git log --since="@${start_epoch_o}" --name-only --pretty=format: 2>/dev/null | grep -vc '^$' || echo 0)"
+    fi
+    OUTCOME_FILES_CHANGED=$(( ${uncommitted:-0} + ${committed:-0} ))
+  fi
+
+  # Determine agents used in this session
+  OUTCOME_AGENT="unknown"
+  if [ -f "${MERLIN_SESSION_FILE}" ]; then
+    first_agent="$(jq -r '[.events[] | select(.type == "agent_route") | .data.agent] | first // "unknown"' \
+      "${MERLIN_SESSION_FILE}" 2>/dev/null || echo "unknown")"
+    OUTCOME_AGENT="${first_agent:-unknown}"
+  fi
+
+  # Classify outcome:
+  # SUCCESS  — files changed AND session file shows no error flag
+  # PARTIAL  — files changed but session had errors or warnings
+  # FAILURE  — no files changed
+  OUTCOME_CLASS="failure"
+  SESSION_HAD_ERRORS=0
+  if [ -f "${MERLIN_SESSION_FILE}" ]; then
+    err_count="$(jq '[.events[] | select(.type == "error")] | length' "${MERLIN_SESSION_FILE}" 2>/dev/null || echo 0)"
+    SESSION_HAD_ERRORS="${err_count:-0}"
+  fi
+
+  if [ "${OUTCOME_FILES_CHANGED}" -gt 0 ] 2>/dev/null; then
+    if [ "${SESSION_HAD_ERRORS:-0}" -gt 0 ] 2>/dev/null; then
+      OUTCOME_CLASS="partial"
+    else
+      OUTCOME_CLASS="success"
+    fi
+  fi
+
+  # Duration
+  OUTCOME_DURATION=0
+  if [ -f "${MERLIN_SESSION_FILE}" ]; then
+    OUTCOME_DURATION="$(jq -r '.durationSeconds // 0' "${MERLIN_SESSION_FILE}" 2>/dev/null || echo 0)"
+  fi
+
+  # Append outcome line (append-only)
+  outcome_line="$(jq -cn \
+    --arg ts "${OUTCOME_TS}" \
+    --arg agent "${OUTCOME_AGENT}" \
+    --arg outcome "${OUTCOME_CLASS}" \
+    --argjson files "${OUTCOME_FILES_CHANGED}" \
+    --argjson duration "${OUTCOME_DURATION}" \
+    '{"timestamp":$ts,"agent":$agent,"outcome":$outcome,"files_changed":$files,"duration":$duration}' \
+    2>/dev/null || true)"
+
+  if [ -n "${outcome_line}" ]; then
+    echo "${outcome_line}" >> "${OUTCOME_FILE}" 2>/dev/null || true
+  fi
+
+  # Keep outcomes.jsonl bounded — drop lines older than 90 days
+  if [ -f "${OUTCOME_FILE}" ]; then
+    cutoff_epoch="$(date -u -v-90d +%s 2>/dev/null || date -u -d '90 days ago' +%s 2>/dev/null || echo 0)"
+    if [ "${cutoff_epoch}" -gt 0 ] 2>/dev/null; then
+      tmp_out="${OUTCOME_FILE}.tmp"
+      while IFS= read -r line; do
+        line_ts="$(echo "${line}" | jq -r '.timestamp // ""' 2>/dev/null || echo "")"
+        if [ -z "${line_ts}" ]; then continue; fi
+        line_epoch="$(date -u -d "${line_ts}" +%s 2>/dev/null || date -u -j -f "%Y-%m-%dT%H:%M:%SZ" "${line_ts}" +%s 2>/dev/null || echo 0)"
+        if [ "${line_epoch}" -ge "${cutoff_epoch}" ] 2>/dev/null; then
+          echo "${line}"
+        fi
+      done < "${OUTCOME_FILE}" > "${tmp_out}" 2>/dev/null && mv "${tmp_out}" "${OUTCOME_FILE}" 2>/dev/null || true
+    fi
+  fi
+fi
+
+# ── Behavior promotion check ─────────────────────────────────────────────────
+# The MCP server writes promotion-ready behaviors to a temp cache file during
+# the session (via merlin_apply_behavior / merlin_get_behaviors).
+# File: ~/.claude/merlin/promotion-candidates.json
+# Format: { "candidates": [{ "id": "...", "pattern": "...", "confidence": 0.9 }] }
+#
+# We never auto-promote — just surface a tip so the user can decide.
+PROMOTION_CACHE="${HOME}/.claude/merlin/promotion-candidates.json"
+
+if [ -f "${PROMOTION_CACHE}" ] && command -v jq >/dev/null 2>&1; then
+  CANDIDATE_COUNT=$(jq '.candidates | length' "${PROMOTION_CACHE}" 2>/dev/null || echo 0)
+
+  if [ "${CANDIDATE_COUNT:-0}" -gt 0 ] 2>/dev/null; then
+    TOP_PATTERN=$(jq -r '
+      .candidates
+      | sort_by(-.confidence)
+      | .[0].pattern
+      | if length > 60 then .[:60] + "..." else . end
+    ' "${PROMOTION_CACHE}" 2>/dev/null || echo "a learned behavior")
+
+    OTHERS=$(( CANDIDATE_COUNT - 1 ))
+    if [ "${OTHERS}" -gt 0 ]; then
+      echo "[merlin] Behavior '${TOP_PATTERN}' (and ${OTHERS} more) is ready for promotion. Run /merlin:promote to review." >&2
+    else
+      echo "[merlin] Behavior '${TOP_PATTERN}' is ready for promotion. Run /merlin:promote to review." >&2
+    fi
+
+    log_event "promotion_candidates_found" "$(printf '{"count":%d}' "${CANDIDATE_COUNT}")"
+  fi
+fi
+
 # Claude Code command hooks must output valid JSON to stdout
 echo '{}'
 exit 0

package/files/hooks/session-start.sh

@@ -176,16 +176,29 @@ _merlin_auto_update() {
 }
 _merlin_auto_update &
 
-# ── 3. Context injection (the only stdout output) ──────────────
+# ── 3. Voice mode check (background) ──────────────────────────
+# If voice_mode_concise is enabled in settings, export env var for the session.
+_merlin_check_voice_mode() {
+  local settings_file="${HOME}/.claude/merlin/settings.local.json"
+  [ -f "${settings_file}" ] || return 0
+  command -v jq >/dev/null 2>&1 || return 0
+  local voice
+  voice=$(jq -r '.voice_mode_concise // false' "${settings_file}" 2>/dev/null) || return 0
+  [ "${voice}" = "true" ] && export MERLIN_VOICE_MODE=1
+}
+_merlin_check_voice_mode
+
+# ── 4. Context injection (the only stdout output) ──────────────
 # Output additionalContext JSON for Claude to see at session start.
 # Full boot instructions are in CLAUDE.md — this is a lightweight nudge.
-cat <<'CONTEXT_JSON'
-{
+_voice_note=""
+[ "${MERLIN_VOICE_MODE:-}" = "1" ] && _voice_note=" Voice mode active: keep all responses short and direct."
+
+printf '{
   "hookSpecificOutput": {
     "hookEventName": "SessionStart",
-    "additionalContext": "STOP. Your FIRST action must be: call merlin_get_selected_repo, then call merlin_get_project_status, then show the user a status summary. Do not respond to the user until you complete these calls."
+    "additionalContext": "STOP. Your FIRST action must be: call merlin_get_selected_repo, then call merlin_get_project_status, then show the user a status summary. Do not respond to the user until you complete these calls.%s"
   }
-}
-CONTEXT_JSON
+}\n' "${_voice_note}"
 
 exit 0