cc-safe-setup 29.7.0 → 30.0.4

package/examples/agents-md-edit-drift-warner.sh

@@ -0,0 +1,223 @@
+#!/bin/bash
+# ================================================================
+# agents-md-edit-drift-warner.sh — Warn at the moment CLAUDE.md (or
+#   AGENTS.md) is edited that the sibling instruction file is now
+#   stale. Complements the SessionStart-only agents-md-sync-checker
+#   (PR #377) with a PostToolUse signal at the actual drift event.
+# ================================================================
+# PURPOSE:
+#   anthropics/claude-code#6235 (5,233 reactions, 13+ months open,
+#   the largest single feature request in the Claude Code tracker)
+#   asks Claude Code to read AGENTS.md as a fallback to CLAUDE.md.
+#   The companion SessionStart hook agents-md-sync-checker (PR
+#   #377) detects drift at the start of a session — but the
+#   actionable moment is the edit itself. By the time the next
+#   session starts the operator has often moved on; an in-the-loop
+#   warning at the moment of the edit is the cheapest correction
+#   point.
+#
+#   This PostToolUse hook fires on Edit and Write tool calls whose
+#   file_path resolves to one of the candidate instruction files
+#   (CLAUDE.md, AGENTS.md, .claude/CLAUDE.md, .agents/AGENTS.md).
+#   It then checks whether the sibling file exists and emits a
+#   one-screen advisory naming the edit and the sibling that now
+#   needs reconciliation.
+#
+# TRIGGER: PostToolUse  MATCHER: "Edit|Write|MultiEdit"
+# CLUSTER: 3 (AGENTS.md interop)
+# COMPANION HOOK: agents-md-sync-checker.sh (SessionStart, PR #377)
+#
+# DETECTION LOGIC:
+#   1. Read tool name and tool_input.file_path from PostToolUse
+#      hook input.
+#   2. If the tool is not Edit / Write / MultiEdit, exit silent.
+#   3. If the file_path basename is not in the instruction-file
+#      candidate set, exit silent.
+#   4. Determine which instruction file was edited
+#      (CLAUDE.md or AGENTS.md).
+#   5. Locate the sibling instruction file in the same directory
+#      or in the standard sibling-directory location
+#      (.claude/CLAUDE.md ↔ .agents/AGENTS.md).
+#   6. If the sibling exists and is not the same inode (i.e. not
+#      a symlink to the same file), emit a warning. If the sibling
+#      is symlinked to this file, no drift is possible — exit
+#      silent.
+#   7. If the sibling does not exist, emit a softer note: the
+#      sibling-tool agent (Codex / Cursor / Amp / etc., or Claude
+#      Code itself depending on direction) will run without these
+#      instructions until the sibling is created.
+#
+# CONFIGURATION (env vars):
+#   CC_AGENTS_MD_DRIFT_WARN_DISABLE   Set to "1" to silence.
+#   CC_AGENTS_MD_DRIFT_WARN_QUIET     Set to "1" to suppress the
+#                                     verbose advisory and emit
+#                                     only the one-line state.
+#
+# UPSTREAM REFERENCES:
+#   #6235 (5,233 reactions, the central feature request)
+#   #31005 (community plea, six issues, 7-month silence)
+#   #34235, #62371, #53223 (sibling angles)
+#
+# WHY POSTTOOLUSE, NOT PRETOOLUSE:
+#   PreToolUse would block the edit until the operator reconciles,
+#   which is wrong for this cluster — the operator is intentionally
+#   editing the file and the sibling is meant to track the edit.
+#   PostToolUse fires after the edit lands and surfaces the
+#   sibling-file gap so the operator can decide whether to mirror
+#   the change now or defer it. The hook never blocks; it advises.
+# ================================================================
+
+set -u
+
+if [ "${CC_AGENTS_MD_DRIFT_WARN_DISABLE:-0}" = "1" ]; then
+    exit 0
+fi
+
+QUIET="${CC_AGENTS_MD_DRIFT_WARN_QUIET:-0}"
+
+INPUT=$(cat 2>/dev/null || true)
+if [ -z "$INPUT" ]; then
+    exit 0
+fi
+
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // .tool_input.tool_name // empty' 2>/dev/null)
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+
+if [ -z "$TOOL_NAME" ] || [ -z "$FILE_PATH" ]; then
+    exit 0
+fi
+
+# Only fire on file-modifying tool families.
+case "$TOOL_NAME" in
+    Edit|Write|MultiEdit) ;;
+    *) exit 0 ;;
+esac
+
+BASENAME=$(basename "$FILE_PATH")
+
+# Only fire on the instruction-file candidates.
+case "$BASENAME" in
+    CLAUDE.md|AGENTS.md) ;;
+    *) exit 0 ;;
+esac
+
+DIR=$(dirname "$FILE_PATH")
+
+# Determine the sibling basename.
+if [ "$BASENAME" = "CLAUDE.md" ]; then
+    SIBLING_BASENAME="AGENTS.md"
+    EDITED_TOOL="Claude Code"
+    SIBLING_TOOLS="Codex / Cursor / Amp / Copilot / Aider / etc."
+else
+    SIBLING_BASENAME="CLAUDE.md"
+    EDITED_TOOL="Codex / Cursor / Amp / Copilot / Aider / etc."
+    SIBLING_TOOLS="Claude Code"
+fi
+
+# Look for the sibling in the same directory first.
+SIBLING_PATH="${DIR}/${SIBLING_BASENAME}"
+
+# If the sibling is not in the same directory, also check the
+# cross-mounted standard location (.claude/CLAUDE.md ↔
+# .agents/AGENTS.md).
+SIBLING_EXISTS=0
+if [ -f "$SIBLING_PATH" ]; then
+    SIBLING_EXISTS=1
+fi
+
+if [ "$SIBLING_EXISTS" = "0" ]; then
+    ALT_PATH=""
+    case "$FILE_PATH" in
+        */.claude/CLAUDE.md)
+            ALT_PATH="${FILE_PATH%/.claude/CLAUDE.md}/.agents/AGENTS.md"
+            ;;
+        */.agents/AGENTS.md)
+            ALT_PATH="${FILE_PATH%/.agents/AGENTS.md}/.claude/CLAUDE.md"
+            ;;
+    esac
+    if [ -n "$ALT_PATH" ] && [ -f "$ALT_PATH" ]; then
+        SIBLING_PATH="$ALT_PATH"
+        SIBLING_EXISTS=1
+    fi
+fi
+
+# If the sibling does not exist anywhere we recognize, emit a
+# softer note about the sibling tool running without instructions.
+if [ "$SIBLING_EXISTS" = "0" ]; then
+    cat >&2 <<EOF
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[agents-md-edit-drift-warner] Edited: ${FILE_PATH}
+No sibling ${SIBLING_BASENAME} found in this directory.
+${SIBLING_TOOLS} will read no project instructions for this repo
+unless you create ${DIR}/${SIBLING_BASENAME}.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+EOF
+    exit 0
+fi
+
+# If the sibling exists and is the same inode (symlink), no drift
+# is possible — exit silent.
+if [ "$SIBLING_PATH" -ef "$FILE_PATH" ]; then
+    exit 0
+fi
+
+# If the two files are byte-identical right now, the edit may have
+# just brought them in sync (or they were synced before and the
+# edit was idempotent). Either way, no warning needed.
+if cmp -s "$FILE_PATH" "$SIBLING_PATH" 2>/dev/null; then
+    exit 0
+fi
+
+# Sibling exists, different content. Emit the drift warning.
+EDITED_SIZE=$(wc -c < "$FILE_PATH" 2>/dev/null || echo 0)
+SIBLING_SIZE=$(wc -c < "$SIBLING_PATH" 2>/dev/null || echo 0)
+
+if [ "$QUIET" = "1" ]; then
+    echo "[agents-md-edit-drift-warner] Drift: ${BASENAME} edited; ${SIBLING_BASENAME} now stale." >&2
+    exit 0
+fi
+
+cat >&2 <<EOF
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[agents-md-edit-drift-warner] Drift detected at edit time
+
+Edited:  ${FILE_PATH} (${EDITED_SIZE} bytes)
+Sibling: ${SIBLING_PATH} (${SIBLING_SIZE} bytes, NOT updated)
+
+The sibling instruction file did not receive this edit. The next
+session of ${SIBLING_TOOLS} will read the older ${SIBLING_BASENAME}
+rather than what ${EDITED_TOOL} now sees.
+
+Cluster 3 (AGENTS.md interop): #6235 has 5,233 reactions and
+13+ months without an official Anthropic position. Until Claude
+Code reads AGENTS.md natively, the operator-side burden is to
+keep both files in sync at edit time.
+
+Three reconciliation options at this moment:
+
+  1. Mirror the edit now. Open ${SIBLING_PATH} and apply the same
+     change while the diff is fresh in your head.
+
+  2. Symlink the two files. \`ln -sf ${FILE_PATH} ${SIBLING_PATH}\`
+     (or the reverse direction) makes future edits update both
+     at once. Caveat: if you symlink at the directory level
+     between .claude/ and .agents/, Claude Code writes .system/
+     files into the shared directory (#20820 / #31005).
+
+  3. Defer with intent. If you know you are mid-experiment and
+     do not want the sibling to track this revision yet, the
+     warning is informational only — no action required.
+
+Silence: set CC_AGENTS_MD_DRIFT_WARN_DISABLE=1.
+Compact mode: set CC_AGENTS_MD_DRIFT_WARN_QUIET=1.
+
+Companion: agents-md-sync-checker (SessionStart, PR #377) catches
+the drift at the start of the next session if you defer here.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+EOF
+
+exit 0

package/examples/agents-md-loader.sh

@@ -0,0 +1,160 @@
+#!/bin/bash
+# agents-md-loader.sh — Detect AGENTS.md in the project tree at session start
+# and surface its contents to Claude Code as a system-reminder, so the agent
+# reads it alongside (or in place of) CLAUDE.md.
+#
+# Addresses: anthropics/claude-code#6235 (Feature Request: Support AGENTS.md),
+# the highest-engagement feature request on the tracker (6,358 reactions),
+# closed as completed on 2026-08-17.
+#
+# DOES CLAUDE CODE READ AGENTS.md NOW? Measured on v2.1.233, 2026-08-21: NO.
+# The issue is closed, but AGENTS.md is still not loaded into the model's
+# context the way CLAUDE.md is. The official CHANGELOG.md (5,693 lines, up
+# to 2.1.238) does not mention AGENTS.md anywhere.
+#
+# This is easy to get wrong, so here is the method. Asking `claude -p` for a
+# token planted in AGENTS.md is NOT a valid test: the agent will often find the
+# file on its own with ls/cat and answer correctly, which looks identical to
+# native loading. Stream the transcript instead and look at the tool calls:
+#
+#   claude -p "<question>" --output-format stream-json --verbose
+#
+#   CLAUDE.md planted ... answered with no file read  -> loaded into context
+#   AGENTS.md planted ... agent ran `ls` then `cat`   -> NOT loaded; it looked
+#
+# So whether the agent sees AGENTS.md depends on whether it happens to go
+# looking, which is not something you can rely on — and it costs tool calls
+# every session when it does.
+#
+# This hook makes it deterministic instead: a SessionStart hook that
+# detects AGENTS.md (in cwd or any parent up to git root), reads its
+# contents (subject to a size cap to protect the context budget), and
+# emits a <system-reminder> so the agent reads it the same way it reads
+# CLAUDE.md.
+#
+# Precedence: the AGENTS.md specification specifies "closest file wins"
+# for monorepos with nested AGENTS.md files. This hook follows the same
+# rule — it walks upward from cwd and uses the first AGENTS.md found.
+#
+# Coexistence with CLAUDE.md: this hook does NOT replace CLAUDE.md.
+# Both files load. If both exist, both are surfaced to the agent. The
+# operator's CLAUDE.md takes precedence on Claude-specific conventions;
+# AGENTS.md provides the vendor-neutral context.
+#
+# TRIGGER: SessionStart
+# MATCHER: ""
+#
+# CONFIGURATION (environment variables):
+#   CC_AGENTS_MD_MAX_BYTES        default 16384 (16 KiB) — file size cap
+#                                  to protect context budget; AGENTS.md
+#                                  larger than this is truncated and a
+#                                  warning is appended.
+#   CC_AGENTS_MD_SEARCH_PARENTS   default "1" — walk up to git root looking
+#                                  for AGENTS.md. Set "0" to check only cwd.
+#   CC_AGENTS_MD_LOADER_DISABLE   set to "1" to disable the hook entirely.
+#
+# USAGE (settings.json):
+#   {
+#     "hooks": {
+#       "SessionStart": [{
+#         "matcher": "",
+#         "hooks": [{
+#           "type": "command",
+#           "command": "~/.claude/hooks/agents-md-loader.sh"
+#         }]
+#       }]
+#     }
+#   }
+
+set -uo pipefail
+
+[ "${CC_AGENTS_MD_LOADER_DISABLE:-0}" = "1" ] && exit 0
+
+MAX_BYTES="${CC_AGENTS_MD_MAX_BYTES:-16384}"
+SEARCH_PARENTS="${CC_AGENTS_MD_SEARCH_PARENTS:-1}"
+
+# Find AGENTS.md by walking up from cwd. Stop at:
+#   - first AGENTS.md found, OR
+#   - filesystem root, OR
+#   - top of git working tree (if inside one), OR
+#   - $HOME, whichever comes first.
+
+find_agents_md() {
+    local dir="$PWD"
+    local git_root=""
+
+    git_root=$(git rev-parse --show-toplevel 2>/dev/null || true)
+
+    while [ -n "$dir" ] && [ "$dir" != "/" ]; do
+        if [ -f "$dir/AGENTS.md" ]; then
+            printf '%s\n' "$dir/AGENTS.md"
+            return 0
+        fi
+        # Stop at git root if found.
+        [ -n "$git_root" ] && [ "$dir" = "$git_root" ] && return 1
+        # Stop at $HOME.
+        [ "$dir" = "$HOME" ] && return 1
+        # If SEARCH_PARENTS is disabled, only check cwd.
+        [ "$SEARCH_PARENTS" = "0" ] && return 1
+        dir=$(dirname "$dir")
+    done
+    return 1
+}
+
+AGENTS_MD_PATH=$(find_agents_md)
+[ -z "$AGENTS_MD_PATH" ] && exit 0  # No AGENTS.md → silent no-op.
+
+# Read the file with a byte cap. If the file is larger than MAX_BYTES,
+# truncate and append a notice so the agent knows.
+FILE_SIZE=$(wc -c < "$AGENTS_MD_PATH" 2>/dev/null || echo 0)
+TRUNCATED=""
+
+if [ "$FILE_SIZE" -gt "$MAX_BYTES" ]; then
+    CONTENT=$(head -c "$MAX_BYTES" "$AGENTS_MD_PATH" 2>/dev/null)
+    TRUNCATED="
+
+[NOTE: AGENTS.md is $FILE_SIZE bytes; truncated to $MAX_BYTES bytes by agents-md-loader. Increase CC_AGENTS_MD_MAX_BYTES or read the full file with the Read tool if you need the rest.]"
+else
+    CONTENT=$(cat "$AGENTS_MD_PATH" 2>/dev/null)
+fi
+
+[ -z "$CONTENT" ] && exit 0
+
+# Detect whether CLAUDE.md is also present (sibling or parent) so the
+# reminder can name the coexistence.
+CLAUDE_MD_SIBLING=""
+PROJECT_DIR=$(dirname "$AGENTS_MD_PATH")
+[ -f "$PROJECT_DIR/CLAUDE.md" ] && CLAUDE_MD_SIBLING="$PROJECT_DIR/CLAUDE.md"
+
+# Emit the system-reminder on stderr (SessionStart hooks use stderr for
+# context-augmenting reminders; exit 0 = non-blocking).
+
+cat >&2 <<EOF
+<system-reminder>
+AGENTS.md detected at $AGENTS_MD_PATH ($FILE_SIZE bytes).
+
+AGENTS.md is the vendor-neutral "README for agents" convention adopted by
+Codex, Cursor, Aider, Zed, VS Code, Devin, JetBrains Junie, Amp, Gemini CLI,
+GitHub Copilot, Windsurf, and 10+ other coding agents. Claude Code does
+not yet natively read this file (see anthropics/claude-code#6235). This
+hook surfaces its contents to you in the same way native CLAUDE.md loading
+would.
+
+The repository operator has chosen to keep cross-vendor context in
+AGENTS.md so the same content serves every agent that visits the repo.
+Treat the content below as project context with the same authority you
+treat CLAUDE.md content.
+$( [ -n "$CLAUDE_MD_SIBLING" ] && printf '%s\n' "
+NOTE: CLAUDE.md is also present at $CLAUDE_MD_SIBLING. Both files are
+in scope. CLAUDE.md takes precedence on Claude-Code-specific conventions
+(hook configurations, slash commands, model-specific behaviour). AGENTS.md
+governs cross-vendor project context (build commands, code style, test
+instructions, security considerations).")
+
+--- BEGIN $AGENTS_MD_PATH ---
+$CONTENT$TRUNCATED
+--- END $AGENTS_MD_PATH ---
+</system-reminder>
+EOF
+
+exit 0

package/examples/agents-md-sync-checker.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# ================================================================
+# agents-md-sync-checker.sh — Warn when AGENTS.md and CLAUDE.md drift apart
+# ================================================================
+# PURPOSE:
+#   This hook reports at session start via hookSpecificOutput /
+#   additionalContext. Without the TRIGGER header below, the
+#   installer registered it under the default PreToolUse/Bash,
+#   so it fired on every Bash call and never ran at session start.
+#
+# TRIGGER: SessionStart
+# MATCHER: ""
+# ================================================================
+
+set -u
+INPUT=$(cat)
+DELTA_PCT="${CC_AGENTS_MD_SIZE_DELTA_PCT:-20}"
+if [ -n "${CC_AGENTS_MD_FILES:-}" ]; then
+    IFS=':' read -ra AGENTS_MD_FILES <<< "$CC_AGENTS_MD_FILES"
+else
+    AGENTS_MD_FILES=(
+        "./AGENTS.md"
+        ".agents/AGENTS.md"
+    )
+fi
+if [ -n "${CC_CLAUDE_MD_FILES_FOR_SYNC:-}" ]; then
+    IFS=':' read -ra CLAUDE_MD_FILES <<< "$CC_CLAUDE_MD_FILES_FOR_SYNC"
+else
+    CLAUDE_MD_FILES=(
+        "./CLAUDE.md"
+        ".claude/CLAUDE.md"
+    )
+fi
+AGENTS_PATH=""
+AGENTS_SIZE=0
+for path in "${AGENTS_MD_FILES[@]}"; do
+    if [ -f "$path" ] && [ -r "$path" ]; then
+        AGENTS_PATH="$path"
+        AGENTS_SIZE=$(wc -c < "$path" 2>/dev/null | tr -d ' ')
+        break
+    fi
+done
+CLAUDE_PATH=""
+CLAUDE_SIZE=0
+for path in "${CLAUDE_MD_FILES[@]}"; do
+    if [ -f "$path" ] && [ -r "$path" ]; then
+        CLAUDE_PATH="$path"
+        CLAUDE_SIZE=$(wc -c < "$path" 2>/dev/null | tr -d ' ')
+        break
+    fi
+done
+[ -z "$AGENTS_PATH" ] && [ -z "$CLAUDE_PATH" ] && exit 0
+[ -z "$AGENTS_PATH" ] && exit 0
+FINDINGS=()
+if [ -z "$CLAUDE_PATH" ]; then
+    FINDINGS+=("AGENTS.md present at $AGENTS_PATH ($AGENTS_SIZE bytes) but no CLAUDE.md found. Claude Code does not read AGENTS.md natively. If you want these instructions in this Claude Code session, copy or symlink AGENTS.md to CLAUDE.md.")
+else
+    if [ "$AGENTS_PATH" -ef "$CLAUDE_PATH" ]; then
+        exit 0
+    fi
+    if cmp -s "$AGENTS_PATH" "$CLAUDE_PATH" 2>/dev/null; then
+        FINDINGS+=("AGENTS.md and CLAUDE.md have identical content but are separate files at $AGENTS_PATH and $CLAUDE_PATH. Consider replacing one with a symlink to the other to prevent future drift.")
+    else
+        if [ "$AGENTS_SIZE" -eq 0 ] || [ "$CLAUDE_SIZE" -eq 0 ]; then
+            PCT_DELTA=100
+        else
+            if [ "$AGENTS_SIZE" -gt "$CLAUDE_SIZE" ]; then
+                PCT_DELTA=$(awk -v a="$AGENTS_SIZE" -v c="$CLAUDE_SIZE" 'BEGIN { printf "%d", (a - c) * 100 / a }')
+            else
+                PCT_DELTA=$(awk -v a="$AGENTS_SIZE" -v c="$CLAUDE_SIZE" 'BEGIN { printf "%d", (c - a) * 100 / c }')
+            fi
+        fi
+        if [ "$PCT_DELTA" -ge "$DELTA_PCT" ]; then
+            FINDINGS+=("AGENTS.md ($AGENTS_PATH: $AGENTS_SIZE bytes) and CLAUDE.md ($CLAUDE_PATH: $CLAUDE_SIZE bytes) differ by $PCT_DELTA% in size. Likely drift between the two instruction sources.")
+        else
+            FINDINGS+=("AGENTS.md and CLAUDE.md present at $AGENTS_PATH ($AGENTS_SIZE bytes) and $CLAUDE_PATH ($CLAUDE_SIZE bytes), close in size ($PCT_DELTA% delta) but content differs. Confirm intentional divergence or sync.")
+        fi
+    fi
+fi
+[ ${#FINDINGS[@]} -eq 0 ] && exit 0
+MSG="DETECTED: AGENTS.md / CLAUDE.md state requires operator review.
+Multiple coding agents (Codex, Amp, Cursor, Aider, others) are converging on AGENTS.md as a shared instruction standard. Claude Code does not read AGENTS.md natively as of this session — the only operator-side mitigation while issue #6235 (5,268 reactions, 13+ months open) is unresolved is to maintain CLAUDE.md alongside.
+Findings:"
+for finding in "${FINDINGS[@]}"; do
+    MSG="$MSG
+  - $finding"
+done
+MSG="$MSG
+Mitigation patterns:
+  1. Single source of truth: write instructions in CLAUDE.md, symlink AGENTS.md to it (or vice versa). Other agents read AGENTS.md; Claude Code reads CLAUDE.md; one edit updates both. Run scripts/agents-md-sync-setup.sh to do this safely in one command (dry-run by default; backs up any file before replacing it; refuses to touch the files when their contents differ).
+  2. Git pre-commit hook that fails when AGENTS.md and CLAUDE.md content drifts.
+  3. Pick one tool and remove the other file. Multi-agent workflows are not required.
+See https://github.com/anthropics/claude-code/issues/6235 for the upstream feature request thread.
+This hook is advisory only. The session continues normally."
+jq -n --arg msg "$MSG" '
+{
+    "hookSpecificOutput": {
+        "hookEventName": "SessionStart",
+        "additionalContext": $msg
+    }
+}'
+exit 0