cc-safe-setup 29.8.0 → 30.0.5

package/examples/mcp-misdiagnosis-arrest.sh

@@ -0,0 +1,209 @@
+#!/bin/bash
+# mcp-misdiagnosis-arrest.sh — Catch the assistant misdiagnosing a silently-
+# dropped MCP connector as "the connector isn't installed", and surface the
+# actual recovery path before the operator wastes a reinstall round-trip.
+#
+# Solves: #60428 ("Slack MCP tools silently deactivate mid-session ~1h
+# uptime; claude mcp list still reports Connected").
+#
+# In that case, an installed MCP connector (Slack, in the reported instance)
+# silently drops out of the model's deferred-tool registry after ~1 hour of
+# uptime. The model then attempts a tool call, gets a missing-tool result,
+# and — guided by current docs/skill prompts — frequently suggests the
+# operator "install the Connector" as the remediation. The reporter
+# documents this as the secondary issue:
+#
+#   "That's wrong: the Connector *is* already installed, it was working in
+#    this session, and the suggestion sends users on a 30-second wild goose
+#    chase before they realize the real fix is restart / new chat /
+#    plugin toggle."
+#
+# The actual recovery path the reporter verified (2026-05-19):
+#
+#   1. Open a new chat in the same Claude Code window (re-binds tools in the
+#      original session without losing context).
+#   2. Toggle the Connector's Plugin off → on in Customize → Personal plugins.
+#   3. Restart Claude Code (loses session).
+#   4. /clear (nukes context — not a real fix).
+#
+# What does NOT restore the tools: /mcp, /compact, /resume, /config, waiting.
+#
+# This hook runs on Stop, scans the assistant's most recent turn for
+# misdiagnosis patterns ("you need to install the X Connector", "the X
+# Plugin isn't installed", "the MCP server seems missing"), cross-references
+# against ~/.claude/settings.json to confirm the named connector IS
+# installed, and — if so — emits an advisory with the correct recovery path.
+#
+# Advisory-default (exit 0 + stderr). Strict mode (exit 2) is opt-in via
+# CC_MCP_MISDIAGNOSIS_MODE=strict.
+#
+# Related Issues:
+#   #60428 — Slack MCP tools silently deactivate (the primary)
+#
+# TRIGGER: Stop
+# MATCHER: ""
+#
+# CONFIGURATION (environment variables):
+#   CC_MCP_MISDIAGNOSIS_MODE       "strict" → exit 2 when misdiagnosis is
+#                                  detected against an installed connector.
+#                                  Default: advisory (exit 0).
+#   CC_MCP_MISDIAGNOSIS_DISABLE    "1" → skip the gate entirely.
+#   CC_MCP_SETTINGS_PATH           Override the settings.json path used to
+#                                  confirm connector installation. Default:
+#                                  ~/.claude/settings.json. Tests use this
+#                                  to point at a fixture file.
+#
+# USAGE (settings.json):
+#   {
+#     "hooks": {
+#       "Stop": [{
+#         "matcher": "",
+#         "hooks": [{
+#           "type": "command",
+#           "command": "~/.claude/hooks/mcp-misdiagnosis-arrest.sh"
+#         }]
+#       }]
+#     }
+#   }
+
+set -uo pipefail
+
+# 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-misdiagnosis-arrest-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [mcp-misdiagnosis-arrest]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+[ "${CC_MCP_MISDIAGNOSIS_DISABLE:-0}" = "1" ] && exit 0
+
+INPUT=$(cat 2>/dev/null || true)
+[ -z "$INPUT" ] && exit 0
+
+SETTINGS_PATH="${CC_MCP_SETTINGS_PATH:-$HOME/.claude/settings.json}"
+
+# Extract the assistant's last message text. Stop-hook input shape varies
+# across Claude Code versions; try several keys (matching the precedent set
+# in closure-word-verify-gate.sh).
+ASSISTANT_TEXT=$(printf '%s' "$INPUT" | jq -r '
+    .transcript[-1].content //
+    .last_assistant_message //
+    .stop_input.assistant_text //
+    .assistant_message //
+    empty
+' 2>/dev/null)
+
+[ -z "$ASSISTANT_TEXT" ] && exit 0
+
+# Misdiagnosis patterns. The shape we want to catch is:
+#   "<thing> Connector/Plugin/MCP server isn't installed / needs to be
+#    installed / is missing / not configured"
+# We intentionally over-match a little; the false-positive cost is a
+# stderr advisory, the false-negative cost is the operator on a reinstall
+# wild goose chase.
+MISDIAG_PATTERN='(([Cc]onnector|[Pp]lugin|[Mm]CP[[:space:]]+[Ss]erver)[[:space:]]+(isn'\''t|is[[:space:]]+not|needs[[:space:]]+to[[:space:]]+be|appears[[:space:]]+to[[:space:]]+be|seems[[:space:]]+to[[:space:]]+be|is)[[:space:]]+(installed|configured|missing|unavailable|set[[:space:]]+up)|need[[:space:]]+to[[:space:]]+install[[:space:]]+the[[:space:]]+[A-Za-z][A-Za-z0-9_-]*[[:space:]]+(Connector|Plugin)|install[[:space:]]+the[[:space:]]+[A-Za-z][A-Za-z0-9_-]*[[:space:]]+(Connector|Plugin)[[:space:]]+(first|to[[:space:]]+use|before)|[Mm]CP[[:space:]]+(tool|tools)[[:space:]]+(are|aren'\''t|is|isn'\''t)[[:space:]]+(missing|unavailable|registered|available))'
+
+if ! printf '%s' "$ASSISTANT_TEXT" | grep -Eq "$MISDIAG_PATTERN"; then
+    exit 0
+fi
+
+# Misdiagnosis language matched. Now check: is any MCP connector / plugin
+# actually installed? If yes, the misdiagnosis is wrong and we should warn.
+# If no installed connectors, the assistant's "isn't installed" claim might
+# be correct — stay silent rather than false-positive.
+
+if [ ! -r "$SETTINGS_PATH" ]; then
+    # No readable settings to confirm against — refuse to false-positive.
+    exit 0
+fi
+
+# Look for any of:
+#   * an enabledPlugins entry like "slack@claude-plugins-official": true
+#   * an mcpServers entry (any key under .mcpServers)
+#   * a plugins block with any entry
+INSTALLED_CONNECTORS=$(jq -r '
+    [
+      (.enabledPlugins // {} | to_entries | map(select(.value == true) | .key)),
+      (.mcpServers // {} | keys),
+      (.plugins // {} | keys)
+    ] | add | unique | .[]
+' "$SETTINGS_PATH" 2>/dev/null)
+
+if [ -z "$INSTALLED_CONNECTORS" ]; then
+    # Nothing installed → assistant's "isn't installed" may be correct.
+    exit 0
+fi
+
+# Try to extract the specific connector name the assistant referenced, so
+# we can match it against the installed set (most precise warning). If we
+# cannot extract a name, we still warn — any installed connector means the
+# generic "you need to install one" advice is at least partly wrong.
+NAMED_CONNECTOR=$(printf '%s' "$ASSISTANT_TEXT" \
+    | grep -Eio '(install[[:space:]]+the[[:space:]]+)?[A-Za-z][A-Za-z0-9_-]*[[:space:]]+(Connector|Plugin|MCP[[:space:]]+Server)' \
+    | head -1 \
+    | sed -E 's/^install[[:space:]]+the[[:space:]]+//I; s/[[:space:]]+(Connector|Plugin|MCP[[:space:]]+Server)$//I')
+
+NAMED_MATCH=""
+if [ -n "$NAMED_CONNECTOR" ]; then
+    # Case-insensitive substring match against installed connector keys.
+    NAMED_LOWER=$(printf '%s' "$NAMED_CONNECTOR" | tr '[:upper:]' '[:lower:]')
+    while IFS= read -r installed; do
+        installed_lower=$(printf '%s' "$installed" | tr '[:upper:]' '[:lower:]')
+        if printf '%s' "$installed_lower" | grep -Fq "$NAMED_LOWER"; then
+            NAMED_MATCH="$installed"
+            break
+        fi
+    done <<EOF
+$INSTALLED_CONNECTORS
+EOF
+fi
+
+# Build advisory.
+{
+    echo "<system-reminder>"
+    echo "MCP MISDIAGNOSIS LIKELY — the assistant's last turn suggested an MCP"
+    echo "connector/plugin needs to be installed, but the operator's settings"
+    echo "already show installed MCP connectors:"
+    echo ""
+    printf '%s\n' "$INSTALLED_CONNECTORS" | sed 's/^/  - /'
+    echo ""
+    if [ -n "$NAMED_MATCH" ]; then
+        echo "Specifically, '$NAMED_MATCH' is already installed and configured."
+    elif [ -n "$NAMED_CONNECTOR" ]; then
+        echo "The named connector '$NAMED_CONNECTOR' was not found in settings,"
+        echo "but other connectors are installed — double-check the name before"
+        echo "recommending a reinstall."
+    fi
+    echo ""
+    echo "Known pattern (#60428): MCP connectors can silently drop out of the"
+    echo "session's deferred-tool registry after ~1h uptime while 'claude mcp"
+    echo "list' continues to report 'Connected'. The model then misdiagnoses"
+    echo "this as missing installation."
+    echo ""
+    echo "Actual recovery path (verified 2026-05-19):"
+    echo "  1. Open a new chat in the same Claude Code window."
+    echo "     (Re-binds tools in the original session without losing context.)"
+    echo "  2. Toggle the connector's Plugin off → on in Customize → Personal"
+    echo "     plugins."
+    echo "  3. Restart Claude Code (loses session)."
+    echo ""
+    echo "What does NOT restore them: /mcp, /compact, /resume, /config, waiting,"
+    echo "or reinstalling the connector."
+    echo ""
+    echo "Before sending the assistant's last turn to the operator, replace the"
+    echo "installation advice with the recovery steps above."
+    echo ""
+    echo "To disable this gate (for genuinely uninstalled-connector flows),"
+    echo "set CC_MCP_MISDIAGNOSIS_DISABLE=1 in your environment."
+    echo "</system-reminder>"
+} >&2
+
+if [ "${CC_MCP_MISDIAGNOSIS_MODE:-advisory}" = "strict" ]; then
+    exit 2
+fi
+exit 0

package/examples/mcp-orphan-leak-warner.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# mcp-orphan-leak-warner.sh — At session start, warn if leaked MCP / sub-agent
+#   server processes from earlier sessions are still alive and piling up, before
+#   they exhaust RAM/swap into an OOM / kernel panic.
+#
+# Solves a recurring May–June 2026 class (anthropics/claude-code #64366, #68647,
+# #66020, #68933, #61748, …): MCP servers and sub-agent children outlive the
+# session that spawned them — reparented to PID 1 — and accumulate until the box
+# swaps to death or kernel-panics. This is *process/memory* exhaustion, distinct
+# from MCP token/context bloat. The actionable moment is the start of your NEXT
+# session, before you spawn more.
+#
+# Precision: ADVISORY ONLY. This hook never kills anything. Being reparented to
+# PID 1 is not sufficient to call a process an orphan (legitimate daemons are
+# PID-1-parented too), so it flags a process ONLY when it is BOTH (a) reparented
+# to PID 1 AND (b) matches an MCP/agent-server command signature, and even then
+# it only *reports*. You decide what to reap. It also stays silent unless the
+# leak is real (>= MIN_COUNT orphans), to avoid nagging.
+#
+# TRIGGER: SessionStart
+
+MIN_COUNT=${CC_MCP_ORPHAN_MIN_COUNT:-3}   # warn only at/above this many orphans
+MIN_AGE=${CC_MCP_ORPHAN_MIN_AGE:-300}     # seconds; ignore freshly-started servers
+
+# MCP / agent-server signatures: how Claude Code spawns MCP servers (npx/uvx
+# launchers, @modelcontextprotocol packages, *mcp-server* binaries). Tuned to
+# avoid matching editors, shells, or your own long-running daemons.
+SIG='@modelcontextprotocol|mcp-server-|modelcontextprotocol|[/ ]mcp([ _-]|$)|uvx[^|]*mcp|npx[^|]*mcp'
+
+read -r COUNT TOTAL_KB < <(ps -eo ppid=,etimes=,rss=,args= 2>/dev/null \
+  | awk -v sig="$SIG" -v minage="$MIN_AGE" '
+      $1==1 && $2>=minage {
+        args=""; for(i=4;i<=NF;i++) args=args (i>4?" ":"") $i
+        if (args ~ sig) { c++; kb+=$3 }
+      }
+      END { print c+0, kb+0 }')
+
+[ "${COUNT:-0}" -lt "$MIN_COUNT" ] && exit 0
+
+{
+  echo "NOTE: $COUNT leaked MCP / sub-agent server process(es) from earlier sessions"
+  echo "are still alive (~$((TOTAL_KB/1024)) MB resident, reparented to PID 1). Left to"
+  echo "pile up these can exhaust RAM/swap into an OOM or kernel panic (#64366, #68647)."
+  echo "Review them:    ps -o pid,etimes,rss,args -p \$(pgrep -f 'mcp-server-|@modelcontextprotocol')"
+  echo "Reap safely:    kill the ones you recognize as dead-session leftovers."
+  echo "Prevent a panic: cap memory for heavy sessions:  ( ulimit -v 8000000; claude )"
+} >&2
+
+exit 0

package/examples/mcp-permissions-ask-warner.sh

@@ -0,0 +1,151 @@
+#!/bin/bash
+# mcp-permissions-ask-warner.sh — Warn when permissions.ask has MCP entries
+#
+# Solves: github.com/anthropics/claude-code/issues/58289
+#         "permissions.ask is ignored for MCP tools in default mode"
+#
+#         Reporter (2026-05-13, Claude Code 2.1.139 + Bedrock): MCP tool
+#         entries in the `permissions.ask` array of `~/.claude/settings.json`
+#         do not trigger a confirmation prompt. The MCP tool call executes
+#         immediately, the same as if the entry were in `allow`. The user's
+#         intent ("ask before running this MCP tool") diverges from the
+#         system's behavior ("run without asking") with no visible signal.
+#
+# WHY THIS MATTERS:
+#   permissions.ask is the gating mechanism users rely on to keep a human
+#   in the loop for sensitive MCP tools (database writes, deployment, file
+#   delete, payment). If this gating is silently bypassed, sensitive MCP
+#   tools fire without the user's review. This is a textbook claim-verify
+#   gap: the user believes "this is gated" while the system has already
+#   run the tool. Worse, the MCP surface is where many irreversible
+#   operations live (cloud resource changes, payment processing, message
+#   sending).
+#
+# TRIGGER: SessionStart  MATCHER: ""
+#
+# HOW IT WORKS:
+#   At session start:
+#     1. Find the relevant settings.json files.
+#        Default order: ~/.claude/settings.json, then $CLAUDE_PROJECT_DIR/.claude/settings.json
+#     2. For each file, parse the permissions.ask array.
+#     3. Filter entries to MCP tools (starting with "mcp__").
+#     4. If any MCP entries are found, emit a clear warning listing them,
+#        explaining the known bypass, and suggesting two workarounds:
+#          (a) Move sensitive MCP entries from permissions.ask to permissions.deny
+#              (deny still works correctly per the reporter)
+#          (b) Use `--permission-mode plan` mode for the session if MCP-heavy
+#
+# CONFIGURATION:
+#   CC_MCP_ASK_DISABLE=1     — disable the hook entirely
+#   CC_MCP_ASK_ACTION        — "warn" (default) or "block" (exit 2)
+#   CC_MCP_ASK_LOG           — log file path (default /tmp/cc-mcp-ask.log)
+#   CC_MCP_ASK_FILES         — comma-separated settings.json paths to scan
+#                              (default: $HOME/.claude/settings.json plus
+#                              $CLAUDE_PROJECT_DIR/.claude/settings.json)
+#
+# Usage:
+# {
+#   "hooks": {
+#     "SessionStart": [{
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/mcp-permissions-ask-warner.sh" }]
+#     }]
+#   }
+# }
+
+if [ "${CC_MCP_ASK_DISABLE:-0}" = "1" ]; then
+  exit 0
+fi
+
+# 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-permissions-ask-warner-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [mcp-permissions-ask-warner]: jq not found - this hook cannot read your settings files and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+ACTION="${CC_MCP_ASK_ACTION:-warn}"
+LOG_FILE="${CC_MCP_ASK_LOG:-/tmp/cc-mcp-ask.log}"
+
+# Determine which settings.json files to scan
+if [ -n "$CC_MCP_ASK_FILES" ]; then
+  IFS=',' read -ra FILES <<< "$CC_MCP_ASK_FILES"
+else
+  FILES=()
+  [ -f "$HOME/.claude/settings.json" ] && FILES+=("$HOME/.claude/settings.json")
+  if [ -n "$CLAUDE_PROJECT_DIR" ] && [ -f "$CLAUDE_PROJECT_DIR/.claude/settings.json" ]; then
+    FILES+=("$CLAUDE_PROJECT_DIR/.claude/settings.json")
+  fi
+fi
+
+# Collect MCP entries across all files
+MCP_ENTRIES=()
+SOURCE_FILES=()
+
+for f in "${FILES[@]}"; do
+  f=$(echo "$f" | xargs)  # trim
+  [ -z "$f" ] && continue
+  [ ! -f "$f" ] && continue
+  # Extract permissions.ask entries that look like MCP tools
+  ENTRIES=$(jq -r '
+    (.permissions.ask // [])
+    | map(select(type == "string" and startswith("mcp__")))
+    | .[]
+  ' "$f" 2>/dev/null)
+  if [ -n "$ENTRIES" ]; then
+    while IFS= read -r entry; do
+      [ -z "$entry" ] && continue
+      MCP_ENTRIES+=("$entry")
+      SOURCE_FILES+=("$f")
+    done <<< "$ENTRIES"
+  fi
+done
+
+# No MCP ask entries → silent pass
+if [ ${#MCP_ENTRIES[@]} -eq 0 ]; then
+  exit 0
+fi
+
+# Log + emit
+TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
+for i in "${!MCP_ENTRIES[@]}"; do
+  echo "[$TIMESTAMP] mcp_in_ask entry=${MCP_ENTRIES[$i]} source=${SOURCE_FILES[$i]} action=$ACTION" >> "$LOG_FILE"
+done
+
+MSG="⚠️  permissions.ask contains MCP tool entries that may be silently bypassed"
+MSG+=$'\n'
+MSG+=$'\n'"  Affected entries:"
+for i in "${!MCP_ENTRIES[@]}"; do
+  MSG+=$'\n'"    - ${MCP_ENTRIES[$i]}  (in ${SOURCE_FILES[$i]})"
+done
+MSG+=$'\n'
+MSG+=$'\n'"  Known bug: github.com/anthropics/claude-code/issues/58289"
+MSG+=$'\n'"  In Claude Code 2.1.139 (and possibly other versions), permissions.ask"
+MSG+=$'\n'"  entries for MCP tools (names starting with mcp__) do not trigger a"
+MSG+=$'\n'"  confirmation prompt in default mode. The tool executes immediately,"
+MSG+=$'\n'"  as if it were in permissions.allow. Reported on Bedrock (us.anthropic."
+MSG+=$'\n'"  claude-opus-4-7), likely also affects other providers."
+MSG+=$'\n'
+MSG+=$'\n'"  Workarounds (pick one):"
+MSG+=$'\n'"    1. Move the listed entries from permissions.ask to permissions.deny."
+MSG+=$'\n'"       deny still gates correctly per the bug report. The tool will be"
+MSG+=$'\n'"       refused outright; you can override case-by-case in the chat."
+MSG+=$'\n'"    2. Run the session with --permission-mode plan, which forces an"
+MSG+=$'\n'"       explicit plan-approval step before any tool execution."
+MSG+=$'\n'"    3. Remove the entry from permissions.ask if the tool is acceptable"
+MSG+=$'\n'"       to run without confirmation."
+MSG+=$'\n'
+MSG+=$'\n'"  This warning fires once per session start. To silence it after you've"
+MSG+=$'\n'"  adopted a workaround, set CC_MCP_ASK_DISABLE=1 in your environment."
+
+if [ "$ACTION" = "block" ]; then
+  printf '%s\n' "$MSG" >&2
+  exit 2
+else
+  printf '%s\n' "$MSG" >&2
+  exit 0
+fi

package/examples/mcp-routine-approval-detector.sh

@@ -0,0 +1,154 @@
+#!/bin/bash
+# mcp-routine-approval-detector.sh — Surface the May 2026 routine-approval cluster
+#
+# PROBLEM (cluster, active since ~2026-05-20):
+#   Scheduled and Remote Claude.ai Routines silently fail every MCP tool call
+#   on Anthropic-hosted connectors (Gmail, Calendar, Microsoft 365, Notion,
+#   Slack, Datadog, Atlassian, Snowflake, Linear, Granola) with:
+#
+#     Streamable HTTP error: Error POSTing to endpoint:
+#     MCP tool call requires approval
+#
+#   Cluster anchors: #61015 (52r/40c), #61027 (33r/18c), #61097 (6r/11c,
+#   has architectural fix proposal), #61044 (3r/3c, open).
+#
+#   The routine has no UI surface to approve the prompt, so the call becomes
+#   a permanent no-op. Custom user-registered MCP servers work fine in the
+#   same routine — the bug is scoped to the CCR proxy's approval gate.
+#
+# HOW THIS HELPS:
+#   PostToolUse hook on mcp__* matcher. Reads tool_result. If the error
+#   string matches the cluster signature, writes a structured diagnostic
+#   receipt under ~/.claude/state/mcp-routine-approval-blocks/ and emits
+#   a stderr warning so the operator sees the silent failure.
+#
+#   The hook does NOT block the failure — the call has already failed on
+#   the server side. The hook surfaces it.
+#
+# RECEIPT FORMAT (one JSON file per block):
+#   {
+#     "blocked_at": "2026-05-25T12:00:00Z",
+#     "tool_name": "mcp__claude_ai_Gmail__search_threads",
+#     "server": "claude_ai_Gmail",
+#     "operation": "search_threads",
+#     "session_id": "<from input>",
+#     "error_excerpt": "Streamable HTTP error: ..."
+#   }
+#
+# CONFIG (all optional):
+#   CC_MCP_ROUTINE_BLOCK_DIR        receipt directory (default: ~/.claude/state/mcp-routine-approval-blocks)
+#   CC_MCP_ROUTINE_BLOCK_DISABLE=1  skip the hook entirely
+#   CC_MCP_ROUTINE_BLOCK_WEBHOOK    if set to a URL, POST a JSON body on each block
+#   CC_MCP_ROUTINE_BLOCK_QUIET=1    suppress the stderr warning (still writes receipt)
+#
+# TRIGGER: PostToolUse
+# MATCHER: mcp__.*
+#
+# OPERATOR NEXT STEPS (printed in stderr warning):
+#   - Confirm cluster signature via the Fallback Architecture Gist:
+#     https://gist.github.com/yurukusa/7ed7176a8e79ea4635995d717b9af703
+#   - Subscribe to the open anchor for the fix-landed signal:
+#     https://github.com/anthropics/claude-code/issues/61044
+#   - Aggregate receipts to see how many blocks happened today:
+#     find ~/.claude/state/mcp-routine-approval-blocks -mtime -1 | wc -l
+
+set -u
+
+[ "${CC_MCP_ROUTINE_BLOCK_DISABLE:-0}" = "1" ] && exit 0
+
+INPUT=$(cat)
+
+# Need jq for structured field extraction; silent skip if missing
+if ! command -v jq >/dev/null 2>&1; then
+    exit 0
+fi
+
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+[ -z "$TOOL" ] && exit 0
+
+# Only inspect MCP tool calls
+case "$TOOL" in
+    mcp__*) ;;
+    *) exit 0 ;;
+esac
+
+# Extract the tool result text (could be string or structured)
+RESULT_TEXT=$(printf '%s' "$INPUT" | jq -r '
+    .tool_result // .tool_response // "" |
+    if type == "string" then .
+    elif type == "object" then (.content // .text // .error // "" | tostring)
+    elif type == "array" then map(tostring) | join(" ")
+    else tostring end
+' 2>/dev/null)
+
+[ -z "$RESULT_TEXT" ] && exit 0
+
+# Cluster signature: the exact error string the four anchor issues report
+SIG_PRIMARY="MCP tool call requires approval"
+SIG_SECONDARY="Streamable HTTP error"
+
+# Both signatures present = high-confidence cluster match
+if ! printf '%s' "$RESULT_TEXT" | grep -qF "$SIG_PRIMARY"; then
+    exit 0
+fi
+
+# At this point we have a confirmed cluster hit. Write a receipt.
+RECEIPT_DIR="${CC_MCP_ROUTINE_BLOCK_DIR:-${HOME}/.claude/state/mcp-routine-approval-blocks}"
+if ! mkdir -p "$RECEIPT_DIR" 2>/dev/null; then
+    # State dir not writable — silent skip per the existing-hook convention
+    exit 0
+fi
+
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Server / operation extraction. Tool names look like mcp__<server>__<operation>
+# where server can itself contain underscores (e.g. claude_ai_Gmail).
+# The separator is the double underscore __, not a single _.
+TOOL_REST="${TOOL#mcp__}"
+SERVER="${TOOL_REST%%__*}"
+OPERATION="${TOOL_REST#*__}"
+
+# Truncate error excerpt to keep receipt files small
+ERROR_EXCERPT=$(printf '%s' "$RESULT_TEXT" | head -c 400)
+
+# Receipt filename: timestamp + tool + short hash of error
+SAFE_TOOL=$(printf '%s' "$TOOL" | tr -c 'A-Za-z0-9_-' '_')
+RECEIPT_NAME="${TIMESTAMP//:/-}-${SAFE_TOOL}.json"
+RECEIPT_PATH="${RECEIPT_DIR}/${RECEIPT_NAME}"
+
+if jq -nc \
+    --arg ts "$TIMESTAMP" \
+    --arg tool "$TOOL" \
+    --arg server "$SERVER" \
+    --arg op "$OPERATION" \
+    --arg sid "$SESSION_ID" \
+    --arg err "$ERROR_EXCERPT" \
+    '{blocked_at: $ts, tool_name: $tool, server: $server, operation: $op, session_id: $sid, error_excerpt: $err}' \
+    > "$RECEIPT_PATH" 2>/dev/null; then
+    :
+else
+    # Receipt write failed — silent skip
+    exit 0
+fi
+
+# Optional webhook
+if [ -n "${CC_MCP_ROUTINE_BLOCK_WEBHOOK:-}" ] && command -v curl >/dev/null 2>&1; then
+    curl -s --max-time 5 -X POST \
+        -H "Content-Type: application/json" \
+        --data-binary "@${RECEIPT_PATH}" \
+        "$CC_MCP_ROUTINE_BLOCK_WEBHOOK" >/dev/null 2>&1 || true
+fi
+
+# Stderr warning unless quiet
+if [ "${CC_MCP_ROUTINE_BLOCK_QUIET:-0}" != "1" ]; then
+    cat >&2 <<EOF
+mcp-routine-approval-detector: silent failure detected on $TOOL
+  → cluster: #61015 / #61027 / #61097 / #61044 (May 2026 routine-approval regression)
+  → receipt: $RECEIPT_PATH
+  → fallback architecture: https://gist.github.com/yurukusa/7ed7176a8e79ea4635995d717b9af703
+  → fix-landed signal: https://github.com/anthropics/claude-code/issues/61044
+EOF
+fi
+
+exit 0

package/examples/mcp-server-allowlist.sh

@@ -16,6 +16,18 @@
 
 set -euo pipefail
 
+# 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-server-allowlist-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [mcp-server-allowlist]: 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)
 [ -z "$TOOL" ] && exit 0

package/examples/mcp-server-guard.sh

@@ -23,6 +23,18 @@
 #   }
 # }
 
+# 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-server-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [mcp-server-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)