cc-safe-setup 29.7.0 → 30.0.4

package/examples/multi-file-plan-routing-gate.sh

@@ -0,0 +1,192 @@
+#!/bin/bash
+# multi-file-plan-routing-gate.sh — Refuse Write/Edit when the current session
+# has touched N or more distinct files without a written plan, route the
+# work through plan-mode before further writes land.
+#
+# Solves: #60506 — supplier-side recommendation #7 in the model's first-person
+# self-report:
+#
+#   "Automatic routing of three-or-more-file changes into a plan-mode path.
+#    Currently I can sprawl across the codebase without writing a plan first.
+#    The hook should refuse the third file-touching Write until a plan exists,
+#    and then enforce the plan as the contract for the remaining touches."
+#
+# This is the seventh and final operator-side implementation of the seven
+# recommendations Semih extracted from claude-opus-4-7's self-report. The
+# preceding six are shipped or in PR:
+#
+#   1. Chain templates as architectural rules → CLAUDE.md hook frameworks
+#   2. Drift detector (3-correction repeat)   → same-correction-arrest.sh
+#   3. Failure-mode re-injection at Write     → claude-md-reinjector.sh
+#   4. Closure-word verification gate         → closure-word-verify-gate.sh
+#   5. Evidence requirements for "tested"     → evidence-claim-gate.sh (PR #256)
+#   6. Apology weighting at training time     → supplier-only
+#   7. THIS HOOK — plan-mode routing for 3+ file changes
+#
+# HOW IT WORKS:
+#   1. Tracks distinct file_path values per session in a small state file.
+#   2. On each PreToolUse Write/Edit/MultiEdit, adds the file_path to the
+#      session's set.
+#   3. When the count reaches CC_PLAN_GATE_THRESHOLD (default 3), checks
+#      for the presence of a plan file at $PLAN_DIR/<session>.md.
+#   4. If no plan file exists, refuses the Write with exit 2 + system reminder
+#      asking the assistant to write the plan first.
+#   5. Once the plan file appears, subsequent writes pass through silently.
+#   6. Stale session state (older than 7 days) is purged automatically.
+#
+# DESIGN PRINCIPLE: don't block the work, route it. The hook does not
+# prevent multi-file changes; it requires that they be planned before being
+# executed. The plan file is the contract; the writes are the contract's
+# fulfillment. The arrest happens at the *third* file (configurable), not
+# the first — single-file and two-file changes are common and not the
+# failure mode #60506 is describing.
+#
+# Related Issues:
+#   #60506 (@zean89,   2026-05-19) — original report, recommendation 7
+#   #60226 (@suwayama, 2026-05-18) — recognition-without-arrest framework
+#   #60177 (@mike-prokhorov)       — twelve days, fifty-one commits, no plan
+#
+# TRIGGER: PreToolUse
+# MATCHER: Write|Edit|MultiEdit
+#
+# CONFIGURATION (environment variables):
+#   CC_PLAN_GATE_THRESHOLD     default 3 — file count that triggers the gate
+#   CC_PLAN_GATE_STATE_DIR     default /tmp/cc-plan-gate
+#   CC_PLAN_GATE_PLAN_DIR      default .claude/plans
+#   CC_PLAN_GATE_DISABLE       set to "1" to disable the gate entirely
+#   CC_PLAN_GATE_STATE_TTL     default 7 (days) — stale state cleanup window
+#
+# USAGE (settings.json):
+#   {
+#     "hooks": {
+#       "PreToolUse": [{
+#         "matcher": "Write|Edit|MultiEdit",
+#         "hooks": [{
+#           "type": "command",
+#           "command": "~/.claude/hooks/multi-file-plan-routing-gate.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-multi-file-plan-routing-gate-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [multi-file-plan-routing-gate]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+[ "${CC_PLAN_GATE_DISABLE:-0}" = "1" ] && exit 0
+
+# OPT-IN: this gate BLOCKS the 3rd+ file Write/Edit in a session when no plan
+# file exists. Ordinary multi-file work (refactors, features touching 3+ files)
+# would be arrested by default, so it is off unless explicitly enabled.
+# Set CC_PLAN_GATE_ENABLE=1 to turn it on.
+[ "${CC_PLAN_GATE_ENABLE:-0}" = "1" ] || exit 0
+
+INPUT=$(cat 2>/dev/null || true)
+[ -z "$INPUT" ] && exit 0
+
+THRESHOLD="${CC_PLAN_GATE_THRESHOLD:-3}"
+STATE_DIR="${CC_PLAN_GATE_STATE_DIR:-/tmp/cc-plan-gate}"
+PLAN_DIR="${CC_PLAN_GATE_PLAN_DIR:-.claude/plans}"
+TTL_DAYS="${CC_PLAN_GATE_STATE_TTL:-7}"
+
+mkdir -p "$STATE_DIR" 2>/dev/null || true
+
+# Stale state cleanup. Purge session files older than TTL_DAYS.
+find "$STATE_DIR" -type f -mtime "+${TTL_DAYS}" -delete 2>/dev/null || true
+
+# Extract session_id and file_path from input.
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '
+    .session_id //
+    .stop_input.session_id //
+    .transcript[-1].session_id //
+    "default"
+' 2>/dev/null)
+[ -z "$SESSION_ID" ] && SESSION_ID="default"
+
+# Sanitize session_id for filename use
+SAFE_SESSION=$(printf '%s' "$SESSION_ID" | tr -c '[:alnum:]_-' '_' | head -c 64)
+
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '
+    .tool_input.file_path //
+    empty
+' 2>/dev/null)
+
+# No file_path → nothing to track (e.g. MultiEdit without path, fall back
+# to tool_input.file as a fallback)
+[ -z "$FILE_PATH" ] && FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file // empty' 2>/dev/null)
+[ -z "$FILE_PATH" ] && exit 0
+
+STATE_FILE="$STATE_DIR/${SAFE_SESSION}.files"
+
+# Add file_path to the session's set (deduplicated).
+touch "$STATE_FILE"
+if ! grep -Fxq "$FILE_PATH" "$STATE_FILE" 2>/dev/null; then
+    echo "$FILE_PATH" >> "$STATE_FILE"
+fi
+
+# Count distinct files touched this session.
+FILE_COUNT=$(wc -l < "$STATE_FILE" 2>/dev/null | tr -d ' ')
+FILE_COUNT="${FILE_COUNT:-0}"
+
+# Below threshold → nothing to gate.
+if [ "$FILE_COUNT" -lt "$THRESHOLD" ]; then
+    exit 0
+fi
+
+# At-or-above threshold. Is there a plan file for this session?
+PLAN_FILE="$PLAN_DIR/${SAFE_SESSION}.md"
+PLAN_FILE_ALT="$PLAN_DIR/plan-${SAFE_SESSION}.md"
+PLAN_FILE_GENERIC="$PLAN_DIR/plan.md"
+
+if [ -f "$PLAN_FILE" ] || [ -f "$PLAN_FILE_ALT" ] || [ -f "$PLAN_FILE_GENERIC" ]; then
+    # Plan exists — work has been routed, allow.
+    exit 0
+fi
+
+# No plan. Refuse the Write/Edit and ask the assistant to write a plan.
+cat >&2 <<EOF
+<system-reminder>
+MULTI-FILE CHANGE WITHOUT A PLAN — this session has now touched $FILE_COUNT
+distinct files via Write/Edit/MultiEdit, and no plan file exists at
+$PLAN_FILE.
+
+This is the failure mode documented in #60506 (recommendation 7): the model
+sprawls across the codebase without writing a plan first, and the resulting
+changes are scattered, partially-wired, or contradict each other. The cost
+of an unplanned multi-file change lands on the operator at review time.
+
+The files touched so far in this session:
+$(sed 's/^/  - /' "$STATE_FILE" 2>/dev/null | head -20)
+
+Before the next Write/Edit lands, do one of the following:
+
+  1. Write a plan to $PLAN_FILE that lists the goal, the files involved,
+     the order of changes, and the verification step for each file. Once
+     the plan file exists, this gate auto-clears and writes proceed silently.
+
+  2. If the changes are unrelated and a unified plan is not appropriate,
+     split the work across separate sessions — one task per session, gate
+     resets at session end (TTL 7 days).
+
+  3. If this is a refactor where multi-file scope was inherent from the
+     start, the plan can be one or two paragraphs — the gate's purpose
+     is to require explicit forethought, not extensive documentation.
+
+To disable this gate for design discussions, retrospectives, or sessions
+where multi-file scope is not the failure mode you are guarding against,
+set CC_PLAN_GATE_DISABLE=1 in your environment. The threshold can be
+raised via CC_PLAN_GATE_THRESHOLD (default 3).
+</system-reminder>
+EOF
+
+exit 2

