cc-safe-setup 29.8.0 → 30.0.5

package/examples/mcp-startup-bloat-detector.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+# ================================================================
+# mcp-startup-bloat-detector.sh — Warn when claude.ai connector
+#   sync inflates the System tools context at session start.
+# ================================================================
+# PURPOSE:
+#   Pro / Claude.ai-OAuth users inherit every connector configured
+#   on their claude.ai account into every CLI session. The MCP
+#   tool definitions and authentication entries each consume
+#   ~250-330 tokens of context, and at scale they can dominate
+#   the context window before the user has typed anything.
+#
+# TRIGGER: SessionStart
+# MATCHER: (none)
+#
+# WHY THIS MATTERS:
+#   Issue #50062 (closed 2026-04-19) reported ~100k tokens of
+#   silent connector bloat; the v2.1.14 fix added the
+#   ENABLE_CLAUDEAI_MCP_SERVERS=false escape hatch.
+#
+#   Issue #57235 (filed 2026-05-08, v2.1.133) reports the same
+#   pattern at 2.9M tokens — 29x larger — leaving /context at
+#   1,460% before the first user turn. Either the v2.1.14 fix
+#   regressed, or a new path bypasses it.
+#
+#   This detector reads claude mcp list and warns when the count
+#   of claude.ai-prefixed connectors crosses a threshold, giving
+#   users a chance to set ENABLE_CLAUDEAI_MCP_SERVERS=false
+#   before the bloat hurts them.
+#
+# CONFIGURATION:
+#   MCP_BLOAT_THRESHOLD_COUNT  number of claude.ai connectors to
+#                              trigger warning (default: 5)
+#   MCP_BLOAT_DETECTOR_DISABLE set to 1 to silence this hook
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/50062
+#   https://github.com/anthropics/claude-code/issues/57235
+# ================================================================
+
+set -u
+
+[ "${MCP_BLOAT_DETECTOR_DISABLE:-0}" = "1" ] && exit 0
+
+THRESHOLD="${MCP_BLOAT_THRESHOLD_COUNT:-5}"
+LOG_DIR="${HOME}/.claude/logs"
+mkdir -p "$LOG_DIR" 2>/dev/null
+
+INPUT=$(cat 2>/dev/null || true)
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+[ -z "$SESSION_ID" ] && SESSION_ID="unknown-$(date +%s)"
+
+# One warning per session
+WARN_LOG="$LOG_DIR/mcp-bloat-warned-$SESSION_ID"
+[ -f "$WARN_LOG" ] && exit 0
+
+# Need claude binary to inspect MCP state
+if ! command -v claude >/dev/null 2>&1; then
+    exit 0
+fi
+
+# Count claude.ai-prefixed connectors. The CLI prints one per line as:
+#   claude.ai <Name>: <url> - <status>
+MCP_OUTPUT=$(claude mcp list 2>/dev/null || true)
+[ -z "$MCP_OUTPUT" ] && exit 0
+
+COUNT=$(printf '%s\n' "$MCP_OUTPUT" | grep -cE '^claude\.ai[[:space:]]' || true)
+COUNT=${COUNT:-0}
+
+if [ "$COUNT" -ge "$THRESHOLD" ]; then
+    EST_TOKENS=$((COUNT * 290))
+    cat >&2 <<MSG
+mcp-startup-bloat-detector: $COUNT claude.ai connectors auto-loaded
+  (estimated ~${EST_TOKENS} tokens of context overhead at ~290 tokens each).
+
+  If /context shows an unusually high "System tools" load, set
+  ENABLE_CLAUDEAI_MCP_SERVERS=false in your shell, remove
+  ~/.claude/.credentials.json, and re-run /login. OAuth stays;
+  the connector sync is what gets disabled.
+
+  Background: Issue #50062 (closed v2.1.14, ~100k tokens) and
+  Issue #57235 (filed 2026-05-08 v2.1.133, ~2.9M tokens).
+MSG
+    touch "$WARN_LOG"
+fi
+
+exit 0

package/examples/mcp-stdio-compatibility-test.sh

