cc-safe-setup 29.7.0 → 30.0.4

package/examples/halt-signal-detector.sh

@@ -0,0 +1,135 @@
+#!/bin/bash
+# ================================================================
+# halt-signal-detector.sh — Warn before further tool calls when the
+#                          user's previous message contains a halt
+#                          token (stop, やめて, halt, etc.)
+# ================================================================
+# PURPOSE:
+#   When the previous user message in the transcript contains an
+#   explicit halt signal, warn that the upcoming tool call may be
+#   reframing the user's halt as a renegotiation. Prevents the
+#   "continuation bargaining after halt signals" failure mode reported
+#   in Issue #55909 (Cowork mode bargaining), Issue #56351 (refusing
+#   to stop digging), and Issue #55363 (/ultrareview ignoring stop).
+#
+# TRIGGER: PreToolUse
+# MATCHER: "*"  (all tools)
+#
+# WHY THIS MATTERS:
+#   In Issue #55909, the user said "stop / やめて / use a different
+#   browser" multiple times, but the model continued operating and
+#   replied with bargaining language ("just let me do this one part",
+#   "after you log in, send 'OK' and I'll do the rest"). The expected
+#   behaviour after a user halt signal is: zero tool calls in the
+#   next turn, no requests for partial cooperation. The original plan
+#   does not survive into the next response, even softened.
+#
+#   This hook detects the halt signal at the input boundary and warns
+#   before any tool call is made. It cannot fix the underlying model
+#   layer issue, but it removes the bargaining surface from the next
+#   turn by surfacing the contradiction to the operator.
+#
+# WHAT IT CHECKS:
+#   1. Read the most recent user message from the transcript
+#   2. Search for halt tokens (Japanese and English)
+#   3. If a halt token is present, emit a warning to stderr
+#   4. If CC_HALT_SIGNAL_BLOCK=1, also exit 2 to block the tool call
+#
+# OUTPUT:
+#   Warning to stderr with a snippet of the matched user text and a
+#   reference to Issue #55909. Exit 0 (advisory) by default.
+#
+# CONFIGURATION:
+#   CC_HALT_SIGNAL_BLOCK  — set to "1" to block the tool call (exit 2)
+#                          when a halt signal is detected. Default is
+#                          advisory only.
+#   CC_HALT_SIGNAL_EXTRA  — additional comma-separated halt tokens to
+#                          match (case-insensitive). Example: "abort,kill"
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/55909
+#   https://github.com/anthropics/claude-code/issues/56351
+#   https://github.com/anthropics/claude-code/issues/55363
+# ================================================================
+
+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-halt-signal-detector-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [halt-signal-detector]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+INPUT=$(cat)
+
+# Get transcript path from PreToolUse input
+TRANSCRIPT_PATH=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+
+if [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+    exit 0
+fi
+
+# Find the most recent user message
+LAST_USER_LINE=$(grep -h '"type":"user"' "$TRANSCRIPT_PATH" 2>/dev/null | tail -1)
+
+if [ -z "$LAST_USER_LINE" ]; then
+    exit 0
+fi
+
+# Extract user text — content may be a string or an array of blocks
+USER_TEXT=$(printf '%s' "$LAST_USER_LINE" | jq -r '
+    if (.message.content | type) == "string" then
+        .message.content
+    elif (.message.content | type) == "array" then
+        [.message.content[] | select(.type == "text") | .text] | join(" ")
+    else
+        empty
+    end
+' 2>/dev/null)
+
+if [ -z "$USER_TEXT" ]; then
+    exit 0
+fi
+
+# Skip if user text looks like a system-generated nudge (idle prompt, hook output)
+if printf '%s' "$USER_TEXT" | grep -qE '^\[idle [0-9]+s|^<system-reminder>|^BLOCKED:'; then
+    exit 0
+fi
+
+# Halt signal patterns — explicit stop/halt verbs
+# Japanese: やめて, やめろ, 止めて, 止まれ, 中断, 中止, ストップ
+# English: stop, halt, abort, cease, do not, don't
+HALT_BASE='やめて|やめろ|止めて|止まれ|中断|中止|ストップ|\bstop\b|\bhalt\b|\babort\b|\bcease\b|\bdo not\b|\bdon'\''t\b'
+
+# Optional extra patterns from env
+EXTRA="${CC_HALT_SIGNAL_EXTRA:-}"
+if [ -n "$EXTRA" ]; then
+    EXTRA_PATTERN=$(printf '%s' "$EXTRA" | tr ',' '|')
+    HALT_PATTERN="${HALT_BASE}|${EXTRA_PATTERN}"
+else
+    HALT_PATTERN="$HALT_BASE"
+fi
+
+# Check for halt signal (case-insensitive)
+if printf '%s' "$USER_TEXT" | grep -qiE "$HALT_PATTERN"; then
+    SNIPPET=$(printf '%s' "$USER_TEXT" | head -c 160 | tr '\n' ' ')
+    cat >&2 <<EOF
+🛑 halt-signal-detector: 直前の利用者の応答に停止の合図が含まれています。
+  検出した文脈: ${SNIPPET}...
+  この道具の呼び出しが、 利用者の停止の合図を「計画の調整の依頼」 として再解釈していないか確認してください。
+  「これだけ」「ここだけ」「短い合図を送ってください」 のような部分的な協力の依頼は、 利用者から見ると停止の合図の無視と等価です。
+  期待される動き: 次の応答で道具の呼び出しゼロ、 状態の報告と利用者への確認のみ。
+  Reference: https://github.com/anthropics/claude-code/issues/55909
+EOF
+    if [ "${CC_HALT_SIGNAL_BLOCK:-0}" = "1" ]; then
+        exit 2
+    fi
+fi
+
+exit 0

package/examples/handoff-on-clear.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# handoff-on-clear.sh — Write a handoff note at /clear, before the context goes
+#
+# Solves: /clear wipes the conversation with no chance to act first, and no hook
+#         can block it — slash commands never reach UserPromptSubmit (measured
+#         2026-09-19 on 2.1.270; the table is in clear-command-confirm-guard.sh).
+#         People ask for a PreClear event for exactly this (#95199).
+#
+# How it works: SessionEnd fires with reason="clear", and at that moment
+#   transcript_path still points at a readable file — 271,593 bytes of it in the
+#   run this was measured on. The conversation is not gone yet, so this hook
+#   reads it and writes HANDOFF.md next to the project before the wipe.
+#
+#   This is "derive and save", never "hold on, are you sure". SessionEnd cannot
+#   cancel the clear and gives no ordering guarantee against the wipe.
+#
+# TRIGGER: SessionEnd
+# MATCHER: ""
+#
+# Usage:
+# {
+#   "hooks": {
+#     "SessionEnd": [{
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/handoff-on-clear.sh" }]
+#     }]
+#   }
+# }
+
+set -uo pipefail
+INPUT=$(cat)
+
+# Without jq there is nothing to read the event with. Say so rather than failing
+# silently: a handoff that never gets written looks identical to one not needed.
+if ! command -v jq >/dev/null 2>&1; then
+  echo "WARNING [handoff-on-clear]: jq not found - no handoff will be written. Install jq." >&2
+  exit 0
+fi
+
+# Only /clear. The other SessionEnd reasons (prompt_input_exit, logout) end the
+# session without the user losing context they expected to keep.
+[ "$(printf '%s' "$INPUT" | jq -r '.reason // empty')" = "clear" ] || exit 0
+
+tp=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty')
+cwd=$(printf '%s' "$INPUT" | jq -r '.cwd // empty')
+if [ -z "$tp" ] || [ ! -f "$tp" ]; then
+  echo "WARNING [handoff-on-clear]: no readable transcript at '$tp' - nothing written." >&2
+  exit 0
+fi
+
+out="${cwd:-.}/HANDOFF.md"
+{
+  printf '# Handoff (written at /clear, %s)\n\n' "$(date -Is)"
+  printf -- '- transcript: `%s`\n' "$tp"
+  printf -- '- turns: %s user / %s assistant\n\n' \
+    "$(jq -rs '[.[] | select(.type=="user")] | length' "$tp" 2>/dev/null)" \
+    "$(jq -rs '[.[] | select(.type=="assistant")] | length' "$tp" 2>/dev/null)"
+  printf '## Last thing you asked for\n\n'
+  jq -rs '[.[] | select(.type=="user") | .message.content] | last
+          | if type=="array" then map(select(.type=="text").text) | join("\n") else . end' \
+     "$tp" 2>/dev/null | head -c 1200
+  printf '\n'
+} > "$out"
+
+echo "handoff-on-clear: wrote $out" >&2
+exit 0

package/examples/hardcoded-ip-guard.sh

@@ -1,3 +1,4 @@
+#!/bin/bash
 #
 # TRIGGER: PreToolUse  MATCHER: "Edit|Write"
 INPUT=$(cat)

package/examples/helm-install-guard.sh

@@ -1,5 +1,6 @@
+#!/bin/bash
 #
-# TRIGGER: PreToolUse  MATCHER: "Bash"
+# TRIGGER: PreToolUse  MATCHER: "Bash|PowerShell"
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
 [[ -z "$COMMAND" ]] && exit 0

package/examples/home-critical-bash-guard.sh

@@ -13,6 +13,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-home-critical-bash-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [home-critical-bash-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
 [ -z "$COMMAND" ] && exit 0
@@ -38,7 +50,11 @@ fi
 
 # Check for truncation via redirect (> ~/.bashrc or : > ~/.bashrc)
 if echo "$COMMAND" | grep -qE ">\s*(${HOME_DIR}|\~)/\."; then
-    TARGET=$(echo "$COMMAND" | grep -oP ">\s*\K(${HOME_DIR}|~)/\.[^\s;|&]+")
+    # -P は GNU 拡張。BSD grep では TARGET が空になり、下の「重要な設定ファイルを切り詰める」
+    # 検査だけが静かに消える。\K の代わりに > から一致させて前置きを落とす。
+    TARGET=$(echo "$COMMAND" \
+        | grep -oE ">[[:space:]]*(${HOME_DIR}|~)/\.[^[:space:];|&]+" \
+        | sed -E 's/^>[[:space:]]*//')
     if echo "$TARGET" | grep -qE "$CRITICAL"; then
         echo "BLOCKED: Truncating critical home directory file" >&2
         echo "Command: $COMMAND" >&2

package/examples/hook-debug-wrapper.sh

@@ -26,8 +26,12 @@
 #
 # LOG LOCATION: ~/.claude/hook-debug.log
 #
-# TRIGGER: Any (wraps any hook)
-# MATCHER: Any
+# TRIGGER: none
+# MATCHER: none
+#   This wraps another hook rather than being registered on its own. Register it
+#   under whatever event and matcher that hook already uses. There is no `Any`
+#   event: an unknown key under `hooks` is ignored without a warning, so a hook
+#   registered under one sits in the config looking installed and never runs.
 # ================================================================
 
 HOOK_SCRIPT="$1"

package/examples/hook-self-disable-detector.sh

@@ -0,0 +1,99 @@
+#!/bin/bash
+# hook-self-disable-detector.sh — Detect when previously-active hooks have been silently removed
+# Trigger: SessionStart
+# Matcher: (empty — runs once at every session start)
+#
+# Background: Claude Code sessions can edit settings.json and remove hooks
+# that were previously active. Over weeks of accumulation this can silently
+# disable safeguards. One documented case: a Claude Code session disabled
+# its own early-detection hook, and 193 GB of WSL bloat accumulated before
+# the operator noticed. See drafts/active/2026-05-16-self-disabled-safeguard-wsl-bloat.md
+# in cc-loop for the source incident.
+#
+# This hook complements settings-integrity-monitor.sh:
+#   settings-integrity-monitor: warns when settings.json checksum changes
+#   hook-self-disable-detector: warns which specific hooks were removed
+#
+# Behavior:
+#   1. On every SessionStart, capture the current set of (event, matcher, command) triples
+#      from ~/.claude/settings.json and .claude/settings.json.
+#   2. Compare against the most recent snapshot in ~/.claude/.hook-state-snapshots/.
+#   3. If a hook present in the previous snapshot is missing from the current state,
+#      print a warning to stderr listing which event/matcher/command was removed.
+#   4. Save the current state as a new snapshot regardless.
+#
+# Environment overrides (mainly for tests):
+#   CC_HOOK_STATE_DIR     — directory for snapshots (default: $HOME/.claude/.hook-state-snapshots)
+#   CC_USER_SETTINGS      — user settings.json path (default: $HOME/.claude/settings.json)
+#   CC_PROJECT_SETTINGS   — project settings.json path (default: .claude/settings.json)
+#   CC_HOOK_DISABLE_QUIET — if "1", suppress the informational first-run message
+
+set -u
+
+STATE_DIR="${CC_HOOK_STATE_DIR:-$HOME/.claude/.hook-state-snapshots}"
+USER_SETTINGS="${CC_USER_SETTINGS:-$HOME/.claude/settings.json}"
+PROJECT_SETTINGS="${CC_PROJECT_SETTINGS:-.claude/settings.json}"
+QUIET="${CC_HOOK_DISABLE_QUIET:-0}"
+
+mkdir -p "$STATE_DIR" 2>/dev/null || exit 0
+
+# Extract the (event, matcher, command) triples from a settings.json file.
+# Each line is "<event>|<matcher>|<command>". Missing fields become empty strings.
+extract_hooks() {
+    local file="$1"
+    [ -f "$file" ] || return 0
+    jq -r '
+        (.hooks // {})
+        | to_entries[]
+        | .key as $event
+        | .value[]?
+        | ($event + "|" + (.matcher // "") + "|" + ((.hooks // [])[]? | (.command // "")))
+    ' "$file" 2>/dev/null
+}
+
+# Build current state: lines prefixed with origin (user/project) for clarity.
+CURRENT=$(
+    {
+        extract_hooks "$USER_SETTINGS" | sed 's/^/user|/'
+        extract_hooks "$PROJECT_SETTINGS" | sed 's/^/project|/'
+    } | sort -u
+)
+
+# Locate the most recent prior snapshot (lexicographic timestamp order) and
+# read its contents BEFORE writing the new snapshot, so the comparison is not
+# polluted by the file we are about to create.
+PREV_SNAPSHOT=$(ls -1 "$STATE_DIR"/snapshot-*.txt 2>/dev/null | sort | tail -n 1)
+PREVIOUS=""
+if [ -n "$PREV_SNAPSHOT" ] && [ -f "$PREV_SNAPSHOT" ]; then
+    PREVIOUS=$(cat "$PREV_SNAPSHOT" 2>/dev/null)
+fi
+
+# Use nanosecond precision so rapid successive invocations get distinct files.
+NEW_SNAPSHOT="$STATE_DIR/snapshot-$(date +%Y%m%d-%H%M%S-%N).txt"
+printf '%s\n' "$CURRENT" > "$NEW_SNAPSHOT"
+
+if [ -z "$PREV_SNAPSHOT" ]; then
+    if [ "$QUIET" != "1" ]; then
+        COUNT=$(printf '%s' "$CURRENT" | grep -c '^' || true)
+        echo "ℹ hook-self-disable-detector: first run, snapshot of $COUNT hook entries saved." >&2
+    fi
+    exit 0
+fi
+
+# Lines that were in the previous snapshot but are missing from the current state.
+REMOVED=$(comm -23 <(printf '%s\n' "$PREVIOUS" | sort -u) <(printf '%s\n' "$CURRENT" | sort -u) | grep -v '^$' || true)
+
+if [ -n "$REMOVED" ]; then
+    REMOVED_COUNT=$(printf '%s\n' "$REMOVED" | grep -c '^' || true)
+    echo "⚠ hook-self-disable-detector: $REMOVED_COUNT hook entries were active in the previous session but are absent now." >&2
+    echo "  This can mask self-disabled safeguards. Review each entry:" >&2
+    printf '%s\n' "$REMOVED" | while IFS='|' read -r origin event matcher command; do
+        # Truncate command to keep the warning readable.
+        short_cmd=$(printf '%s' "$command" | head -c 120)
+        echo "    [$origin] event=$event matcher='$matcher' command='$short_cmd'" >&2
+    done
+    echo "  Previous snapshot: $PREV_SNAPSHOT" >&2
+    echo "  Current snapshot:  $NEW_SNAPSHOT" >&2
+fi
+
+exit 0

package/examples/hook-stdout-sanitizer.sh

@@ -16,8 +16,12 @@
 #
 # Or use as a template for writing safe hooks.
 #
-# TRIGGER: Any (wrapper for other hooks)
-# MATCHER: Any
+# TRIGGER: none
+# MATCHER: none
+#   This wraps another hook rather than being registered on its own. Register it
+#   under whatever event and matcher that hook already uses. There is no `Any`
+#   event: an unknown key under `hooks` is ignored without a warning, so a hook
+#   registered under one sits in the config looking installed and never runs.
 
 TARGET_HOOK="$1"
 shift

package/examples/hook-tamper-guard.sh

@@ -27,6 +27,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-hook-tamper-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [hook-tamper-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)
 

package/examples/image-dimension-guard.sh

@@ -0,0 +1,109 @@
+#!/bin/bash
+# image-dimension-guard.sh — Block Read of oversized images that trigger a costly retry loop
+#
+# Solves: When Claude reads/attaches an image whose dimensions exceed the API
+# limit (2000px per side for many-image requests), the API returns a
+# 400 invalid_request_error. Claude Code silently removes the image and then
+# RETRIES (observed 41x in #65636). Each retry mutates the conversation prefix,
+# which invalidates the prompt cache: cache reads collapse and the whole
+# context is re-written to the cache every turn, inflating session cost ~35x
+# (one such loop was ~66% of a session's total cost).
+#
+# This checks an image's pixel dimensions BEFORE the Read tool sends it and
+# blocks (or warns) when a side exceeds the limit, so the loop never starts.
+# Dimensions are read from the file header with no external dependency
+# (PNG/JPEG/GIF/BMP); it falls back to ImageMagick `identify` for other
+# formats. It FAILS OPEN when dimensions cannot be determined, so it never
+# breaks a normal Read.
+#
+# Complements image-file-validator.sh, which blocks FAKE images (wrong MIME);
+# this one blocks REAL images that are simply too large.
+#
+# TRIGGER: PreToolUse  MATCHER: "Read"
+# Config:
+#   CC_IMAGE_DIM_LIMIT=2000   max px per side (2000 = many-image API limit; raise to 8000 for single-image-only workflows)
+#   CC_IMAGE_DIM_GUARD=block  block | warn | off
+# Related: https://github.com/anthropics/claude-code/issues/65636
+
+INPUT=$(cat)
+
+MODE="${CC_IMAGE_DIM_GUARD:-block}"
+[ "$MODE" = "off" ] && exit 0
+LIMIT="${CC_IMAGE_DIM_LIMIT:-2000}"
+
+FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+[ -z "$FILE" ] && exit 0
+[ ! -f "$FILE" ] && exit 0
+
+# Only raster formats have a pixel cap that triggers this 400 (skip svg/ico).
+case "${FILE,,}" in
+    *.png|*.jpg|*.jpeg|*.gif|*.bmp|*.webp|*.tiff|*.tif) ;;
+    *) exit 0 ;;
+esac
+
+# Read "W H" from the file header with no hard dependency.
+DIMS=$(python3 - "$FILE" 2>/dev/null <<'PY'
+import sys, struct
+def dims(path):
+    with open(path, 'rb') as f:
+        head = f.read(26)
+        if head[:8] == b'\x89PNG\r\n\x1a\n':
+            w, h = struct.unpack('>II', head[16:24]); return w, h
+        if head[:6] in (b'GIF87a', b'GIF89a'):
+            w, h = struct.unpack('<HH', head[6:10]); return w, h
+        if head[:2] == b'BM':
+            w, h = struct.unpack('<ii', head[18:26]); return abs(w), abs(h)
+        if head[:2] == b'\xff\xd8':  # JPEG: scan SOF markers
+            f.seek(2)
+            while True:
+                b = f.read(1)
+                if not b: break
+                if b != b'\xff': continue
+                marker = f.read(1)
+                while marker == b'\xff': marker = f.read(1)
+                if not marker: break
+                m = marker[0]
+                if m in (0xd8, 0xd9) or 0xd0 <= m <= 0xd7: continue
+                seg = f.read(2)
+                if len(seg) < 2: break
+                length = struct.unpack('>H', seg)[0]
+                if m in (0xc0,0xc1,0xc2,0xc3,0xc5,0xc6,0xc7,0xc9,0xca,0xcb,0xcd,0xce,0xcf):
+                    data = f.read(5)
+                    if len(data) < 5: break
+                    h, w = struct.unpack('>HH', data[1:5]); return w, h
+                f.seek(length - 2, 1)
+    return None
+try:
+    r = dims(sys.argv[1])
+    if r: print(r[0], r[1])
+except Exception:
+    pass
+PY
+)
+
+# Fallback for formats the header parser skips (e.g. WEBP/TIFF).
+if [ -z "$DIMS" ] && command -v identify >/dev/null 2>&1; then
+    DIMS=$(identify -format '%w %h' "$FILE[0]" 2>/dev/null | head -1)
+fi
+
+# Fail open if dimensions are unknown — never break a normal Read.
+[ -z "$DIMS" ] && exit 0
+W=$(printf '%s' "$DIMS" | awk '{print $1}')
+H=$(printf '%s' "$DIMS" | awk '{print $2}')
+case "$W" in ''|*[!0-9]*) exit 0;; esac
+case "$H" in ''|*[!0-9]*) exit 0;; esac
+
+MAX="$W"; [ "$H" -gt "$W" ] && MAX="$H"
+[ "$MAX" -le "$LIMIT" ] && exit 0
+
+BASE="${FILE##*/}"
+MSG="${BASE} is ${W}x${H}px, exceeding the ${LIMIT}px per-side API limit for many-image requests. Sending it returns a 400 error; Claude Code then silently strips the image and retries (observed 41x in #65636), which invalidates the prompt cache and can inflate session cost ~35x. Resize it first, e.g. 'convert ${BASE} -resize ${LIMIT}x${LIMIT} small-${BASE}' (ImageMagick) or 'sips -Z ${LIMIT} ${BASE}' (macOS), then read the smaller copy. Set CC_IMAGE_DIM_LIMIT to change the threshold, CC_IMAGE_DIM_GUARD=warn to only warn, or =off to disable."
+
+if [ "$MODE" = "warn" ]; then
+    echo "image-dimension-guard: $MSG" >&2
+    exit 0
+fi
+
+# block (default): emit a structured block decision (exit 0, like image-file-validator).
+jq -n --arg r "$MSG" '{decision: "block", reason: $r}'
+exit 0