package/examples/multi-vendor-concurrent-warner.sh

@@ -0,0 +1,108 @@
+#!/bin/bash
+# ================================================================
+# multi-vendor-concurrent-warner.sh — Warn when another AI coding
+#   CLI (Codex, Gemini, Cursor, Aider, Amp, ...) is running at the
+#   same time as Claude Code, so concurrent edits to the same repo
+#   do not silently collide.
+# ================================================================
+# PURPOSE:
+#   A growing number of operators run several AI coding tools in
+#   parallel — Claude Code plus Codex, Gemini CLI, Cursor's agent,
+#   Aider, Amp, and others — pointed at the same repository. Two
+#   failure modes follow, and neither tool can see the other:
+#     1. Conflicting edits. Two agents edit the same file; one
+#        overwrites the other, or the repo lands in a broken state
+#        (reported: dozens of type errors after a parallel run).
+#     2. Cost is invisible. Each vendor bills separately; the
+#        combined spend across tools is not shown in any one tool,
+#        and parallel runs multiply it (operators report 3-5x).
+#
+#   Every other concurrency hook in cc-safe-setup bounds Claude
+#   Code's OWN subagents (max-concurrent-agents, parallel-edit-guard,
+#   subagent-budget-guard, ...). None of them can see a SEPARATE
+#   vendor's process. This hook fills that gap: at session start it
+#   checks the process table for other AI CLIs and, if it finds one,
+#   prints a one-time advisory so the operator coordinates scope and
+#   watches combined cost.
+#
+# UPSTREAM / CONTEXT:
+#   The multi-vendor parallel-operation pattern (Claude Code + Codex
+#   + Gemini + Grok) is a real and growing operator workflow. This
+#   hook is advisory only — it never blocks and never inspects the
+#   other tool; it only notes that it is running.
+#
+# TRIGGER: SessionStart   (also safe as PreToolUse)
+#
+# CONFIGURATION (env vars):
+#   CC_MULTI_VENDOR_PROCS    Space-separated process names to treat
+#                            as other AI CLIs. Default covers the
+#                            common ones. Claude's own process is
+#                            never matched.
+#   CC_MULTI_VENDOR_PS       Override the command used to list
+#                            process names (default: ps -eo comm=).
+#   CC_MULTI_VENDOR_PS_OUTPUT  Pre-supplied process listing (tests).
+# ================================================================
+
+set -u
+
+# Read and discard stdin (hook protocol); this hook does not use it.
+cat > /dev/null 2>&1 || true
+
+DEFAULT_PROCS="codex gemini cursor-agent cursor-agent-cli aider amp ampcode grok cline continue goose qwen"
+PROCS="${CC_MULTI_VENDOR_PROCS:-$DEFAULT_PROCS}"
+
+# Obtain the list of running process names.
+if [ -n "${CC_MULTI_VENDOR_PS_OUTPUT:-}" ]; then
+    PS_LIST="$CC_MULTI_VENDOR_PS_OUTPUT"
+else
+    PS_CMD="${CC_MULTI_VENDOR_PS:-ps -eo comm=}"
+    PS_LIST="$($PS_CMD 2>/dev/null)"
+fi
+
+[ -z "$PS_LIST" ] && exit 0
+
+# Match each candidate as a whole basename token so "cursor-agent"
+# does not match unrelated names. We compare against the basename of
+# each process entry to tolerate full paths in some ps formats.
+FOUND=""
+while IFS= read -r raw; do
+    [ -z "$raw" ] && continue
+    name="${raw##*/}"          # basename
+    name="${name%% *}"          # strip args if present
+    for p in $PROCS; do
+        if [ "$name" = "$p" ]; then
+            case " $FOUND " in
+                *" $p "*) : ;;          # already recorded
+                *) FOUND="$FOUND $p" ;;
+            esac
+        fi
+    done
+done <<EOF
+$PS_LIST
+EOF
+
+FOUND="${FOUND# }"
+[ -z "$FOUND" ] && exit 0
+
+MSG="DETECTED: another AI coding CLI appears to be running alongside Claude Code: ${FOUND}.
+Running multiple AI tools against the same repository at once has two failure modes that neither tool can see on its own:
+  - Conflicting edits: two agents change the same file; one silently overwrites the other, or the repo lands half-edited.
+  - Combined cost is invisible: each vendor bills separately, so no single tool shows your total spend, and parallel runs multiply it.
+Operator-side mitigations:
+  1. Give each tool a disjoint scope (different directories or files) and commit frequently so collisions surface in git, not at runtime.
+  2. Track spend per vendor separately; assume the combined monthly cost, not any single tool's number.
+  3. Prefer a clear lead tool for edits and use the others for read-only review while both are live.
+This hook is advisory only — it does not read or stop the other tool. The session continues normally."
+
+if command -v jq > /dev/null 2>&1; then
+    jq -n --arg msg "$MSG" '
+    {
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": $msg
+        }
+    }'
+else
+    echo "$MSG" >&2
+fi
+exit 0