@@ -0,0 +1,153 @@
+#!/bin/bash
+# mcp-stdio-compatibility-test.sh — MCP regression test harness (Incident 8)
+# Why: v2.1.105 changed PreToolUse additionalContext + stdio framing and
+#      broke MCP servers that had worked on v2.1.104. The regression was
+#      largely fixed by v2.1.118 but custom MCP servers still need
+#      re-validation after every Claude Code upgrade. This harness
+#      exercises every MCP server registered in your settings against a
+#      known-good suite of calls so you can distinguish "MCP regression"
+#      from "auth expired" / "external resource down."
+# Event: standalone CLI, not a Claude Code hook.
+# Usage:   bash examples/mcp-stdio-compatibility-test.sh [path-to-settings.json]
+#          (defaults to ~/.claude/settings.json)
+# Exit:    0 if all servers OK; 1 if one or more regressions (parse errors,
+#          stdio framing failures). Non-regression failures (auth, network)
+#          are reported as [AUTH] or [NET] and do not set exit code 1.
+
+set -u
+
+# Without jq, the parse below silently yields empty and this hook stops
+# guarding - with no error anywhere. Say so. We deliberately do not exit
+# here: blocking would halt every tool call, and exiting 0 would change
+# the behaviour of guards that do not depend on the parsed value.
+if ! command -v jq >/dev/null 2>&1; then
+  _nojq_warned="/tmp/cc-nojq-warned-mcp-stdio-compatibility-test-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [mcp-stdio-compatibility-test]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+SETTINGS="${1:-${HOME}/.claude/settings.json}"
+LOG_DIR="${HOME}/.claude/logs"
+LOG_FILE="${LOG_DIR}/mcp-compat.log"
+mkdir -p "$LOG_DIR" 2>/dev/null
+
+if [ ! -r "$SETTINGS" ]; then
+  echo "mcp-stdio-compatibility-test: settings file not readable: $SETTINGS" >&2
+  exit 2
+fi
+
+# Reject malformed JSON up front so a parse failure isn't reported as
+# "nothing to test" — that would mask a broken config and exit 0.
+if ! jq empty "$SETTINGS" 2>/dev/null; then
+  echo "mcp-stdio-compatibility-test: settings file is not valid JSON: $SETTINGS" >&2
+  exit 2
+fi
+
+if ! jq -e '.mcpServers // empty' "$SETTINGS" >/dev/null 2>&1; then
+  echo "[info] no mcpServers block in $SETTINGS — nothing to test"
+  exit 0
+fi
+
+# Pick whichever timeout binary is available; macOS ships only `gtimeout`
+# via coreutils, while Linux usually has `timeout`. Without one of these
+# a misbehaving server could hang the whole probe loop, so fall back to
+# a no-timeout invocation only when we have warned the operator.
+if command -v timeout >/dev/null 2>&1; then
+  TIMEOUT_CMD="timeout"
+elif command -v gtimeout >/dev/null 2>&1; then
+  TIMEOUT_CMD="gtimeout"
+else
+  TIMEOUT_CMD=""
+  echo "[warn] no timeout/gtimeout in PATH — server probes may hang on misbehaving servers" >&2
+fi
+
+SERVERS=$(jq -r '.mcpServers | keys[]' "$SETTINGS" 2>/dev/null)
+if [ -z "$SERVERS" ]; then
+  echo "[info] mcpServers block is empty — nothing to test"
+  exit 0
+fi
+
+REGRESSION_COUNT=0
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# Each MCP server speaks JSON-RPC over stdio. A viable smoke test is to
+# send the initialize request and verify the server replies with a valid
+# JSON-RPC response containing serverInfo. Parse errors or non-JSON
+# output indicate the v2.1.105-class regression.
+send_initialize() {
+  local cmd="$1"
+  local args_json="$2"
+  local args_array=()
+  if [ -n "$args_json" ] && [ "$args_json" != "null" ]; then
+    while IFS= read -r a; do args_array+=("$a"); done < <(printf '%s' "$args_json" | jq -r '.[]' 2>/dev/null)
+  fi
+  local init_req='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"cc-safe-setup-compat-test","version":"1.0"}}}'
+  if [ -n "$TIMEOUT_CMD" ]; then
+    printf '%s\n' "$init_req" | "$TIMEOUT_CMD" 5 "$cmd" "${args_array[@]}" 2>&1
+  else
+    printf '%s\n' "$init_req" | "$cmd" "${args_array[@]}" 2>&1
+  fi
+}
+
+for name in $SERVERS; do
+  CMD=$(jq -r ".mcpServers[\"$name\"].command // empty" "$SETTINGS" 2>/dev/null)
+  ARGS=$(jq -c ".mcpServers[\"$name\"].args // []" "$SETTINGS" 2>/dev/null)
+  if [ -z "$CMD" ]; then
+    echo "[skip] $name: no command field"
+    printf '%s\t%s\t%s\n' "$TS" "$name" "skip-no-command" >> "$LOG_FILE"
+    continue
+  fi
+  if ! command -v "$CMD" >/dev/null 2>&1 && [ ! -x "$CMD" ]; then
+    echo "[skip] $name: command not executable ($CMD)"
+    printf '%s\t%s\t%s\n' "$TS" "$name" "skip-not-executable" >> "$LOG_FILE"
+    continue
+  fi
+  OUTPUT=$(send_initialize "$CMD" "$ARGS" 2>&1) || true
+  RESPONSE=$(printf '%s' "$OUTPUT" | grep -m1 '"jsonrpc"' || true)
+  if [ -z "$RESPONSE" ]; then
+    echo "[FAIL] $name: no JSON-RPC response (regression candidate)"
+    printf '%s\t%s\t%s\n' "$TS" "$name" "regression-no-response" >> "$LOG_FILE"
+    REGRESSION_COUNT=$((REGRESSION_COUNT + 1))
+    continue
+  fi
+  if ! printf '%s' "$RESPONSE" | jq -e . >/dev/null 2>&1; then
+    echo "[FAIL] $name: non-JSON response (v2.1.105-class regression)"
+    printf '%s\t%s\t%s\n' "$TS" "$name" "regression-parse-error" >> "$LOG_FILE"
+    REGRESSION_COUNT=$((REGRESSION_COUNT + 1))
+    continue
+  fi
+  ERR=$(printf '%s' "$RESPONSE" | jq -r '.error.code // empty' 2>/dev/null)
+  if [ -n "$ERR" ]; then
+    MSG=$(printf '%s' "$RESPONSE" | jq -r '.error.message // ""' 2>/dev/null)
+    case "$MSG" in
+      *auth*|*Auth*|*AUTH*|*permission*|*Permission*)
+        echo "[AUTH] $name: $MSG"
+        printf '%s\t%s\t%s\n' "$TS" "$name" "auth-$ERR" >> "$LOG_FILE"
+        ;;
+      *network*|*timeout*|*connect*|*DNS*)
+        echo "[NET]  $name: $MSG"
+        printf '%s\t%s\t%s\n' "$TS" "$name" "network-$ERR" >> "$LOG_FILE"
+        ;;
+      *)
+        echo "[FAIL] $name: error $ERR — $MSG"
+        printf '%s\t%s\t%s\n' "$TS" "$name" "regression-error-$ERR" >> "$LOG_FILE"
+        REGRESSION_COUNT=$((REGRESSION_COUNT + 1))
+        ;;
+    esac
+    continue
+  fi
+  echo "[ok]   $name"
+  printf '%s\t%s\t%s\n' "$TS" "$name" "ok" >> "$LOG_FILE"
+done
+
+if [ "$REGRESSION_COUNT" -gt 0 ]; then
+  echo
+  echo "$REGRESSION_COUNT MCP server(s) have regressions. Review the log:"
+  echo "  $LOG_FILE"
+  echo "Consider pinning an older Claude Code version:"
+  echo "  npm install -g @anthropic-ai/claude-code@2.1.104"
+  exit 1
+fi
+exit 0

