cc-safe-setup 29.8.0 → 30.0.4

package/examples/bash-project-fence.sh

@@ -0,0 +1,194 @@
+#!/bin/bash
+# ================================================================
+# bash-project-fence.sh — Block Bash commands that reach outside the project root
+# ================================================================
+# PURPOSE:
+#   Prevents Claude Code from reading, writing, or scanning files
+#   outside CLAUDE_PROJECT_DIR via Bash commands. The complement to
+#   working-directory-fence.sh (which covers Read/Edit/Write tools).
+#   Without this hook, CLAUDE.md restrictions on path scope are
+#   model-side soft constraints that the model can ignore.
+#
+# SOLVES Issue #56739: model ran `find` across the entire Desktop,
+#   located a personal file, and sent it to a 3rd-party API without
+#   user confirmation. CLAUDE.md had a project-directory restriction
+#   that the model ignored. Tool-layer enforcement was absent.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash"
+#
+# HOW IT WORKS:
+#   Parses the Bash command for absolute path arguments. For each
+#   absolute path, resolves it against CLAUDE_PROJECT_DIR (or CWD as
+#   fallback). If any path resolves outside the project tree, blocks
+#   with exit 2 and a structured explanation.
+#
+# CONFIGURATION:
+#   CC_BASH_FENCE_ALLOW — colon-separated additional allowed prefixes
+#     (e.g., "/tmp:/var/log:/home/user/.config")
+#     Default: /tmp, /var/tmp, /dev/null, /dev/stdin, /dev/stdout, /dev/stderr
+#   CC_BASH_FENCE_ACTION — "block" (default) or "warn"
+#   CC_BASH_FENCE_OFF — set to "1" to disable the hook entirely
+#
+# WHAT IT DOES NOT DO:
+#   Does not parse arbitrary shell syntax (pipes, subshells, command
+#   substitution). For most cases this is sufficient — the model's
+#   surface use of `find`, `cat`, `grep`, `cp`, `mv`, `head`, `tail`,
+#   `ls` against absolute paths is what reaches outside the project.
+#   Operators who need stricter parsing should add a separate hook.
+# ================================================================
+
+set -u
+
+# Honor disable flag
+# 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-bash-project-fence-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [bash-project-fence]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+if [ "${CC_BASH_FENCE_OFF:-0}" = "1" ]; then
+    exit 0
+fi
+
+INPUT=$(cat)
+COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+if [ -z "$COMMAND" ]; then
+    exit 0
+fi
+
+# Determine project root
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+PROJECT_ROOT=$(realpath -m "$PROJECT_ROOT" 2>/dev/null || printf '%s' "$PROJECT_ROOT")
+
+# Default allowed prefixes (system paths the model legitimately needs)
+DEFAULT_ALLOW="/tmp:/var/tmp:/dev/null:/dev/stdin:/dev/stdout:/dev/stderr:/proc"
+
+# Build allow list
+ALLOW_PREFIXES="${PROJECT_ROOT}:${DEFAULT_ALLOW}"
+if [ -n "${CC_BASH_FENCE_ALLOW:-}" ]; then
+    ALLOW_PREFIXES="${ALLOW_PREFIXES}:${CC_BASH_FENCE_ALLOW}"
+fi
+
+ACTION="${CC_BASH_FENCE_ACTION:-block}"
+
+# Extract absolute path arguments from the command.
+# Match tokens that start with / or ~/, but exclude pure flags (-x), URLs, and
+# path-like substrings inside quoted JSON / env var assignments. We use a simple
+# tokenizer based on shell word splitting; this misses some edge cases but
+# covers the common file-access surface.
+#
+# Tokens captured:
+#   - /absolute/path
+#   - ~/home/path (expanded to $HOME)
+# Tokens skipped:
+#   - flags starting with -
+#   - URLs (contain ://)
+#   - things that look like options for find: -path X, -name X (handled below)
+
+declare -a OUTSIDE_PATHS=()
+
+# Use a portable word-split. Word-split the command on whitespace and pipes;
+# preserve quoted segments roughly by stripping quotes after split.
+# shellcheck disable=SC2086
+set -f
+IFS=$' \t\n|;&'
+for tok in $COMMAND; do
+    # Strip surrounding quotes
+    tok="${tok#\"}"; tok="${tok%\"}"
+    tok="${tok#\'}"; tok="${tok%\'}"
+
+    # Strip the punctuation that wraps a command, so a path inside a
+    # substitution or a subshell is still seen as a path. The word split above
+    # does not break on ( ) or a backtick, so `[[ -n $(ls ~/secrets) ]]` used to
+    # produce the token "~/secrets)", which matches neither the ~/ case nor the
+    # absolute-path case below, and the reference left the fence unnoticed.
+    # Measured 2026-08-04: the bare form was blocked and the wrapped form passed.
+    tok="${tok#\$(}"; tok="${tok#(}"; tok="${tok#\`}"
+    tok="${tok%)}"; tok="${tok%\`}"
+
+    # Expand ~/ to $HOME
+    case "$tok" in
+        '~'/*) tok="${HOME}${tok#\~}" ;;
+        '~') tok="${HOME}" ;;
+    esac
+
+    # Only check tokens that look like absolute paths
+    case "$tok" in
+        /*) ;;       # absolute path - check it
+        *) continue ;;
+    esac
+
+    # Skip URLs (e.g., /http://... would be invalid anyway)
+    case "$tok" in
+        *://*) continue ;;
+    esac
+
+    # Resolve symlinks / .. against the filesystem (use -m for nonexistent paths)
+    RESOLVED=$(realpath -m "$tok" 2>/dev/null || printf '%s' "$tok")
+
+    # Check against each allowed prefix
+    ALLOWED=0
+    OLD_IFS="$IFS"
+    IFS=':'
+    for prefix in $ALLOW_PREFIXES; do
+        IFS="$OLD_IFS"
+        [ -z "$prefix" ] && continue
+        # Normalize prefix
+        prefix_norm=$(realpath -m "$prefix" 2>/dev/null || printf '%s' "$prefix")
+        # Match if RESOLVED equals prefix or starts with prefix + "/"
+        case "$RESOLVED" in
+            "$prefix_norm"|"$prefix_norm"/*)
+                ALLOWED=1
+                break
+                ;;
+        esac
+        IFS=':'
+    done
+    IFS="$OLD_IFS"
+
+    if [ "$ALLOWED" -eq 0 ]; then
+        OUTSIDE_PATHS+=("$RESOLVED")
+    fi
+done
+set +f
+
+if [ "${#OUTSIDE_PATHS[@]}" -eq 0 ]; then
+    exit 0
+fi
+
+# Report
+{
+    if [ "$ACTION" = "warn" ]; then
+        echo "WARN: Bash command references path outside the project root."
+    else
+        echo "BLOCKED: Bash command references path outside the project root."
+    fi
+    echo "  Project root: $PROJECT_ROOT"
+    for p in "${OUTSIDE_PATHS[@]}"; do
+        echo "  Outside path: $p"
+    done
+    echo "  Command head: $(printf '%s' "$COMMAND" | head -c 120)"
+    echo
+    echo "  This hook enforces a project-root allow list at the Bash layer."
+    echo "  Background: model-side restrictions (CLAUDE.md, system prompt) can"
+    echo "  be ignored. See https://github.com/anthropics/claude-code/issues/56739."
+    echo
+    echo "  To allow specific paths outside the project, set:"
+    echo "    CC_BASH_FENCE_ALLOW=\"/path/one:/path/two\""
+    echo "  To downgrade to a warning, set CC_BASH_FENCE_ACTION=warn."
+    echo "  To disable entirely, set CC_BASH_FENCE_OFF=1."
+} >&2
+
+if [ "$ACTION" = "warn" ]; then
+    exit 0
+fi
+
+exit 2

package/examples/bash-safety-auto-deny.sh

@@ -14,6 +14,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-bash-safety-auto-deny-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [bash-safety-auto-deny]: 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

package/examples/bash-secret-output-detector.sh

@@ -7,11 +7,37 @@
 #
 # How it works: PostToolUse hook on Bash that checks command stdout for
 #   patterns matching API keys, tokens, passwords, and connection strings.
-#   Emits a systemMessage warning the model to ignore/not repeat secrets.
+#   When one matches, it prints a warning on stderr, so you see it in the
+#   terminal. By default it does not interrupt the turn (exit 0).
+#
+# WHAT THIS DOES NOT DO BY DEFAULT: it does not put the warning in front of
+#   the model. Until 2026-09-20 this hook wrote {"systemMessage": ...} to
+#   stdout on exit 0 and the header said it warned the model. Measured on
+#   2.1.278, PostToolUse matcher Bash, in a disposable HOME, judging by
+#   whether a unique token in the message came back when the model was asked
+#   to quote everything it had been shown:
+#
+#     nothing printed (control)                 not delivered
+#     top-level {"systemMessage": ...}, exit 0   not delivered
+#     stderr + exit 2 (positive control)         DELIVERED
+#
+#   The positive control is the point: the probe can see a delivered message,
+#   so the middle row is not an artefact of how it was read. In that run the
+#   model said in as many words that no hook output appeared, while quoting
+#   the system reminders it had been given.
+#
+#   So on exit 0 the warning reaches you and not the model. If you want the
+#   model to be told, set CC_SECRET_OUTPUT_BLOCK=1 below — that is the shape
+#   measured as delivered. It is a blocking error: the tool has already run,
+#   and Claude is told about it and can act on it.
 #
 # TRIGGER: PostToolUse
 # MATCHER: "Bash"
 #
+# Environment:
+#   CC_SECRET_OUTPUT_BLOCK=1  — exit 2 after warning, so the model is told.
+#                               Default (unset) warns on stderr and exits 0.
+#
 # Usage:
 # {
 #   "hooks": {
@@ -46,7 +72,14 @@ if echo "$STDOUT" | grep -qiE '(mysql|postgres|mongodb|redis)://[^:]+:[^@]+@'; t
 fi
 
 # Private keys
-if echo "$STDOUT" | grep -qE '-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----'; then
+# `--` is required: without it grep reads the leading dashes of the PEM
+# header as options and dies with "unrecognized option", so this check
+# silently never fired. The six existing checks in test.sh only assert
+# exit 0, and this hook always exited 0, so they passed anyway.
+# The same omission was found in ci-workflow-guard.sh and fixed in the same
+# branch; a sweep of examples/ and hooks/ for a grep pattern starting with a
+# dash found no third case.
+if echo "$STDOUT" | grep -qE -- '-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----'; then
     FOUND="${FOUND}private key, "
 fi
 
@@ -62,7 +95,15 @@ fi
 
 if [ -n "$FOUND" ]; then
     FOUND="${FOUND%, }"
-    echo "{\"systemMessage\":\"⚠ SECRET DETECTED in command output: ${FOUND}. Do NOT repeat, log, or include these values in any output. They are now in context but should be treated as redacted.\"}"
+    # stderr, not stdout: a {"systemMessage": ...} object on stdout is dropped
+    # here (measured 2026-09-20, table in the header). stderr at least reaches
+    # the terminal, and with BLOCK=1 it reaches the model too.
+    echo "⚠ SECRET DETECTED in command output: ${FOUND}." >&2
+    echo "  Do NOT repeat, log, or include these values in any output." >&2
+    echo "  They are already in the context window and should be treated as redacted." >&2
+    if [ "${CC_SECRET_OUTPUT_BLOCK:-0}" = "1" ]; then
+        exit 2
+    fi
 fi
 
 exit 0

package/examples/bash-trace-guard.sh

@@ -21,6 +21,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-bash-trace-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [bash-trace-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

package/examples/bg-permission-prompt-warner.sh

@@ -0,0 +1,182 @@
+#!/bin/bash
+# bg-permission-prompt-warner.sh — Warn operators dispatching `claude --bg` that
+# background sessions stall on permission prompts even under acceptEdits
+# (Cluster 24 candidate, axis 24A — non-interactive permission gap)
+#
+# Background:
+#   Cluster 24 candidate axis 24A documents that `claude --bg` code-writing
+#   sessions stall on permission prompts even when invoked with
+#   `--permission-mode acceptEdits`. There is no non-interactive way to
+#   answer the prompt from the shell, so unattended automation that depends
+#   on `--bg` for fan-out blocks indefinitely on the first edit-permission
+#   gate.
+#
+#   Anchor case:
+#     #64271 — `claude --bg` code-writing sessions stall on permission
+#              prompts with no non-interactive way to answer
+#
+#   The structural shape: the operator dispatches a background session
+#   expecting it to run unattended, walks away, and returns to find the
+#   session paused indefinitely on a permission prompt that no automation
+#   layer can answer. The "background" framing implies the session can
+#   run without supervision; the permission gate breaks that expectation.
+#
+#   Cluster 24 axes (4 sub-clusters):
+#     24A — non-interactive permission gap (#64271, this hook)
+#     24B — documentation gap: hook payload omits agent_id for bg sessions (#64272)
+#     24C — resource-release gap: Windows daemon retains dir handle (#64273)
+#     24D — result-delivery gap: iOS Dispatch / Advisor result not relayed
+#           (#64242, #64244, #64250)
+#
+#   This hook is a SessionStart advisory that fires when:
+#     - the parent process command line contains `--bg` or `--background`
+#       (detected via /proc/$PPID/cmdline on Linux or `ps -o command` on
+#       macOS), AND
+#     - the operator has not already seen the advisory in this session
+#
+#   The advisory describes the four sub-cluster axes, names the operator-side
+#   workaround for axis 24A (keep a terminal attached until the
+#   non-interactive path lands), and links the field guide.
+#
+# When this hook does NOT emit anything:
+#   - CC_BG_WARN_DISABLE=1
+#   - CC_BG_WARN_QUIET=1
+#   - the parent command line does not contain --bg / --background
+#   - the parent command line cannot be read
+#   - the advisory has already fired in this session
+#
+# Hook config (settings.json):
+# {
+#   "hooks": {
+#     "SessionStart": [{
+#       "matcher": "",
+#       "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/bg-permission-prompt-warner.sh" }]
+#     }]
+#   }
+# }
+#
+# Env vars:
+#   CC_BG_WARN_DISABLE=1            — never emit
+#   CC_BG_WARN_QUIET=1              — silent (process but never write to stderr)
+#   CC_BG_WARN_FORCE=1              — bypass parent-cmdline detection, always emit
+#                                     (tests, or for operators who want the
+#                                      advisory on every session-start)
+#   CC_BG_WARN_PARENT_CMD=<cmd>     — parent command line override (tests)
+#   CC_BG_WARN_STATE_DIR=<path>     — one-shot state dir override (default ~/.claude/state)
+#   CC_BG_WARN_SESSION_ID=<id>      — session id override (tests)
+#
+# Design notes:
+#   - Opt-out. Operators who use --bg regularly and have already absorbed
+#     the limitation can disable. The default-on signal serves operators
+#     who are about to be surprised by the permission gate.
+#   - One-shot per session. The advisory fires once. Repeated firings
+#     across sessions of long-running --bg pilots add no signal.
+#   - Never blocks. Exit always 0. The advisory is informational.
+#   - Parent detection is best-effort: /proc on Linux, ps on macOS,
+#     fallback to env vars on platforms without either.
+
+set -u
+
+if [[ "${CC_BG_WARN_DISABLE:-0}" = "1" ]]; then
+    exit 0
+fi
+
+STATE_DIR="${CC_BG_WARN_STATE_DIR:-$HOME/.claude/state}"
+mkdir -p "$STATE_DIR" 2>/dev/null
+
+SESSION_ID="${CC_BG_WARN_SESSION_ID:-${CLAUDE_SESSION_ID:-default}}"
+GUARD_FILE="$STATE_DIR/bg-warn-${SESSION_ID}.fired"
+
+if [[ -f "$GUARD_FILE" ]]; then
+    exit 0
+fi
+
+# Detect parent command line. Order of attempts:
+#   1) explicit override via env var (tests)
+#   2) /proc/$PPID/cmdline (Linux)
+#   3) ps -o command -p $PPID (macOS)
+PARENT_CMD="${CC_BG_WARN_PARENT_CMD:-}"
+if [[ -z "$PARENT_CMD" ]]; then
+    if [[ -r "/proc/$PPID/cmdline" ]]; then
+        # Replace NULs with spaces for grep
+        PARENT_CMD=$(tr '\0' ' ' < "/proc/$PPID/cmdline" 2>/dev/null)
+    elif command -v ps >/dev/null 2>&1; then
+        PARENT_CMD=$(ps -o command= -p "$PPID" 2>/dev/null)
+    fi
+fi
+
+# Decide whether to emit. CC_BG_WARN_FORCE bypasses parent-cmdline detection.
+SHOULD_EMIT=0
+if [[ "${CC_BG_WARN_FORCE:-0}" = "1" ]]; then
+    SHOULD_EMIT=1
+elif [[ -n "$PARENT_CMD" ]] && echo "$PARENT_CMD" | grep -qE -- '(--bg|--background)\b'; then
+    SHOULD_EMIT=1
+fi
+
+if [[ "$SHOULD_EMIT" -ne 1 ]]; then
+    exit 0
+fi
+
+# Mark one-shot guard.
+touch "$GUARD_FILE" 2>/dev/null
+
+if [[ "${CC_BG_WARN_QUIET:-0}" = "1" ]]; then
+    exit 0
+fi
+
+cat >&2 <<EOF
+
+────────────────────────────────────────────────────────────────────
+  Background dispatch advisory — Cluster 24 axis 24A (--bg permission gap)
+────────────────────────────────────────────────────────────────────
+  Parent command line includes \`--bg\` / \`--background\`. This session
+  appears to be running as a background-dispatched Claude Code session.
+
+  The Cluster 24 axis 24A pattern: \`claude --bg\` code-writing sessions
+  stall on permission prompts even under \`--permission-mode acceptEdits\`.
+  There is no non-interactive way to answer the prompt from the shell,
+  so unattended automation that depends on --bg blocks indefinitely on
+  the first edit-permission gate.
+
+  Anchor case: #64271.
+
+  Recommended operator-side workaround until the non-interactive path
+  lands upstream:
+
+    1) Keep a terminal attached to the dispatcher process until the
+       background session completes — the permission prompts surface
+       there and can be answered manually.
+    2) For long-running unattended automation, do not rely on --bg
+       alone; combine with explicit non-interactive Bash invocations
+       that bypass the edit-permission surface entirely.
+    3) Audit your tool-call distribution. Tool calls that trigger
+       edit-permission gates (Write, Edit, NotebookEdit) are the ones
+       that stall; read-only tool calls (Read, Glob, Bash with safe
+       commands) do not.
+
+  Three sibling axes also documented in Cluster 24 candidate:
+
+    24B — \`hooks.md\` does not articulate that background-dispatched
+          sessions are top-level processes, so hook payloads omit
+          \`agent_id\` (#64272). Use \`session_id\` as the primary
+          correlator instead.
+
+    24C — On Windows, the background daemon retains directory handles
+          after \`claude rm\` (#64273). Sleep briefly or restart the
+          per-user node daemon before retrying directory deletion.
+
+    24D — Dispatch / iOS Dispatch / Advisor result-delivery surface
+          signals "completed" but the result never reaches the
+          orchestrator context (#64242, #64244, #64250). Verify with
+          an explicit completion-marker check rather than trusting
+          the UI signal.
+
+  Field guide: cluster-tracker.html on GitHub Pages, search "Cluster 24".
+
+  (This advisory fires once per session. To disable:
+   export CC_BG_WARN_DISABLE=1)
+────────────────────────────────────────────────────────────────────
+
+EOF
+
+exit 0

package/examples/bg-task-cooldown-guard.sh

@@ -14,6 +14,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-bg-task-cooldown-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [bg-task-cooldown-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)
 COOLDOWN="${CC_BG_COOLDOWN_SECS:-10}"

package/examples/binary-read-detector.sh

@@ -0,0 +1,135 @@
+#!/bin/bash
+# ================================================================
+# binary-read-detector.sh — Surface image / PDF / binary path
+# references in user prompts before they reach the vision dispatch
+# bus that bypasses PreToolUse hooks
+# ================================================================
+# PURPOSE:
+#   Issue #62639 documented that PreToolUse hooks do not fire when
+#   the Read tool reads image, PDF, or other binary files. The
+#   model receives the content via a vision-routing dispatch path
+#   that bypasses the hook bus entirely. Three related places
+#   exhibit the same gap:
+#
+#     1. Read on .png / .jpg / .webp / .gif / .heic — PreToolUse
+#        skipped, content goes straight to vision input
+#     2. Read on .pdf — same skip; model receives parsed content
+#        but no hook event fires
+#     3. Image attachments via `claude --image` or drag-and-drop
+#        in the desktop app — UserPromptSubmit fires but does not
+#        carry the image path in tool_input in a hook-readable
+#        schema
+#
+#   This means PreToolUse cannot be a security boundary against
+#   prompt-injection-via-image attacks while the dispatch gap
+#   exists: an attacker who gets the model to Read a poisoned
+#   image bypasses every PreToolUse defense installed.
+#
+#   The earliest hook surface that DOES fire for these cases is
+#   UserPromptSubmit. This hook scans the prompt text for binary
+#   path references and surfaces them to the operator with the
+#   articulated risk and operator-side options.
+#
+# WHO THIS PROTECTS:
+#   Operators relying on PreToolUse hooks to gate file access,
+#   especially those running Claude Code on machines where
+#   ~/Downloads/ or similar directories may contain untrusted
+#   image content (attachments from email, browser downloads).
+#
+# DETECTION:
+#   UserPromptSubmit. Scan the prompt for path-like substrings
+#   that end in a binary extension. Default extensions:
+#     png, jpg, jpeg, gif, webp, heic, pdf, mp4, mov, mp3, wav,
+#     zip, tar, gz, bin, exe, dll, so, dylib, doc, docx, xls,
+#     xlsx, ppt, pptx
+#   If matches found, emit an advisory naming the matched paths
+#   and articulating the bypass risk.
+#
+# OUTPUT:
+#   stderr advisory naming matched paths and articulating that:
+#     - PreToolUse hooks WILL NOT fire when these are Read
+#     - Hook-installed policies cannot be enforced against them
+#     - Operator should verify the content is trusted before
+#       proceeding (or pre-process to text out-of-band)
+#   Exit 0 always (advisory, not blocking) so the prompt still
+#   proceeds. The operator decides whether to continue.
+#
+# CONFIGURATION:
+#   CC_BINARY_READ_DISABLE  — set to 1 to disable entirely
+#   CC_BINARY_READ_BLOCK    — set to 1 to block (exit 2) instead
+#                             of advisory pass-through
+#   CC_BINARY_READ_EXTENSIONS — colon-separated extension list
+#                             override (without dots)
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/62639
+#
+# TRIGGER: UserPromptSubmit
+# MATCHER: "" (all)
+# ================================================================
+
+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-binary-read-detector-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [binary-read-detector]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+INPUT=$(cat 2>/dev/null || echo "{}")
+
+[ "${CC_BINARY_READ_DISABLE:-0}" = "1" ] && exit 0
+
+DEFAULT_EXTS='png:jpg:jpeg:gif:webp:heic:pdf:mp4:mov:mp3:wav:zip:tar:gz:bin:exe:dll:so:dylib:doc:docx:xls:xlsx:ppt:pptx'
+EXTS="${CC_BINARY_READ_EXTENSIONS:-$DEFAULT_EXTS}"
+
+PROMPT=$(printf '%s' "$INPUT" | jq -r '.prompt // .user_message // empty' 2>/dev/null)
+[ -z "$PROMPT" ] && exit 0
+
+# Build extension alternation pattern: \.(png|jpg|jpeg|...)\b
+EXT_ALT=$(printf '%s' "$EXTS" | tr ':' '|')
+PATTERN="\\.($EXT_ALT)(\\s|\$|['\"]|/|\\)|,|\\.|;)"
+
+# Find all matching path-like substrings.
+MATCHES=$(printf '%s' "$PROMPT" | grep -oiE "[A-Za-z0-9_./~-]+\\.($EXT_ALT)" | sort -u | head -10)
+
+[ -z "$MATCHES" ] && exit 0
+
+MSG="Binary path reference detected in prompt — PreToolUse hooks will NOT fire when Claude reads these:
+
+$(printf '%s' "$MATCHES" | sed 's/^/  - /')
+
+Issue #62639 documented that the Read tool dispatches image, PDF, and other binary content through a vision-routing path that bypasses the PreToolUse hook bus. Operator-installed PreToolUse policies cannot block, redirect, or audit these reads.
+
+What this means for your hook policy:
+- Any 'block reads outside this directory' rule does not apply
+- Any 'audit-log every file read' rule misses these
+- Prompt-injection-via-image attacks bypass every PreToolUse defense
+
+Operator-side options:
+1. Verify the file is trusted before proceeding. If it came from email, browser download, or external chat, treat it as untrusted
+2. Pre-process to text out-of-band (e.g., 'tesseract image.png out' or 'pdftotext file.pdf -') and reference the text file instead. Text reads DO fire PreToolUse
+3. For audit trails, install a PostToolUse hook — PostToolUse fires for binary reads (with empty tool_response.content for images) so the read is at least recorded
+4. For policy enforcement, the only reliable layer is the OS (macOS Quarantine, Linux AppArmor profile, FUSE wrapper). PreToolUse cannot be a security boundary against this dispatch path
+
+To disable this advisory:
+  CC_BINARY_READ_DISABLE=1
+
+To block instead of advise (exit 2 to prevent the prompt from running):
+  CC_BINARY_READ_BLOCK=1
+
+Related: cc-safe-setup Cluster 1 (Sub-Agent Observability), hook-bus completeness sub-pattern."
+
+echo "[binary-read-detector] $MSG" >&2
+
+if [ "${CC_BINARY_READ_BLOCK:-0}" = "1" ]; then
+    exit 2
+fi
+
+exit 0

package/examples/binary-upload-guard.sh

@@ -11,6 +11,18 @@
 # TRIGGER: PreToolUse
 # MATCHER: "Bash"
 
+# 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-binary-upload-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [binary-upload-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