create-merlin-brain 3.11.0 → 3.13.0

package/files/hook-templates/todo-tracker.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+#
+# Hook Template: todo-tracker.sh
+# Event: PostToolUse (Write, Edit)
+#
+# Scans modified files for new TODO, FIXME, HACK, XXX, and TEMP comments.
+# Reports them so they don't silently accumulate without notice.
+#
+# HOW TO INSTALL:
+#   Copy this file to ~/.claude/merlin/hooks/todo-tracker.sh
+#   Then add to your .claude/settings.local.json:
+#
+#   {
+#     "hooks": {
+#       "PostToolUse": [
+#         {
+#           "matcher": "Write|Edit",
+#           "hooks": [{ "type": "command", "command": "~/.claude/merlin/hooks/todo-tracker.sh" }]
+#         }
+#       ]
+#     }
+#   }
+#
+# BEHAVIOR: Advisory only. Lists new TODO-style comments found in the changed file.
+#           Exits 0 (no blocking) — just surfaces the information.
+#
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+TODO_PATTERN='TODO|FIXME|HACK|XXX|TEMP|NOCOMMIT|REMOVEME'
+
+# Read tool input from stdin
+input=""
+if [ ! -t 0 ]; then
+  input=$(cat 2>/dev/null || true)
+fi
+
+[ -z "$input" ] && { echo '{}'; exit 0; }
+
+# Extract file path
+file_path=""
+if command -v jq >/dev/null 2>&1; then
+  file_path=$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null || true)
+fi
+
+[ -z "$file_path" ] || [ ! -f "$file_path" ] && { echo '{}'; exit 0; }
+
+# Only scan source code files
+case "$file_path" in
+  *.js|*.jsx|*.ts|*.tsx|*.mjs|*.py|*.go|*.java|*.rb|*.rs|*.swift|*.c|*.cpp|*.h|*.sh|*.md)
+    ;;
+  *)
+    echo '{}'
+    exit 0
+    ;;
+esac
+
+# Skip node_modules and generated files
+case "$file_path" in
+  *node_modules*|*dist/*|*build/*|*vendor/*)
+    echo '{}'
+    exit 0
+    ;;
+esac
+
+# Find TODO-style comments with line numbers
+todos=$(grep -nE "$TODO_PATTERN" "$file_path" 2>/dev/null | head -20 || true)
+
+if [ -n "$todos" ]; then
+  count=$(echo "$todos" | wc -l | tr -d ' ')
+  echo "TODO TRACKER: ${count} annotation(s) found in ${file_path}:" >&2
+  echo "$todos" | while IFS= read -r line; do
+    echo "  $line" >&2
+  done
+  echo "  Track these in your issue tracker to avoid tech debt accumulation." >&2
+fi
+
+# Always exit 0 — informational only, never blocking
+echo '{}'
+exit 0

package/files/hooks/check-file-size.sh

@@ -4,16 +4,29 @@
 # Checks if the modified file exceeds the 400-line convention.
 # Exits with code 2 to inject feedback when file is too large.
 #
-# Agent-type awareness: docs-keeper and merlin-verifier agents are exempt
-# from the 400-line limit (they work with doc/verification files).
+# Agent-type awareness: only enforce for implementation agents.
+# Non-code agents (docs, review, verify, etc.) are fully exempt.
 #
 set -euo pipefail
 trap 'echo "{}"; exit 0' ERR
 
-# Check agent type — skip enforcement for non-implementation agents
+# Read CLAUDE_AGENT_TYPE from env — support both var names
 AGENT_TYPE="${CLAUDE_AGENT_TYPE:-${CLAUDE_CODE_AGENT_TYPE:-main}}"
+
+# Only enforce for implementation agents
+# Skip for all doc/review/verification/analysis agents
 case "$AGENT_TYPE" in
-  docs-keeper|merlin-verifier)
+  implementation-dev|merlin-executor)
+    # Enforcement is active for these agents — continue
+    ;;
+  docs-keeper|merlin-reviewer|merlin-verifier|merlin-milestone-auditor|\
+  merlin-integration-checker|merlin-work-verifier|code-organization-supervisor|\
+  context-guardian|dry-refactor|tests-qa|merlin-codebase-mapper)
+    echo '{}'
+    exit 0
+    ;;
+  *)
+    # For all other agents (including 'main'), skip enforcement
     echo '{}'
     exit 0
     ;;

package/files/hooks/config-change.sh

@@ -2,7 +2,7 @@
 #
 # Merlin Hook: ConfigChange
 # Purpose: Validate Merlin MCP key still works after config change.
-# Also logs config changes to Sights for enterprise audit trail.
+# Logs config change events to Sights for audit trail.
 #
 # Always exits 0 — never blocks Claude Code.
 #
@@ -13,31 +13,59 @@ HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 # Source shared libs if available
 [ -f "${HOOK_DIR}/lib/analytics.sh" ] && . "${HOOK_DIR}/lib/analytics.sh"
+[ -f "${HOOK_DIR}/lib/sights-check.sh" ] && . "${HOOK_DIR}/lib/sights-check.sh"
 
-MERLIN_API_KEY="${MERLIN_API_KEY:-}"
 AGENT_ID="${CLAUDE_AGENT_ID:-unknown}"
 AGENT_TYPE="${CLAUDE_AGENT_TYPE:-main}"
+CLAUDE_DIR="${HOME}/.claude"
+
+# Resolve API key: env var takes priority, fall back to config.json
+MERLIN_API_KEY="${MERLIN_API_KEY:-}"
+if [ -z "$MERLIN_API_KEY" ] && declare -f get_merlin_api_key >/dev/null 2>&1; then
+  MERLIN_API_KEY="$(get_merlin_api_key)"
+fi
+
+# Detect which MCP servers are configured for audit trail
+MCP_SERVERS=""
+if [ -f "${CLAUDE_DIR}/config.json" ] && command -v jq >/dev/null 2>&1; then
+  MCP_SERVERS=$(jq -r '(.mcpServers // {}) | keys | join(",")' \
+    "${CLAUDE_DIR}/config.json" 2>/dev/null || echo "")
+fi
+
+HAS_KEY="$([ -n "$MERLIN_API_KEY" ] && echo true || echo false)"
+KEY_VALID="unknown"
+
+# Validate key format if present (valid prefixes: mrln_ or ccw_)
+if [ -n "$MERLIN_API_KEY" ]; then
+  case "$MERLIN_API_KEY" in
+    mrln_*|ccw_*)
+      KEY_VALID="true"
+      ;;
+    *)
+      KEY_VALID="false"
+      echo "Merlin: API key has unexpected format after config change" >&2
+      ;;
+  esac
+fi
+
+# Write audit trail entry to local log
+AUDIT_DIR="${HOME}/.claude/merlin/audit"
+mkdir -p "$AUDIT_DIR" 2>/dev/null || true
+printf '{"ts":"%s","agent_id":"%s","agent_type":"%s","has_key":%s,"key_valid":"%s","mcp_servers":"%s"}\n' \
+  "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
+  "$AGENT_ID" "$AGENT_TYPE" "$HAS_KEY" "$KEY_VALID" "$MCP_SERVERS" \
+  >> "${AUDIT_DIR}/config-changes.log" 2>/dev/null || true
 
 # Log config change event if analytics available
 if declare -f log_event >/dev/null 2>&1; then
-  log_event "config_change" "$(printf '{"agent_id":"%s","agent_type":"%s","has_key":"%s"}' "$AGENT_ID" "$AGENT_TYPE" "$([ -n "$MERLIN_API_KEY" ] && echo true || echo false)")"
+  log_event "config_change" "$(printf \
+    '{"agent_id":"%s","agent_type":"%s","has_key":%s,"key_valid":"%s","mcp_servers":"%s"}' \
+    "$AGENT_ID" "$AGENT_TYPE" "$HAS_KEY" "$KEY_VALID" "$MCP_SERVERS")"
 fi
 
 if [ -z "$MERLIN_API_KEY" ]; then
-  echo "Merlin: No API key configured after config change" >&2
-  echo '{}'
-  exit 0
+  echo "Merlin: No API key configured — Sights features disabled" >&2
 fi
 
-# Quick validation — check key format (valid prefixes: mrln_ or ccw_)
-case "$MERLIN_API_KEY" in
-  mrln_*|ccw_*)
-    # Valid prefix — no-op
-    ;;
-  *)
-    echo "Merlin: API key has unexpected format after config change" >&2
-    ;;
-esac
-
 echo '{}'
 exit 0

package/files/hooks/instructions-loaded.sh

@@ -4,6 +4,9 @@
 # Purpose: Pre-warm Merlin Sights connection when CLAUDE.md loads.
 # Fires BEFORE session-start, giving us a head start on context loading.
 #
+# Cold-start optimization: touching the sights-check timestamp file signals
+# that Merlin is active so the first pre-edit check doesn't fire a warning.
+#
 # Always exits 0 — never blocks Claude Code startup.
 #
 set -euo pipefail
@@ -17,18 +20,32 @@ HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=lib/sights-check.sh
 [ -f "${HOOK_DIR}/lib/sights-check.sh" ] && . "${HOOK_DIR}/lib/sights-check.sh"
 
-# Log agent context if available
 AGENT_ID="${CLAUDE_AGENT_ID:-unknown}"
 AGENT_TYPE="${CLAUDE_AGENT_TYPE:-main}"
+MERLIN_DIR="${HOME}/.claude/merlin"
+
+# Cold-start pre-warm: record that Sights is active so the pre-edit hook
+# doesn't fire a "Sights not consulted" warning immediately after boot.
+# Only touch if the file is stale (>300s old) or missing — avoids
+# re-stamping on every CLAUDE.md reload within the same session.
+if declare -f record_sights_call >/dev/null 2>&1; then
+  if ! sights_was_checked_recently 300 2>/dev/null; then
+    record_sights_call 2>/dev/null || true
+  fi
+fi
+
+# Write a lightweight cold-start marker so session-start can detect
+# that instructions were already loaded (avoids double context fetch).
+mkdir -p "${MERLIN_DIR}" 2>/dev/null || true
+printf '%s' "$(date +%s)" > "${MERLIN_DIR}/.instructions-loaded-ts" 2>/dev/null || true
 
 # Log the instructions-loaded event if analytics is available
 if declare -f log_event >/dev/null 2>&1; then
-  log_event "instructions_loaded" "$(printf '{"agent_id":"%s","agent_type":"%s","cwd":"%s"}' "$AGENT_ID" "$AGENT_TYPE" "${PWD:-}")"
+  log_event "instructions_loaded" "$(printf '{"agent_id":"%s","agent_type":"%s","cwd":"%s"}' \
+    "$AGENT_ID" "$AGENT_TYPE" "${PWD:-}")"
 fi
 
-# Signal that Merlin instructions were loaded
-# The MCP server will handle actual Sights connection
-echo "Merlin instructions loaded — Sights pre-warming (agent: ${AGENT_TYPE})" >&2
+echo "Merlin instructions loaded — Sights pre-warmed (agent: ${AGENT_TYPE})" >&2
 
 echo '{}'
 exit 0

package/files/hooks/notify-desktop.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+#
+# Merlin Hook: notify-desktop.sh
+# Events: Notification, Stop
+#
+# Sends a desktop notification when Claude finishes work or needs input.
+# Reads notification config from .merlin/config.json in the project root.
+# Always exits 0 — notifications must never block the main session.
+#
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+# ── Config resolution ─────────────────────────────────────────────
+# Resolve project root: prefer CLAUDE_WORKTREE_PATH, fall back to PWD
+PROJECT_ROOT="${CLAUDE_WORKTREE_PATH:-${PWD:-$(pwd)}}"
+CONFIG_FILE="${PROJECT_ROOT}/.merlin/config.json"
+
+# Read a value from .merlin/config.json using jq or python3 as fallback
+_read_config() {
+  local key="${1}" default="${2:-}"
+  if [ ! -f "${CONFIG_FILE}" ]; then
+    echo "${default}"
+    return 0
+  fi
+  local val
+  if command -v jq >/dev/null 2>&1; then
+    val=$(jq -r "${key} // \"${default}\"" "${CONFIG_FILE}" 2>/dev/null) || val="${default}"
+  elif command -v python3 >/dev/null 2>&1; then
+    val=$(python3 -c "
+import json, sys
+try:
+    d = json.load(open('${CONFIG_FILE}'))
+    keys = '${key}'.lstrip('.').split('.')
+    v = d
+    for k in keys:
+        v = v.get(k, None)
+        if v is None:
+            break
+    print(v if v is not None else '${default}')
+except:
+    print('${default}')
+" 2>/dev/null) || val="${default}"
+  else
+    val="${default}"
+  fi
+  echo "${val}"
+}
+
+# Check if desktop notifications are enabled (default: true)
+DESKTOP_ENABLED=$(_read_config '.notifications.desktop' 'true')
+if [ "${DESKTOP_ENABLED}" = "false" ]; then
+  echo '{}'
+  exit 0
+fi
+
+# Check notify_on list to see if this event type is included
+HOOK_EVENT="${CLAUDE_HOOK_EVENT:-Stop}"
+NOTIFY_ON=$(_read_config '.notifications.notify_on' '["stop","needs_input","error"]')
+
+# Map hook event names to notify_on values
+case "${HOOK_EVENT}" in
+  Stop)       EVENT_KEY="stop" ;;
+  Notification) EVENT_KEY="needs_input" ;;
+  *)          EVENT_KEY="stop" ;;
+esac
+
+# Check if this event is in the notify_on list
+EVENT_ENABLED=false
+if echo "${NOTIFY_ON}" | grep -q "\"${EVENT_KEY}\"" 2>/dev/null; then
+  EVENT_ENABLED=true
+fi
+# Default to true if we couldn't parse (degraded gracefully)
+if [ "${NOTIFY_ON}" = '["stop","needs_input","error"]' ]; then
+  EVENT_ENABLED=true
+fi
+
+if [ "${EVENT_ENABLED}" = "false" ]; then
+  echo '{}'
+  exit 0
+fi
+
+# ── Build notification message ─────────────────────────────────────
+# Read stdin for hook context (non-blocking, best-effort)
+HOOK_INPUT=""
+if [ -t 0 ]; then
+  # stdin is a terminal, no piped input
+  HOOK_INPUT=""
+else
+  HOOK_INPUT=$(cat 2>/dev/null || true)
+fi
+
+# Determine message based on event type
+case "${HOOK_EVENT}" in
+  Stop)
+    # Extract agent type for context if available
+    AGENT_TYPE="${CLAUDE_AGENT_TYPE:-main}"
+    if [ "${AGENT_TYPE}" != "main" ] && [ "${AGENT_TYPE}" != "unknown" ]; then
+      MESSAGE="Task complete (${AGENT_TYPE} agent)"
+    else
+      MESSAGE="Task complete — Claude has finished working"
+    fi
+    ;;
+  Notification)
+    MESSAGE="Claude needs your input"
+    ;;
+  *)
+    MESSAGE="Merlin: Task complete"
+    ;;
+esac
+
+TITLE="Merlin"
+SOUND_ENABLED=$(_read_config '.notifications.sound' 'false')
+
+# ── Detect OS and send notification ───────────────────────────────
+OS_TYPE="$(uname -s 2>/dev/null || echo 'unknown')"
+
+case "${OS_TYPE}" in
+  Darwin)
+    # macOS — use osascript
+    osascript -e "display notification \"${MESSAGE}\" with title \"${TITLE}\" sound name \"Glass\"" \
+      >/dev/null 2>&1 &
+
+    # Optional extra sound (beyond what osascript plays)
+    if [ "${SOUND_ENABLED}" = "true" ]; then
+      SOUND_FILE="/System/Library/Sounds/Glass.aiff"
+      if [ -f "${SOUND_FILE}" ]; then
+        afplay "${SOUND_FILE}" >/dev/null 2>&1 &
+      fi
+    fi
+    ;;
+
+  Linux)
+    # Linux — use notify-send if available
+    if command -v notify-send >/dev/null 2>&1; then
+      notify-send "${TITLE}" "${MESSAGE}" --icon=dialog-information \
+        >/dev/null 2>&1 &
+    fi
+
+    # Optional sound on Linux
+    if [ "${SOUND_ENABLED}" = "true" ]; then
+      SOUND_FILE="/usr/share/sounds/freedesktop/stereo/complete.oga"
+      if [ -f "${SOUND_FILE}" ] && command -v paplay >/dev/null 2>&1; then
+        paplay "${SOUND_FILE}" >/dev/null 2>&1 &
+      fi
+    fi
+    ;;
+
+  *)
+    # Unknown OS — exit silently
+    echo '{}'
+    exit 0
+    ;;
+esac
+
+# Claude Code command hooks must output valid JSON to stdout
+echo '{}'
+exit 0

package/files/hooks/notify-webhook.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+#
+# Merlin Hook: notify-webhook.sh
+# Event: Stop
+#
+# Fires Slack and/or Discord webhooks when Claude finishes a task.
+# Reads webhook URLs from .merlin/config.json in the project root.
+# All curl calls are fire-and-forget (background, 5s timeout).
+# Always exits 0 — webhooks must never block the main session.
+#
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+# ── Require curl ──────────────────────────────────────────────────
+if ! command -v curl >/dev/null 2>&1; then
+  echo '{}'
+  exit 0
+fi
+
+# ── Config resolution ─────────────────────────────────────────────
+PROJECT_ROOT="${CLAUDE_WORKTREE_PATH:-${PWD:-$(pwd)}}"
+CONFIG_FILE="${PROJECT_ROOT}/.merlin/config.json"
+
+_read_config() {
+  local key="${1}" default="${2:-}"
+  if [ ! -f "${CONFIG_FILE}" ]; then
+    echo "${default}"
+    return 0
+  fi
+  local val
+  if command -v jq >/dev/null 2>&1; then
+    val=$(jq -r "${key} // \"${default}\"" "${CONFIG_FILE}" 2>/dev/null) || val="${default}"
+  elif command -v python3 >/dev/null 2>&1; then
+    val=$(python3 -c "
+import json, sys
+try:
+    d = json.load(open('${CONFIG_FILE}'))
+    keys = '${key}'.lstrip('.').split('.')
+    v = d
+    for k in keys:
+        v = v.get(k, None)
+        if v is None:
+            break
+    print(v if v is not None else '${default}')
+except:
+    print('${default}')
+" 2>/dev/null) || val="${default}"
+  else
+    val="${default}"
+  fi
+  echo "${val}"
+}
+
+SLACK_WEBHOOK=$(_read_config '.notifications.slack_webhook' '')
+DISCORD_WEBHOOK=$(_read_config '.notifications.discord_webhook' '')
+
+# Exit early if no webhooks are configured
+if [ -z "${SLACK_WEBHOOK}" ] && [ -z "${DISCORD_WEBHOOK}" ]; then
+  echo '{}'
+  exit 0
+fi
+
+# ── Build context ─────────────────────────────────────────────────
+AGENT_NAME="${CLAUDE_AGENT_TYPE:-main}"
+if [ "${AGENT_NAME}" = "unknown" ] || [ -z "${AGENT_NAME}" ]; then
+  AGENT_NAME="main"
+fi
+
+# Calculate session duration from session analytics file if available
+SESSION_ID="${MERLIN_SESSION_ID:-}"
+DURATION_STR="unknown"
+if [ -n "${SESSION_ID}" ]; then
+  SESSION_FILE="${HOME}/.claude/merlin/analytics/session-${SESSION_ID}.json"
+  if [ -f "${SESSION_FILE}" ] && command -v jq >/dev/null 2>&1; then
+    START_TS=$(jq -r '.startTime // ""' "${SESSION_FILE}" 2>/dev/null || echo "")
+    if [ -n "${START_TS}" ]; then
+      START_EPOCH=$(date -d "${START_TS}" +%s 2>/dev/null \
+        || python3 -c "import datetime; print(int(datetime.datetime.fromisoformat('${START_TS}'.replace('Z','+00:00')).timestamp()))" 2>/dev/null \
+        || echo "")
+      if [ -n "${START_EPOCH}" ]; then
+        NOW_EPOCH=$(date +%s)
+        ELAPSED=$(( NOW_EPOCH - START_EPOCH ))
+        MINUTES=$(( ELAPSED / 60 ))
+        SECONDS=$(( ELAPSED % 60 ))
+        DURATION_STR="${MINUTES}m ${SECONDS}s"
+      fi
+    fi
+  fi
+fi
+
+STATUS_TEXT="Success"
+STATUS_ICON="OK"
+
+# ── Slack webhook ─────────────────────────────────────────────────
+if [ -n "${SLACK_WEBHOOK}" ]; then
+  SLACK_BODY=$(cat <<SLACK_JSON
+{
+  "text": "Merlin: Task completed",
+  "blocks": [
+    {
+      "type": "section",
+      "text": {
+        "type": "mrkdwn",
+        "text": "*Merlin Task Complete*\n\nAgent: ${AGENT_NAME}\nDuration: ${DURATION_STR}\nStatus: ${STATUS_ICON} ${STATUS_TEXT}"
+      }
+    }
+  ]
+}
+SLACK_JSON
+)
+  curl \
+    --max-time 5 \
+    --silent \
+    --output /dev/null \
+    --request POST \
+    --header "Content-Type: application/json" \
+    --data "${SLACK_BODY}" \
+    "${SLACK_WEBHOOK}" &
+fi
+
+# ── Discord webhook ───────────────────────────────────────────────
+if [ -n "${DISCORD_WEBHOOK}" ]; then
+  DISCORD_BODY=$(cat <<DISCORD_JSON
+{
+  "content": "**Merlin Task Complete**\n\nAgent: ${AGENT_NAME}\nDuration: ${DURATION_STR}\nStatus: ${STATUS_ICON} ${STATUS_TEXT}"
+}
+DISCORD_JSON
+)
+  curl \
+    --max-time 5 \
+    --silent \
+    --output /dev/null \
+    --request POST \
+    --header "Content-Type: application/json" \
+    --data "${DISCORD_BODY}" \
+    "${DISCORD_WEBHOOK}" &
+fi
+
+# Claude Code command hooks must output valid JSON to stdout
+echo '{}'
+exit 0

package/files/hooks/pre-edit-sights-check.sh

@@ -1,8 +1,11 @@
 #!/usr/bin/env bash
 #
 # Merlin Hook: PreToolUse (Edit/Write)
-# Checks if Sights was consulted recently before file edits.
-# Advisory only — always exits 0, never blocks edits.
+# Two responsibilities:
+#   1. Secret detection — blocks writes that contain leaked credentials.
+#      Exit code 2 with a clear message. This is the only hard block.
+#   2. Sights consultation check — advisory warning if Sights was not
+#      consulted recently. Always exits 0 (never blocks on this).
 #
 set -euo pipefail
 trap 'echo "{}"; exit 0' ERR
@@ -11,9 +14,9 @@ HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 # Source shared libraries
 # shellcheck source=lib/analytics.sh
-. "${HOOKS_DIR}/lib/analytics.sh"
+[ -f "${HOOKS_DIR}/lib/analytics.sh" ] && . "${HOOKS_DIR}/lib/analytics.sh"
 # shellcheck source=lib/sights-check.sh
-. "${HOOKS_DIR}/lib/sights-check.sh"
+[ -f "${HOOKS_DIR}/lib/sights-check.sh" ] && . "${HOOKS_DIR}/lib/sights-check.sh"
 
 # Read tool input from stdin (Claude Code pipes JSON)
 input=""
@@ -21,19 +24,83 @@ if [ ! -t 0 ]; then
   input=$(cat 2>/dev/null || true)
 fi
 
-# Extract file path from tool input
+# Extract file path and content from tool input
 file_path=""
+content_to_write=""
 if [ -n "$input" ] && command -v jq >/dev/null 2>&1; then
   file_path=$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null || true)
+  # Write tool has 'content', Edit tool has 'new_string'
+  content_to_write=$(echo "$input" | jq -r '.tool_input.content // .tool_input.new_string // empty' 2>/dev/null || true)
 fi
 
-# Check if Sights was consulted recently (within 120 seconds)
-if ! sights_was_checked_recently 120; then
-  log_event "sights_skip_warning" "$(printf '{"file":"%s"}' "${file_path:-unknown}")"
+# ─────────────────────────────────────────────────────────────────────────────
+# SECRET DETECTION
+# Scans the content being written for common credential patterns.
+# Uses grep with POSIX ERE for speed (<5ms on typical file sizes).
+# ─────────────────────────────────────────────────────────────────────────────
+if [ -n "$content_to_write" ]; then
+  SECRET_FOUND=""
+  SECRET_TYPE=""
+
+  # AWS access key: AKIA followed by 16 uppercase alphanumeric chars
+  if echo "$content_to_write" | grep -qE 'AKIA[0-9A-Z]{16}' 2>/dev/null; then
+    SECRET_FOUND=1
+    SECRET_TYPE="AWS access key (AKIA...)"
+  fi
+
+  # OpenAI / Anthropic style API key: sk- followed by 48+ alphanumeric chars
+  if [ -z "$SECRET_FOUND" ] && echo "$content_to_write" | grep -qE 'sk-[a-zA-Z0-9]{48,}' 2>/dev/null; then
+    SECRET_FOUND=1
+    SECRET_TYPE="API secret key (sk-...)"
+  fi
+
+  # PEM private key header
+  if [ -z "$SECRET_FOUND" ] && echo "$content_to_write" | \
+      grep -qE '-----BEGIN (RSA|EC|DSA|OPENSSH|PRIVATE) KEY-----' 2>/dev/null; then
+    SECRET_FOUND=1
+    SECRET_TYPE="PEM private key"
+  fi
+
+  # Generic password assignment in config-like contexts
+  # Matches: password=, PASSWORD=, "password": "...", passwd=
+  # Requires the value to be non-empty and at least 8 chars to avoid false positives
+  if [ -z "$SECRET_FOUND" ] && echo "$content_to_write" | \
+      grep -qiE '(password|passwd|secret|api_key|apikey)\s*[=:]\s*["\x27]?[A-Za-z0-9@#$%^&*!_\-]{8,}' 2>/dev/null; then
+    # Exclude known placeholder patterns: <password>, ${PASSWORD}, %(password)s, REPLACE_ME, etc.
+    if ! echo "$content_to_write" | \
+        grep -qiE '(password|passwd|secret|api_key|apikey)\s*[=:]\s*["\x27]?(<[^>]+>|\$\{[^}]+\}|%\([^)]+\)s|REPLACE_ME|YOUR_|TODO|CHANGEME|example|placeholder|xxx+|test)' 2>/dev/null; then
+      SECRET_FOUND=1
+      SECRET_TYPE="credential assignment (password/secret/api_key)"
+    fi
+  fi
+
+  if [ -n "$SECRET_FOUND" ]; then
+    if declare -f log_event >/dev/null 2>&1; then
+      log_event "secret_detected" "$(printf '{"file":"%s","type":"%s"}' \
+        "${file_path:-unknown}" "$SECRET_TYPE")"
+    fi
+    echo "SECRET DETECTED: ${SECRET_TYPE} found in write to '${file_path:-unknown}'. Remove the secret before committing." >&2
+    # Output block decision — Claude Code reads this JSON when exit code is 2
+    echo '{"decision":"block","reason":"Secret detected in file write. Remove the secret before committing."}'
+    exit 2
+  fi
+fi
+
+# ─────────────────────────────────────────────────────────────────────────────
+# SIGHTS CONSULTATION CHECK (advisory only)
+# ─────────────────────────────────────────────────────────────────────────────
+if declare -f sights_was_checked_recently >/dev/null 2>&1; then
+  if ! sights_was_checked_recently 120; then
+    if declare -f log_event >/dev/null 2>&1; then
+      log_event "sights_skip_warning" "$(printf '{"file":"%s"}' "${file_path:-unknown}")"
+    fi
+  fi
 fi
 
 # Log the pre-edit event
-log_event "pre_edit" "$(printf '{"file":"%s"}' "${file_path:-unknown}")"
+if declare -f log_event >/dev/null 2>&1; then
+  log_event "pre_edit" "$(printf '{"file":"%s"}' "${file_path:-unknown}")"
+fi
 
 # Claude Code command hooks must output valid JSON to stdout
 echo '{}'