package/examples/mcp-tool-guard.sh

@@ -1,9 +1,50 @@
 #!/bin/bash
 #
-# TRIGGER: PreToolUse  MATCHER: "Bash"
+# mcp-tool-guard.sh — Guard destructive / side-effecting MCP tool calls.
+#
+# TRIGGER: PreToolUse
+# MATCHER: ".*"   (fires on every tool; the hook self-filters to mcp__ tools.
+#                  NOTE: the previous "Bash" matcher was wrong — a Bash matcher
+#                  never sees an mcp__ tool name, so the hook never fired.)
+#
+# Why this exists: an MCP tool can perform a destructive action whose tool NAME
+#   looks harmless. The clearest case is browser automation: a model in an
+#   auto-approve mode calls e.g. mcp__playwright__browser_click on a "delete"
+#   confirmation button and removes production data with no prompt (anthropics/
+#   claude-code#65563). The tool name ("browser_click") contains no destructive
+#   word, so name-based detection alone misses it.
+#
+# CONFIG (all opt-in; defaults preserve the original warn-only behavior):
+#   CC_MCP_WARN_ALL=1            Log every MCP tool call.
+#   CC_MCP_BLOCKED_TOOLS="a,b"   Hard-block (exit 2) MCP tools matching these.
+#   CC_MCP_PROD_HOSTS="h1,h2"    Deny any MCP call whose input references these
+#                                 hosts/paths. Reliable for browser navigate
+#                                 (the target URL is in tool_input) — keeps an
+#                                 "investigation" from reaching production.
+#   CC_MCP_AUTOMATION_GUARD=off|warn|ask|block   (default: warn)
+#                                 How to treat automation tools (click/navigate/
+#                                 fill/type/...) while a permission mode is
+#                                 auto-approving. warn=stderr note; ask=prompt;
+#                                 block=exit 2. Addresses #65563's root cause.
+#   CC_MCP_AUTOMATION_TOOLS="click,navigate,fill,type,press,submit,upload"
+#                                 Tool-name substrings treated as automation.
+# Without jq, the parse below silently yields empty and this hook stops
+# guarding - with no error anywhere. Say so. We deliberately do not exit
+# here: blocking would halt every tool call, and exiting 0 would change
+# the behaviour of guards that do not depend on the parsed value.
+if ! command -v jq >/dev/null 2>&1; then
+  _nojq_warned="/tmp/cc-nojq-warned-mcp-tool-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [mcp-tool-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
 INPUT=$(cat)
 TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
 echo "$TOOL" | grep -q '^mcp__' || exit 0
