cc-safe-setup 29.7.0 → 30.0.4

package/examples/context-compact-advisor.sh

@@ -1,11 +1,38 @@
+#!/bin/bash
 INPUT=$(cat)
-COUNTER="/tmp/cc-tool-count-$$"
+__CC_HOOK_INPUT="$INPUT"
+# --- セッション識別子でファイルを分ける (2026-08-09 修正) ---
+# 旧実装は "$$" を使っていたが、$$ はこのスクリプト自身のPIDで呼び出しごとに変わるため、
+# 状態が一度も持続しなかった(実測: 200回呼ぶとファイルが200個でき、中身は全部 1)。
+__CC_SID=""
+if [ -n "${__CC_HOOK_INPUT:-}" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    __CC_SID=$(printf '%s' "$__CC_HOOK_INPUT" | jq -r '.session_id // .sessionId // empty' 2>/dev/null)
+  fi
+  if [ -z "$__CC_SID" ] && command -v python3 >/dev/null 2>&1; then
+    __CC_SID=$(printf '%s' "$__CC_HOOK_INPUT" | python3 -c 'import sys,json
+try:
+    d=json.load(sys.stdin); print(d.get("session_id") or d.get("sessionId") or "")
+except Exception: print("")' 2>/dev/null)
+  fi
+fi
+if [ -n "$__CC_SID" ]; then
+  __CC_KEY=$(printf '%s' "$__CC_SID" | tr -c 'A-Za-z0-9_-' '_' | cut -c1-64)
+else
+  __CC_KEY="nosession-$(date +%Y%m%d)"
+fi
+# --- ここまで ---
+
+COUNTER="/tmp/cc-tool-count-$__CC_KEY"
 COUNT=$(cat "$COUNTER" 2>/dev/null || echo 0)
 COUNT=$((COUNT + 1))
 echo "$COUNT" > "$COUNTER"
 THRESHOLD="${CC_COMPACT_THRESHOLD:-50}"
 if [ "$((COUNT % THRESHOLD))" -eq 0 ]; then
-    TRANSCRIPT=$(ls -t ~/.claude/projects/*/sessions/*/transcript.jsonl 2>/dev/null | head -1)
+    # 記録の場所を推測しない（旧: projects/*/sessions/*/transcript.jsonl は実在せず、
+    # glob が空のまま黙って何も助言しなかった）。
+    TRANSCRIPT=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+    [ -f "$TRANSCRIPT" ] || TRANSCRIPT=$(ls -t "$HOME"/.claude/projects/*/*.jsonl 2>/dev/null | head -1)
     if [ -f "$TRANSCRIPT" ]; then
         SIZE_KB=$(($(wc -c < "$TRANSCRIPT") / 1024))
         if [ "$SIZE_KB" -gt 200 ]; then

package/examples/context-length-budget.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# context-length-budget.sh — long-context retrieval regression guard (Incident 6)
+# Why: Opus 4.7 shows significant retrieval accuracy regressions above 200K
+#      tokens of context (MRCR -46pt, 256k-8-needle -32.7pt). This hook
+#      tracks cumulative input-token usage across a session and emits an
+#      advisory when the budget threshold is crossed, so you can split the
+#      workflow before results start degrading. The same 200K line is also a
+#      billing-tier boundary on 1M-context models (the 200k-1M tier bills at a
+#      higher rate, #65870), so the advisory doubles as a cost warning when
+#      auto-compaction fails to fire and a session silently grows past it.
+# Event: PreToolUse  MATCHER: "*"
+# Action: Read the latest usage total from the transcript, append to the
+#         session's context-budget log, and warn once per session when the
+#         cumulative input tokens cross the budget line.
+#
+# Environment:
+#   CONTEXT_BUDGET_THRESHOLD    tokens above which to warn (default 200000)
+#
+# The threshold is advisory, not absolute. Sessions can run above 200K and
+# perform fine if retrieval is not multi-round. Treat the alert as a reason
+# to verify accuracy, not a reason to abort.
+
+set -u
+
+THRESHOLD="${CONTEXT_BUDGET_THRESHOLD:-200000}"
+LOG_DIR="${HOME}/.claude/logs"
+mkdir -p "$LOG_DIR" 2>/dev/null
+
+INPUT=$(cat)
+
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // "unknown"' 2>/dev/null)
+[ "$SESSION_ID" = "unknown" ] && exit 0
+
+TRANSCRIPT=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+[ -z "$TRANSCRIPT" ] && exit 0
+[ ! -r "$TRANSCRIPT" ] && exit 0
+
+# Read the most recent usage record and compute cumulative input = input +
+# cache_read + cache_creation. cache_read counts against the context window
+# even when it did not cost extra tokens, because retrieval happens over the
+# reconstructed context.
+LAST_USAGE=$(tac "$TRANSCRIPT" 2>/dev/null | grep -m1 '"usage"' || true)
+[ -z "$LAST_USAGE" ] && exit 0
+
+INPUT_TOK=$(printf '%s' "$LAST_USAGE" | jq -r '.message.usage.input_tokens // .usage.input_tokens // 0' 2>/dev/null)
+CACHE_READ=$(printf '%s' "$LAST_USAGE" | jq -r '.message.usage.cache_read_input_tokens // .usage.cache_read_input_tokens // 0' 2>/dev/null)
+CACHE_CREATE=$(printf '%s' "$LAST_USAGE" | jq -r '.message.usage.cache_creation_input_tokens // .usage.cache_creation_input_tokens // 0' 2>/dev/null)
+
+INPUT_TOK=${INPUT_TOK:-0}
+CACHE_READ=${CACHE_READ:-0}
+CACHE_CREATE=${CACHE_CREATE:-0}
+
+CUMULATIVE=$((INPUT_TOK + CACHE_READ + CACHE_CREATE))
+
+LOG_FILE="${LOG_DIR}/context-budget-${SESSION_ID}.log"
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+printf '%s\t%s\t%s\t%s\t%s\n' "$TS" "$CUMULATIVE" "$INPUT_TOK" "$CACHE_READ" "$CACHE_CREATE" >> "$LOG_FILE"
+
+# Warn once per session when the threshold is first crossed. Track with a
+# sentinel file so we do not re-warn on every subsequent turn.
+SENTINEL="${LOG_DIR}/context-budget-${SESSION_ID}.warned"
+if [ "$CUMULATIVE" -gt "$THRESHOLD" ] && [ ! -f "$SENTINEL" ]; then
+  echo "⚠ context-length-budget: $CUMULATIVE tokens in session context (threshold ${THRESHOLD})" >&2
+  echo "  Opus 4.7 shows retrieval accuracy drops above 200K (MRCR -46pt). Consider splitting the workflow or running /compact." >&2
+  echo "  Cost: on 1M-context models, crossing 200K also moves requests into the higher-priced 200k-1M billing tier (#65870), so a long session can silently bill at the premium rate when auto-compaction does not fire." >&2
+  touch "$SENTINEL"
+fi
+
+exit 0

package/examples/context-threshold-alert.sh

@@ -18,6 +18,18 @@
 # TRIGGER: PostToolUse
 # MATCHER: "" (all tools — checks context on every call)
 
+# 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-context-threshold-alert-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [context-threshold-alert]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
 INPUT=$(cat)
 
 # Extract context percentage from tool output if available

package/examples/context-usage-drift-alert.sh

@@ -5,29 +5,57 @@
 #      ツール呼び出し回数でコンテキスト消費を推定し、警告する。
 # Event: PostToolUse  MATCHER: ""
 # Action: セッション内のツール呼び出し回数が閾値を超えたら警告
+#
+# 2026-08-09 修正: カウンターがセッション単位で分かれていなかった。
+#   旧実装は "/tmp/cc-context-usage-counter-$$" を先に見ていたが、$$ は
+#   このスクリプト自身のPIDで**呼び出しごとに変わる**ため、そのファイルは
+#   決して存在せず、常に日付単位のフォールバックへ落ちていた。
+#   結果、カウンターはその日の全セッションで共有され、しかも判定が -eq の
+#   完全一致だったので、150を一度超えると**その日はもう二度と鳴らなかった**。
+#   実測(隔離HOME): 160回呼ぶと 50/100/150 で3回発火するが、続けて別セッション
+#   相当の160回を呼ぶと発火は0回(カウンターは160→320と進むだけ)。
+#   自律運用では1日に何本もセッションが立つので、2本目以降は無警告だった。
+#   修正: hookの入力JSONの session_id でカウンターを分ける。閾値の判定は
+#   「跨いだ回だけ鳴らす」形にして、-eq の取りこぼしも塞ぐ。
 
-COUNTER_FILE="/tmp/cc-context-usage-counter-$$"
-# セッションPIDが変わると新しいカウンターになる
-# フォールバック: 親PIDでグループ化
-if [ ! -f "$COUNTER_FILE" ]; then
-  COUNTER_FILE="/tmp/cc-context-usage-counter-$(date +%Y%m%d)"
+INPUT=$(cat 2>/dev/null)
+SESSION_ID=""
+if [ -n "$INPUT" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // .sessionId // empty' 2>/dev/null)
+  elif command -v python3 >/dev/null 2>&1; then
+    SESSION_ID=$(printf '%s' "$INPUT" | python3 -c 'import sys,json;d=json.load(sys.stdin);print(d.get("session_id") or d.get("sessionId") or "")' 2>/dev/null)
+  fi
 fi
 
+# session_id が取れない場合だけ日付へ落ちる。落ちたことが分かるよう接尾辞を分ける
+# (旧実装はここが既定になっていて、しかも黙っていた)
+if [ -n "$SESSION_ID" ]; then
+  KEY=$(printf '%s' "$SESSION_ID" | tr -c 'A-Za-z0-9_-' '_' | cut -c1-64)
+else
+  KEY="nosession-$(date +%Y%m%d)"
+fi
+COUNTER_FILE="/tmp/cc-context-usage-counter-$KEY"
+
 COUNT=$(cat "$COUNTER_FILE" 2>/dev/null || echo "0")
+case "$COUNT" in ''|*[!0-9]*) COUNT=0 ;; esac
+PREV=$COUNT
 COUNT=$((COUNT + 1))
 echo "$COUNT" > "$COUNTER_FILE"
 
-# 50回: 注意喚起、100回: 強い警告、150回: compact推奨
-if [ "$COUNT" -eq 50 ]; then
-  echo "📊 Session checkpoint: $COUNT tool calls. Context may be growing large." >&2
-  echo "Run /cost to check actual usage. UI display may undercount by 2x (#50204)." >&2
-elif [ "$COUNT" -eq 100 ]; then
+# 閾値を「跨いだ」回だけ鳴らす。PostToolUse が数を飛ばしても取りこぼさない
+crossed() { [ "$PREV" -lt "$1" ] && [ "$COUNT" -ge "$1" ]; }
+
+if crossed 150; then
+  echo "🚨 VERY HIGH CONTEXT: $COUNT tool calls. Auto-compact likely imminent." >&2
+  echo "Save important state to files NOW. Run /compact manually to control what's kept." >&2
+elif crossed 100; then
   echo "⚠ HIGH CONTEXT USAGE: $COUNT tool calls this session." >&2
   echo "UI may show ~50% when actual usage is near 100%. Consider /compact." >&2
   echo "Unexpected auto-compact can erase your working context. See: #50204" >&2
-elif [ "$COUNT" -eq 150 ]; then
-  echo "🚨 VERY HIGH CONTEXT: $COUNT tool calls. Auto-compact likely imminent." >&2
-  echo "Save important state to files NOW. Run /compact manually to control what's kept." >&2
+elif crossed 50; then
+  echo "📊 Session checkpoint: $COUNT tool calls. Context may be growing large." >&2
+  echo "Run /cost to check actual usage. UI display may undercount by 2x (#50204)." >&2
 fi
 
 exit 0

package/examples/conversation-history-guard.sh

@@ -39,6 +39,18 @@
 
 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-conversation-history-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [conversation-history-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
 [ "${CC_ALLOW_HISTORY_ACCESS:-0}" = "1" ] && exit 0
 
 INPUT=$(cat)

package/examples/core-file-protect-guard.sh

@@ -23,6 +23,18 @@
 #   Default: "*rules*:*config*:*core*"
 # ================================================================
 
+# 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-core-file-protect-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [core-file-protect-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/cost-incident-self-audit.sh

@@ -0,0 +1,162 @@
+#!/bin/bash
+# cost-incident-self-audit.sh — Tell me which real Claude Code cost accidents
+#   my current setup is still exposed to
+#
+# This is NOT a hook — it is a one-shot diagnostic you run by hand:
+#
+#     bash examples/cost-incident-self-audit.sh
+#
+# Why this exists: the cost/billing cluster is the single largest pain cluster
+# in the Claude Code tracker (200+ open issues), and the danger is not "my bill
+# is a bit high" — it is sudden, irreversible loss: a fan-out of pushes burning
+# a month of GitHub Actions minutes in 3 hours (#65944), a research loop running
+# ~98 WebFetch calls before anyone notices (#65684), an oversized image retried
+# until cost is ~35x (#65636), 1M-context credits draining without opt-in (#64445).
+# Generic cost trackers and the official spend page tell you what you ALREADY
+# spent. None of them tell you which of these specific accidents your setup has
+# no guard against *before* one happens. That is the gap this fills.
+#
+# It only reports what it can actually verify in your settings + environment.
+# It never edits anything, never phones home, and fails open: if it cannot read
+# something it stays quiet rather than guessing. Every finding cites the real
+# issue it comes from so you can read the incident yourself.
+#
+# Always exits 0 (it is a report, not a gate). The exposure count is in the
+# output and, with --json, in the "exposures" field. CC_COST_AUDIT_SETTINGS
+# overrides the settings glob (mainly for testing).
+
+set -u
+
+JSON=0
+for a in "$@"; do
+    case "$a" in
+        --json) JSON=1 ;;
+        -h|--help)
+            echo "Usage: bash cost-incident-self-audit.sh [--json]"
+            echo "Reports which documented Claude Code cost accidents your setup is exposed to."
+            exit 0 ;;
+    esac
+done
+
+# --- Gather settings content (best effort, fail open) ---------------------
+# Hooks are configured in settings.json / settings.local.json at user or
+# project scope. We just need the raw text to see which guard commands are
+# wired in; we do not parse the schema so a slightly unusual layout still works.
+SETTINGS_GLOB="${CC_COST_AUDIT_SETTINGS:-}"
+SETTINGS_TEXT=""
+if [ -n "$SETTINGS_GLOB" ]; then
+    for f in $SETTINGS_GLOB; do
+        [ -f "$f" ] && SETTINGS_TEXT="$SETTINGS_TEXT
+$(cat "$f" 2>/dev/null)"
+    done
+else
+    for f in \
+        "$HOME/.claude/settings.json" \
+        "$HOME/.claude/settings.local.json" \
+        "./.claude/settings.json" \
+        "./.claude/settings.local.json"; do
+        [ -f "$f" ] && SETTINGS_TEXT="$SETTINGS_TEXT
+$(cat "$f" 2>/dev/null)"
+    done
+fi
+
+# A guard is considered "wired in" if its script name appears anywhere in the
+# settings text (the hook command references the file by name).
+has_guard() { printf '%s' "$SETTINGS_TEXT" | grep -q "$1"; }
+
+# Does this project have CI workflows that an agentic push could fan out onto?
+HAS_WORKFLOWS=0
+if [ -d "./.github/workflows" ] && ls ./.github/workflows/*.y*ml >/dev/null 2>&1; then
+    HAS_WORKFLOWS=1
+fi
+
+# --- Define the checks ----------------------------------------------------
+# Each check appends "issue|title|fix" to FINDINGS when the setup is exposed.
+FINDINGS=()
+
+# 1. CI minutes blast from multi-branch pushes — only relevant if CI exists.
+if [ "$HAS_WORKFLOWS" -eq 1 ] && ! has_guard "git-push-blast-radius-guard"; then
+    FINDINGS+=("65944|Pushing one fix across many branches fans out CI runs and can burn a month of GitHub Actions minutes in hours|add examples/git-push-blast-radius-guard.sh as a PreToolUse(Bash) hook")
+fi
+
+# 2. WebFetch / research runaway cost.
+if ! has_guard "webfetch-runaway-guard"; then
+    FINDINGS+=("65684|A research loop can run dozens of WebFetch calls without pausing, spending real money before you notice|add examples/webfetch-runaway-guard.sh as a PreToolUse(WebFetch) hook")
+fi
+
+# 3. Oversized image retried into a cost loop.
+if ! has_guard "image-dimension-guard"; then
+    FINDINGS+=("65636|An oversized image can be retried until prompt caching breaks and cost climbs ~35x|add examples/image-dimension-guard.sh as a PreToolUse(Read) hook")
+fi
+
+# 4. Unbounded command output exhausting the session (and re-processing cost).
+if ! has_guard "unbounded-output-guard"; then
+    FINDINGS+=("65789|An unbounded-output command (yes, cat /dev/zero, ...) floods the session and inflates re-processing cost|add examples/unbounded-output-guard.sh as a PreToolUse(Bash) hook")
+fi
+
+# 5. No spend visibility at all — none of the cost/budget signals are wired in.
+if ! has_guard "daily-cost-guard" && ! has_guard "session-cost-alert" \
+   && ! has_guard "token-budget-guard" && ! has_guard "cost-tracker"; then
+    FINDINGS+=("0|No session/daily cost signal is configured, so a runaway has nothing watching the running total|add one of examples/daily-cost-guard.sh, session-cost-alert.sh, or token-budget-guard.sh")
+fi
+
+# 6. 1M context left on — silently drains the weekly quota faster.
+# Exposure only when the user has not explicitly turned it off.
+if [ "${CLAUDE_CODE_DISABLE_1M_CONTEXT:-}" != "1" ]; then
+    FINDINGS+=("64445|1M context can consume credits/quota without you explicitly selecting 1M mode, draining the weekly limit faster via larger re-processed context|set CLAUDE_CODE_DISABLE_1M_CONTEXT=1 (and prefer opusplan) if you do not need the 1M window")
+fi
+
+COUNT=${#FINDINGS[@]}
+
+# --- Output ---------------------------------------------------------------
+if [ "$JSON" -eq 1 ]; then
+    printf '{"exposures":%d,"findings":[' "$COUNT"
+    first=1
+    for f in "${FINDINGS[@]}"; do
+        IFS='|' read -r issue title fix <<EOF
+$f
+EOF
+        [ "$first" -eq 0 ] && printf ','
+        first=0
+        # JSON-escape the two free-text fields minimally (quotes/backslashes).
+        et=$(printf '%s' "$title" | sed 's/\\/\\\\/g; s/"/\\"/g')
+        ef=$(printf '%s' "$fix" | sed 's/\\/\\\\/g; s/"/\\"/g')
+        printf '{"issue":"%s","title":"%s","fix":"%s"}' "$issue" "$et" "$ef"
+    done
+    printf ']}\n'
+    exit 0
+fi
+
+echo ""
+echo "  Claude Code cost-accident self-audit"
+echo "  ===================================="
+if [ "$COUNT" -eq 0 ]; then
+    echo ""
+    echo "  No exposures found against the documented cost accidents checked here."
+    echo "  (This only covers the patterns above — it is not a guarantee.)"
+    echo ""
+    exit 0
+fi
+
+echo ""
+echo "  Exposed to $COUNT of the documented cost accidents below:"
+echo ""
+for f in "${FINDINGS[@]}"; do
+    IFS='|' read -r issue title fix <<EOF
+$f
+EOF
+    if [ "$issue" = "0" ]; then
+        echo "  [!] $title"
+    else
+        echo "  [!] $title (#$issue)"
+    fi
+    echo "      fix: $fix"
+    echo ""
+done
+echo "  These guards ship in this repo; wire the ones you want into your"
+echo "  .claude/settings.json hooks, or run 'npx cc-safe-setup' to set them up."
+echo "  Worked examples of these exact incidents (free chapter):"
+echo "    https://yurukusa.github.io/cc-safe-setup/token-book.html"
+echo ""
+
+exit 0

package/examples/cowork-claude-md-load-checker.sh

@@ -0,0 +1,100 @@
+#!/bin/bash
+# cowork-claude-md-load-checker.sh — Surface ~/.claude/CLAUDE.md at SessionStart
+#
+# Solves: #62859 — Cowork (Claude desktop app) does NOT load ~/.claude/CLAUDE.md
+#         at session start. Users who keep safety-critical standing instructions
+#         (e.g. "Always ask before write operations to MCP tools") in
+#         ~/.claude/CLAUDE.md lose those guardrails whenever they open a Cowork
+#         session, because Cowork only honors part of the ~/.claude/ directory.
+#         Related: #50669 (Cowork loads only 3/27 personal skills).
+#
+# WHO THIS PROTECTS:
+#   CLI users who also use Cowork on the same machine. The hook runs in the
+#   CLI (where hooks DO fire), and:
+#     (a) confirms ~/.claude/CLAUDE.md is loaded in this CLI session by
+#         echoing a short header + the file's first lines to stderr at
+#         SessionStart;
+#     (b) reminds the operator that the same file will NOT auto-load in
+#         Cowork, so they should paste it manually when switching surfaces.
+#
+#   Cowork itself ignores ~/.claude/, so the hook cannot run inside Cowork.
+#   The protection is the operator-side awareness this hook builds in CLI.
+#
+# HOW IT WORKS:
+#   On SessionStart, if ~/.claude/CLAUDE.md exists and is non-trivial
+#   (>= CC_COWORK_MD_MIN_BYTES, default 50 bytes), print a warning block to
+#   stderr with the first N bytes of the file and a one-line note linking
+#   to #62859. Always exit 0 (advisory only).
+#
+# TRIGGER: SessionStart
+# MATCHER: ""
+#
+# CONFIGURATION:
+#   CC_COWORK_MD_PATH=path       override file (default ~/.claude/CLAUDE.md)
+#   CC_COWORK_MD_MIN_BYTES=N     skip if file smaller than N (default 50)
+#   CC_COWORK_MD_MAX_CHARS=N     truncate display at N (default 1500)
+#   CC_COWORK_MD_QUIET=1         suppress the reminder line about Cowork
+#   CC_COWORK_MD_LOG=path        append load events (default off)
+#
+# USAGE:
+# {
+#   "hooks": {
+#     "SessionStart": [{
+#       "hooks": [{
+#         "type": "command",
+#         "command": "~/.claude/hooks/cowork-claude-md-load-checker.sh"
+#       }]
+#     }]
+#   }
+# }
+
+MD_PATH="${CC_COWORK_MD_PATH:-$HOME/.claude/CLAUDE.md}"
+MIN_BYTES="${CC_COWORK_MD_MIN_BYTES:-50}"
+MAX_CHARS="${CC_COWORK_MD_MAX_CHARS:-1500}"
+
+# Drain stdin (SessionStart hooks may or may not receive payload)
+INPUT=$(cat 2>/dev/null || true)
+
+if [ ! -f "$MD_PATH" ]; then
+    exit 0
+fi
+
+ACTUAL_SIZE=$(wc -c < "$MD_PATH" 2>/dev/null || echo 0)
+if [ "$ACTUAL_SIZE" -lt "$MIN_BYTES" ]; then
+    exit 0
+fi
+
+CONTENT=$(head -c "$MAX_CHARS" "$MD_PATH" 2>/dev/null)
+
+cat >&2 <<EOF
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[cowork-claude-md-load-checker] SessionStart — surfacing ${MD_PATH}
+Addresses #62859: Cowork (Claude desktop app) does NOT load
+~/.claude/CLAUDE.md at session start. This hook runs in CLI only
+and re-states the file's contents so the rules remain in context.
+These are standing instructions that apply across all projects.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+${CONTENT}
+EOF
+
+if [ "$ACTUAL_SIZE" -gt "$MAX_CHARS" ]; then
+    echo "" >&2
+    echo "[...truncated at ${MAX_CHARS} chars of ${ACTUAL_SIZE}. Full file: ${MD_PATH}]" >&2
+fi
+
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" >&2
+
+if [ -z "${CC_COWORK_MD_QUIET:-}" ]; then
+    cat >&2 <<'EOF'
+[cowork-claude-md-load-checker] Reminder: if you switch to Cowork on the same
+machine, the file above will NOT auto-load there. Paste it manually into the
+Cowork chat until #62859 is resolved.
+EOF
+fi
+
+if [ -n "${CC_COWORK_MD_LOG:-}" ]; then
+    mkdir -p "$(dirname "$CC_COWORK_MD_LOG")" 2>/dev/null
+    echo "$(date -Iseconds) file=${MD_PATH} size=${ACTUAL_SIZE}" >> "$CC_COWORK_MD_LOG"
+fi
+
+exit 0

package/examples/cowork-fuse-staleness-watcher.sh

@@ -0,0 +1,140 @@
+#!/bin/bash
+# cowork-fuse-staleness-watcher.sh — Warn before bash git ops in Cowork FUSE mounts
+#
+# Solves: #62932 (P1 critical) — In Cowork, the FUSE bridge that mounts a
+#         Windows host folder into the Linux sandbox at
+#         /sessions/<id>/mnt/<folder>/ caches inode metadata for the entire
+#         session. After the first read, the sandbox bash environment sees
+#         the file's original size, mtime, and content even when Windows
+#         modifies it. The wedge is SELECTIVE:
+#           - file content + stat: stale
+#           - working-tree git walks (status / add / commit): return garbage
+#           - ref-walking git commands (rev-parse / log / show): stay clean
+#           - Cowork's first-class file tools (Read/Edit/Write): bypass FUSE
+#             and are authoritative
+#
+#         The danger: bash `git add` / `git commit` against the working tree
+#         silently commits the stale content, corrupting the repo's view of
+#         the Windows-side truth. Bash `git status` returns "No commits yet"
+#         on a repo with hundreds of commits.
+#
+# HOW IT WORKS:
+#   PreToolUse hook on Bash. If the command looks like a working-tree git
+#   operation (git status / add / commit / diff / restore / checkout --) AND
+#   the current working directory matches the Cowork FUSE mount pattern
+#   (/sessions/*/mnt/), print a stderr warning explaining:
+#     - the wedge exists for THIS session and won't self-clear
+#     - working-tree views are untrustworthy; ref views are still clean
+#     - prefer Cowork's first-class Read/Edit/Write tools instead of bash
+#     - if a parser error fires on .git/config, the file likely needs a
+#       full rewrite via `cat > .git/config`
+#
+#   Always exit 0 (advisory only). The hook does NOT block, because the
+#   user may consciously be running ref-only ops (rev-parse / log) that
+#   stay clean even under the wedge.
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
+#
+# CONFIGURATION:
+#   CC_COWORK_FUSE_PATTERN=regex  custom path regex (default Cowork sandbox)
+#   CC_COWORK_FUSE_QUIET=1        suppress the recommendation block
+#   CC_COWORK_FUSE_LOG=path       append warning events (default off)
+#
+# USAGE:
+# {
+#   "hooks": {
+#     "PreToolUse": [{
+#       "matcher": "Bash",
+#       "hooks": [{
+#         "type": "command",
+#         "command": "~/.claude/hooks/cowork-fuse-staleness-watcher.sh"
+#       }]
+#     }]
+#   }
+# }
+
+INPUT=$(cat 2>/dev/null || true)
+
+# Extract the bash command. Hook input is JSON via stdin.
+CMD=$(echo "$INPUT" | jq -r '.tool_input.command // ""' 2>/dev/null)
+if [ -z "$CMD" ]; then
+    exit 0
+fi
+
+# Detect the Cowork FUSE mount path. The pattern is /sessions/<id>/mnt/<folder>/.
+# Match either CWD or any path inside the command itself.
+FUSE_PATTERN="${CC_COWORK_FUSE_PATTERN:-/sessions/[^/]+/mnt/}"
+
+cwd=$(echo "$INPUT" | jq -r '.cwd // ""' 2>/dev/null)
+if [ -z "$cwd" ]; then
+    cwd="$PWD"
+fi
+
+in_fuse_mount=0
+if echo "$cwd" | grep -qE "$FUSE_PATTERN"; then
+    in_fuse_mount=1
+elif echo "$CMD" | grep -qE "$FUSE_PATTERN"; then
+    in_fuse_mount=1
+fi
+
+if [ "$in_fuse_mount" -eq 0 ]; then
+    exit 0
+fi
+
+# Detect a working-tree git command. Ref-only ops (rev-parse, log, show, cat-file)
+# are safe under the wedge, so we deliberately do NOT warn on those. Matcher
+# allows arbitrary git prefix args like `git -C <path>` or `git --git-dir=...`.
+is_worktree_git=0
+if echo "$CMD" | grep -qE '\bgit\b[^|;&]*\b(status|add|commit|diff|restore|stash|clean|ls-files|rm|mv)\b'; then
+    is_worktree_git=1
+elif echo "$CMD" | grep -qE '\bgit\b[^|;&]*\bcheckout\b[^|;&]*(-- |\.\s*$|\.\s*[|;&])'; then
+    # `git checkout <branch>` is safe; only warn on path-discard variants
+    # like `git checkout -- file` or `git checkout .`.
+    is_worktree_git=1
+fi
+
+if [ "$is_worktree_git" -eq 0 ]; then
+    exit 0
+fi
+
+cat >&2 <<EOF
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[cowork-fuse-staleness-watcher] Cowork FUSE mount detected
+This bash command runs against a working-tree git view on a Cowork
+Windows-host FUSE bridge (path matches ${FUSE_PATTERN}).
+
+Known wedge (#62932, P1 critical): once a file is read in this session,
+its size / mtime / content are frozen for the rest of the session even
+when Windows modifies it. Working-tree git ops will see the FROZEN
+content; bash 'git add' / 'git commit' will silently commit the stale
+content. 'git status' may report "No commits yet" on a repo with hundreds
+of commits.
+
+What still works under the wedge:
+  - ref-walking git: rev-parse, log, show, cat-file
+  - Cowork's first-class Read / Edit / Write file tools (they bypass FUSE)
+
+What does NOT work:
+  - bash git status / add / commit / diff / restore / checkout / stash
+  - bash file reads of any file modified by Windows in this session
+
+If '.git/config' parsing fails with NUL bytes, rewrite the file via
+'cat > .git/config' from inside the sandbox before any further git op.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+EOF
+
+if [ -z "${CC_COWORK_FUSE_QUIET:-}" ]; then
+    cat >&2 <<'EOF'
+[cowork-fuse-staleness-watcher] Recommended: replace this bash git op with
+the Cowork file tools (Read / Edit / Write), or use a ref-only command
+(rev-parse / log / show) when you just need ref info. The wedge will NOT
+clear for the rest of this session.
+EOF
+fi
+
+if [ -n "${CC_COWORK_FUSE_LOG:-}" ]; then
+    mkdir -p "$(dirname "$CC_COWORK_FUSE_LOG")" 2>/dev/null
+    echo "$(date -Iseconds) cwd=${cwd} cmd=${CMD}" >> "$CC_COWORK_FUSE_LOG"
+fi
+
+exit 0