package/examples/multi-window-auth-drift-detector.sh

@@ -0,0 +1,183 @@
+#!/bin/bash
+# multi-window-auth-drift-detector.sh — Detect on-disk credentials drift mid-session
+# (Cluster 19 candidate, axis 19E — multi-window /account state inconsistency)
+#
+# Background:
+#   Cluster 19 axis 19E documents a class of authentication failures unique to
+#   operators running multiple Claude Code windows in parallel. The structural
+#   shape: Window A authenticates with Account X and starts a long session.
+#   While Window A is mid-session, Window B either (a) logs in with Account Y,
+#   (b) logs out, or (c) re-authenticates — any action that rewrites the
+#   on-disk credential store. Window A keeps working from the cached in-memory
+#   token, but `/account` in Window A now reports "Not authenticated" while
+#   the same dialog's USAGE panel still shows real quota consumption.
+#
+#   Anchor case: #62790 — "/account shows 'Not authenticated' in older windows
+#   after another window logs in/out, while Usage bars still populate".
+#
+#   The contradiction is observable: same dialog, "Not authenticated" + live
+#   session quota bars. The operator does not know if their next substantive
+#   tool call will succeed or fail.
+#
+#   This hook is a PostToolUse advisory that fires when:
+#     - the credentials file has been modified since the session start, AND
+#     - the operator has not already seen the advisory in this session
+#
+#   The advisory does not block the tool call. It surfaces the drift so the
+#   operator can run /account, decide whether the in-memory auth is still the
+#   intended account, and re-auth deliberately if needed.
+#
+#   Reference:
+#     https://gist.github.com/yurukusa/58cb17bfda4d5ab31bd804809809d22f (auth cluster field guide)
+#
+# Why a hook helps:
+#   Without the advisory, the failure mode is: Window A operator continues
+#   working, hits a 401 mid-task hours later, loses the in-flight work. With
+#   the advisory, the operator learns at the next tool call that the on-disk
+#   credentials have drifted, and can verify deliberately rather than discover
+#   the lapse during a costly task.
+#
+# When this hook does NOT emit anything:
+#   - CC_AUTH_DRIFT_DISABLE=1
+#   - CC_AUTH_DRIFT_QUIET=1
+#   - no credentials file exists at any known path
+#   - the credentials file mtime is older than the session start
+#   - the advisory has already fired in this session
+#
+# Hook config (settings.json):
+# {
+#   "hooks": {
+#     "PostToolUse": [{
+#       "matcher": "",
+#       "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/multi-window-auth-drift-detector.sh" }]
+#     }]
+#   }
+# }
+#
+# Env vars:
+#   CC_AUTH_DRIFT_DISABLE=1          — never emit
+#   CC_AUTH_DRIFT_QUIET=1            — silent (process but never write to stderr)
+#   CC_AUTH_DRIFT_CRED_FILE=<path>   — credentials file path override (tests)
+#   CC_AUTH_DRIFT_SESSION_START=<ep> — session start epoch override (tests)
+#   CC_AUTH_DRIFT_STATE_DIR=<path>   — one-shot state dir override (default ~/.claude/state)
+#   CC_AUTH_DRIFT_SESSION_ID=<id>    — session id override (tests)
+#
+# Design notes:
+#   - Opt-out. The advisory is specific (credentials file changed since
+#     session start) and the cost of a missed advisory (silent 401 mid-task)
+#     exceeds the cost of a false positive (one stderr advisory the operator
+#     dismisses).
+#   - One-shot per session. The advisory fires once. Further drifts in the
+#     same session do not re-fire — the operator already knows.
+#   - Never blocks. Exit always 0. The auth recovery is operator-action.
+#   - Looks at multiple known credential file paths. The exact path varies
+#     across Claude Code versions and platforms; the hook checks each in
+#     order and uses the first that exists.
+
+set -u
+
+if [[ "${CC_AUTH_DRIFT_DISABLE:-0}" = "1" ]]; then
+    exit 0
+fi
+
+CRED_FILE="${CC_AUTH_DRIFT_CRED_FILE:-}"
+if [[ -z "$CRED_FILE" ]]; then
+    for candidate in \
+        "$HOME/.config/claude/auth.json" \
+        "$HOME/.config/anthropic/configs/default.json" \
+        "$HOME/.claude/credentials.json" \
+        "$HOME/.claude/.credentials.json"; do
+        if [[ -f "$candidate" ]]; then
+            CRED_FILE="$candidate"
+            break
+        fi
+    done
+fi
+
+if [[ -z "$CRED_FILE" ]] || [[ ! -f "$CRED_FILE" ]]; then
+    exit 0
+fi
+
+STATE_DIR="${CC_AUTH_DRIFT_STATE_DIR:-$HOME/.claude/state}"
+mkdir -p "$STATE_DIR" 2>/dev/null
+
+SESSION_ID="${CC_AUTH_DRIFT_SESSION_ID:-${CLAUDE_SESSION_ID:-default}}"
+GUARD_FILE="$STATE_DIR/auth-drift-${SESSION_ID}.fired"
+START_FILE="$STATE_DIR/auth-drift-${SESSION_ID}.start"
+
+if [[ -f "$GUARD_FILE" ]]; then
+    exit 0
+fi
+
+# Read or record session start epoch. The first hook firing of a session
+# records the start time; subsequent firings compare the credentials mtime
+# against it.
+SESSION_START="${CC_AUTH_DRIFT_SESSION_START:-}"
+if [[ -z "$SESSION_START" ]]; then
+    if [[ -f "$START_FILE" ]]; then
+        SESSION_START=$(cat "$START_FILE" 2>/dev/null)
+    fi
+    if [[ -z "$SESSION_START" ]] || ! [[ "$SESSION_START" =~ ^[0-9]+$ ]]; then
+        date +%s > "$START_FILE" 2>/dev/null
+        exit 0
+    fi
+fi
+
+# Get credentials file mtime in epoch seconds. Linux uses stat -c %Y;
+# macOS uses stat -f %m. Try both for portability.
+CRED_MTIME=$(stat -c %Y "$CRED_FILE" 2>/dev/null)
+if [[ -z "$CRED_MTIME" ]] || ! [[ "$CRED_MTIME" =~ ^[0-9]+$ ]]; then
+    CRED_MTIME=$(stat -f %m "$CRED_FILE" 2>/dev/null)
+fi
+if [[ -z "$CRED_MTIME" ]] || ! [[ "$CRED_MTIME" =~ ^[0-9]+$ ]]; then
+    exit 0
+fi
+
+# If credentials were not modified since the session started, no drift.
+if (( CRED_MTIME <= SESSION_START )); then
+    exit 0
+fi
+
+# Drift detected. Mark one-shot guard.
+touch "$GUARD_FILE" 2>/dev/null
+
+if [[ "${CC_AUTH_DRIFT_QUIET:-0}" = "1" ]]; then
+    exit 0
+fi
+
+GAP=$(( CRED_MTIME - SESSION_START ))
+
+cat >&2 <<EOF
+
+────────────────────────────────────────────────────────────────────
+  Auth advisory — Cluster 19 axis 19E (multi-window drift)
+────────────────────────────────────────────────────────────────────
+  Credentials file modified ${GAP}s after this session started:
+    ${CRED_FILE}
+
+  The Cluster 19 axis 19E pattern: when another Claude Code window
+  logs in/out or re-authenticates, this window's in-memory token may
+  silently diverge from on-disk state. /account in this window can
+  report "Not authenticated" while the USAGE quota bars still show
+  live consumption. The next substantive tool call may 401 mid-task.
+
+  Anchor case: #62790.
+
+  Recommended check before the next costly tool call:
+
+    /account
+
+  If "Auth method" reports "Not authenticated" but USAGE bars are
+  populated, the in-memory token is stale. Close all Claude Code
+  windows, then re-authenticate in a single window and start fresh
+  sessions — re-using the existing window will re-surface the drift.
+
+  Field guide: https://gist.github.com/yurukusa/58cb17bfda4d5ab31bd804809809d22f
+
+  (This advisory fires once per session. To disable:
+   export CC_AUTH_DRIFT_DISABLE=1)
+────────────────────────────────────────────────────────────────────
+
+EOF
+
+exit 0