+MODE=$(echo "$INPUT" | jq -r '.permission_mode // empty' 2>/dev/null)
+INPUT_BLOB=$(echo "$INPUT" | jq -r '.tool_input | tostring' 2>/dev/null)
 if [ "${CC_MCP_WARN_ALL:-0}" = "1" ]; then
     echo "NOTE: MCP tool call: $TOOL" >&2
 fi
@@ -18,6 +59,65 @@ if [ -n "$BLOCKED" ]; then
         fi
     done
 fi
+
+# Deny any MCP call that references a configured production host/path. For
+# browser navigate tools the destination URL is in tool_input, so this reliably
+# stops an "investigation" session from reaching production data.
+PROD="${CC_MCP_PROD_HOSTS:-}"
+if [ -n "$PROD" ] && [ -n "$INPUT_BLOB" ]; then
+    IFS=',' read -ra HOSTS <<< "$PROD"
+    for h in "${HOSTS[@]}"; do
+        h=$(echo "$h" | xargs)
+        [ -z "$h" ] && continue
+        if printf '%s' "$INPUT_BLOB" | grep -qiF "$h"; then
+            printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"MCP tool %s targets a production host (%s). Investigate against staging/local, not production."}}\n' "$TOOL" "$h"
+            exit 0
+        fi
+    done
+fi
+
+# #65563: while a permission mode is auto-approving, an automation tool can
+# perform a destructive UI action (e.g. clicking a delete button) that the tool
+# name does not reveal. Escalate such tools so a click cannot auto-run.
+GUARD="${CC_MCP_AUTOMATION_GUARD:-warn}"
+if [ "$GUARD" != "off" ]; then
+    case "$MODE" in
+        acceptEdits|bypassPermissions|auto|dontAsk)
+            AUTOM="${CC_MCP_AUTOMATION_TOOLS:-click,navigate,fill,type,press,submit,upload}"
+            IFS=',' read -ra ATOOLS <<< "$AUTOM"
+            for a in "${ATOOLS[@]}"; do
+                a=$(echo "$a" | xargs)
+                [ -z "$a" ] && continue
+                if [[ "$TOOL" == *"$a"* ]]; then
+                    case "$GUARD" in
+                        # VERSION NOTE (measured 2026-08-13 on 2.1.228; this
+                        # comment previously claimed the opposite): #77212
+                        # reported "ask" being silently auto-approved under
+                        # bypassPermissions — the very mode this branch fires
+                        # in. It does not reproduce on 2.1.228: interactively,
+                        # the confirmation appears under both
+                        # --dangerously-skip-permissions and
+                        # --permission-mode auto. Control: with the hook removed
+                        # both modes ran unprompted, so the mode was in effect.
+                        # Older builds may differ. Use
+                        # CC_MCP_AUTOMATION_GUARD=block when no operator is
+                        # present to answer; block is enforced in every mode.
+                        ask)
+                            printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"Confirm MCP automation action %s — permission mode %s is auto-approving."}}\n' "$TOOL" "$MODE"
+                            exit 0 ;;
+                        block)
+                            echo "BLOCKED: MCP automation tool $TOOL under auto-approve mode $MODE. Re-run in default mode so the action is confirmed." >&2
+                            exit 2 ;;
+                        *)
+                            echo "WARNING: MCP automation tool $TOOL is running under auto-approve mode $MODE — a UI action could change data without a prompt." >&2 ;;
+                    esac
+                    break
+                fi
+            done
+            ;;
+    esac
+fi
+
 case "$TOOL" in
     *delete*|*remove*|*drop*|*destroy*|*purge*)
         echo "WARNING: Potentially destructive MCP tool: $TOOL" >&2

package/examples/memory-chain-audit.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# memory-chain-audit.sh — extractMemories double-cache detector (Incident 7)
+# Why: Claude Code's extractMemories feature fires a background call at the
+#      end of each turn to update persistent memory. When the default is ON,
+#      this background call carries its own cache chain that roughly doubles
+#      the API cost per turn. Users who have not set
+#      CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 are paying for the feature silently.
+# Event: PostToolUse  MATCHER: "*"   (the extractMemories background call
+#                                     fires as a Stop-event after the turn,
+#                                     so we observe it one turn later)
+# Action: Log cumulative main-chain vs extractMemories-chain cost per session.
+#         If the ratio is consistently ≥ 1 (extractMemories costs match or
+#         exceed the main chain), the log shows the user that the feature is
+#         doubling their bill.
+#
+# Review with:
+#   awk -F'\t' '{ main+=$3; mem+=$4 } END { if (main>0) printf "main=%d mem=%d ratio=%.2f\n", main, mem, mem/main }' \
+#     ~/.claude/logs/memory-chain.log
+#
+# If the ratio is near or above 1 and you do not actively rely on auto-memory,
+# set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 in your shell rc.
+
+set -u
+
+LOG_DIR="${HOME}/.claude/logs"
+LOG_FILE="${LOG_DIR}/memory-chain.log"
+mkdir -p "$LOG_DIR" 2>/dev/null
+
+INPUT=$(cat)
+
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // "unknown"' 2>/dev/null)
+[ "$SESSION_ID" = "unknown" ] && exit 0
+
+TRANSCRIPT=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+[ -z "$TRANSCRIPT" ] && exit 0
+[ ! -r "$TRANSCRIPT" ] && exit 0
+
+# Main-chain cost = total input+output for the last assistant turn tagged
+# "main". extractMemories-chain cost = the same for the last turn tagged as
+# a memory call. Tags differ between client versions; we match on the
+# presence of "extractMemories" / "memory" in the request metadata.
+
+MAIN=$(tac "$TRANSCRIPT" 2>/dev/null \
+       | grep -m1 '"type":"assistant"' \
+       | jq -r '(.message.usage.input_tokens // 0) + (.message.usage.output_tokens // 0)' 2>/dev/null)
+
+MEM=$(grep 'extractMemor\|"memory"' "$TRANSCRIPT" 2>/dev/null | tail -1 \
+      | jq -r '(.message.usage.input_tokens // 0) + (.message.usage.output_tokens // 0)' 2>/dev/null)
+
+MAIN=${MAIN:-0}
+MEM=${MEM:-0}
+
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+printf '%s\t%s\t%s\t%s\n' "$TS" "$SESSION_ID" "$MAIN" "$MEM" >> "$LOG_FILE"
+
+exit 0

package/examples/memory-orphan-detector.sh

@@ -0,0 +1,188 @@
+#!/bin/bash
+# memory-orphan-detector.sh — Detect Claude Code memory that may have been
+# orphaned when the working directory was renamed.
+#
+# Solves: #61349 — "[BUG] Memory orphaned when working directory is renamed"
+# Filed 2026-05-22 by adamcopley.
+#
+# Claude Code stores per-project memory at
+#   ~/.claude/projects/<encoded-working-dir>/memory/
+# where <encoded-working-dir> is the absolute working directory path with
+# every `/` and `.` rewritten as `-`.
+#
+# When the operator renames or moves a working directory, Claude Code does
+# not migrate the memory. Instead, on next session start it silently creates
+# a fresh empty memory directory at the new encoded path. The old memory
+# directory remains on disk forever — orphaned, not loaded by any session,
+# with no notification to the operator. The accumulated investment (user
+# role, project conventions, validated feedback, references to external
+# systems) is effectively lost.
+#
+# This hook runs on SessionStart and emits a warning when:
+#   (a) the CURRENT working directory's memory is empty (≤ N entries), AND
+#   (b) the current working directory has substantive git history (suggesting
+#       prior work in the project that would have accumulated memory), AND
+#   (c) one or more OTHER memory directories on disk have substantive content
+#       (≥ M entries or ≥ K bytes), making them candidate orphans
+#
+# All three signals together: high likelihood of an orphaning event. The hook
+# does not block session start. It surfaces the candidate orphan directories
+# so the operator can decide whether to migrate them manually.
+#
+# Path decoding is LOSSY (a `-` in the encoded path could have originated as
+# either a `/` or a literal `-` in the working directory name). This hook
+# does NOT attempt to decode and verify path existence; it uses encoded-form
+# similarity heuristics instead.
+#
+# TRIGGER: SessionStart
+# MATCHER: ""
+#
+# CONFIGURATION (environment variables):
+#   CC_PROJECTS_DIR              default ~/.claude/projects
+#   CC_MEMORY_ORPHAN_DISABLE     set to "1" to disable
+#   CC_MEMORY_EMPTY_THRESHOLD    max entries to consider "empty" (default 1)
+#   CC_MEMORY_ORPHAN_THRESHOLD   min entries for candidate orphan (default 5)
+#   CC_MEMORY_ORPHAN_MIN_BYTES   min bytes for candidate orphan (default 2048)
+#
+# USAGE (settings.json):
+#   {
+#     "hooks": {
+#       "SessionStart": [{
+#         "matcher": "",
+#         "hooks": [{
+#           "type": "command",
+#           "command": "~/.claude/hooks/memory-orphan-detector.sh"
+#         }]
+#       }]
+#     }
+#   }
+
+set -uo pipefail
+
+[ "${CC_MEMORY_ORPHAN_DISABLE:-0}" = "1" ] && exit 0
+
+PROJECTS_DIR="${CC_PROJECTS_DIR:-$HOME/.claude/projects}"
+EMPTY_THRESHOLD="${CC_MEMORY_EMPTY_THRESHOLD:-1}"
+ORPHAN_THRESHOLD="${CC_MEMORY_ORPHAN_THRESHOLD:-5}"
+ORPHAN_MIN_BYTES="${CC_MEMORY_ORPHAN_MIN_BYTES:-2048}"
+
+[ ! -d "$PROJECTS_DIR" ] && exit 0
+
+CWD="$(pwd)"
+
+# Compute the encoded form of the current working directory.
+encode_path() {
+    # / → -, . → -
+    printf '%s' "$1" | tr '/.' '--'
+}
+CWD_ENCODED="$(encode_path "$CWD")"
+CURRENT_MEMORY_DIR="$PROJECTS_DIR/${CWD_ENCODED}/memory"
+
+# (a) Is current memory empty?
+CURRENT_COUNT=0
+if [ -d "$CURRENT_MEMORY_DIR" ]; then
+    CURRENT_COUNT=$(find "$CURRENT_MEMORY_DIR" -maxdepth 1 -type f 2>/dev/null | wc -l)
+fi
+
+# Not empty → likely fine. Exit silently.
+if [ "$CURRENT_COUNT" -gt "$EMPTY_THRESHOLD" ]; then
+    exit 0
+fi
+
+# (b) Does current working directory have git history?
+HAS_GIT_HISTORY=0
+if [ -d "$CWD/.git" ] || git -C "$CWD" rev-parse --git-dir > /dev/null 2>&1; then
+    COMMITS=$(git -C "$CWD" rev-list --count HEAD 2>/dev/null || echo 0)
+    if [ "$COMMITS" -gt 5 ]; then
+        HAS_GIT_HISTORY=1
+    fi
+fi
+
+# No git history → not a strong signal of prior work. Exit silently.
+if [ "$HAS_GIT_HISTORY" -eq 0 ]; then
+    exit 0
+fi
+
+# (c) Find candidate orphans: other memory directories with content.
+ORPHAN_CANDIDATES=()
+for d in "$PROJECTS_DIR"/*/; do
+    [ -d "$d" ] || continue
+    base="${d%/}"
+    base="${base##*/}"
+    # Skip current
+    if [ "$base" = "$CWD_ENCODED" ]; then continue; fi
+    mem_dir="$d/memory"
+    [ ! -d "$mem_dir" ] && continue
+    cnt=$(find "$mem_dir" -maxdepth 1 -type f 2>/dev/null | wc -l)
+    bytes=$(du -sb "$mem_dir" 2>/dev/null | awk '{print $1}')
+    bytes="${bytes:-0}"
+    if [ "$cnt" -ge "$ORPHAN_THRESHOLD" ] && [ "$bytes" -ge "$ORPHAN_MIN_BYTES" ]; then
+        # Compute encoded-form similarity: shared prefix length / longer length
+        # (very rough — but better than nothing without lossless decode)
+        ORPHAN_CANDIDATES+=("$base|$cnt|$bytes")
+    fi
+done
+
+# No candidate orphans → nothing to report.
+if [ "${#ORPHAN_CANDIDATES[@]}" -eq 0 ]; then
+    exit 0
+fi
+
+# Limit output to top 5 candidates, sorted by byte size descending.
+TOP=()
+while IFS= read -r line; do
+    TOP+=("$line")
+done < <(printf '%s\n' "${ORPHAN_CANDIDATES[@]}" | sort -t'|' -k3 -rn | head -5)
+
+EXTRA=$(( ${#ORPHAN_CANDIDATES[@]} - ${#TOP[@]} ))
+
+cat >&2 <<EOF
+<system-reminder>
+POSSIBLE MEMORY ORPHANING DETECTED — the current working directory's memory
+is empty, but this project has substantive git history AND there are other
+memory directories on disk with non-trivial content. One of them may be the
+prior version of this project's memory that was orphaned by a directory
+rename, move, or symlink change.
+
+This is the failure mode documented in anthropics/claude-code#61349. Claude
+Code derives memory location from the encoded working-directory path
+(everything in / and . becomes -). Renaming the directory produces a
+different encoded form, so a fresh empty memory directory is created at
+the new path while the old memory stays on disk, unreferenced.
+
+Current working directory: $CWD
+Encoded form:              $CWD_ENCODED
+Current memory:            $CURRENT_COUNT file(s) at $CURRENT_MEMORY_DIR
+
+Candidate orphan memory directories (top 5 by size):
+EOF
+for entry in "${TOP[@]}"; do
+    IFS='|' read -r b c bytes <<< "$entry"
+    # Print bytes in KB for readability
+    kb=$(( bytes / 1024 ))
+    echo "  $PROJECTS_DIR/$b/memory/  ($c files, ${kb}KB)" >&2
+done
+if [ "$EXTRA" -gt 0 ]; then
+    echo "  ... and $EXTRA more" >&2
+fi
+cat >&2 <<EOF
+
+Recommended next actions for the operator (NOT for the model to perform
+automatically):
+  1. Inspect the candidate directories. The encoded path is the original
+     working directory's absolute path with every / and . replaced by -.
+     Note that this encoding is LOSSY — a - in the encoded form could be a
+     literal - or a / in the original path. Decode by trying both.
+  2. If you recognize an orphan that corresponds to a previous location of
+     this project (before a rename/move), copy its memory files into the
+     current memory directory: cp -r <orphan>/memory/* $CURRENT_MEMORY_DIR/
+  3. To prevent future orphaning, version-control the memory directory:
+     store memory in the project's git tree (e.g., .claude-memory/) and
+     symlink the system memory directory to it. Renames preserve the link.
+
+To disable this detector, set CC_MEMORY_ORPHAN_DISABLE=1.
+</system-reminder>
+EOF
+
+# Exit 0 — detection-only.
+exit 0