cc-safe-setup 29.7.0 → 30.0.4

package/examples/account-billing-log.sh

@@ -0,0 +1,98 @@
+#!/bin/bash
+# ================================================================
+# account-billing-log.sh — Append per-session line to a billing
+#                          log indexed by Anthropic account label
+# ================================================================
+# PURPOSE:
+#   Consultants billing clients for Claude Code work need
+#   defensible per-account session records. This hook fires on
+#   Stop and appends one line per session to ~/billing-logs/sessions.log
+#   capturing timestamp, account label, working directory, and any
+#   session metadata Claude passes to the hook.
+#
+#   The log format is plain text (one line per session) for easy
+#   aggregation with awk/grep/jq at month-end.
+#
+# TRIGGER: Stop
+# MATCHER: ""
+#
+# WHY IT MATTERS:
+#   When you bill multiple clients off the same machine, "which
+#   account did this session run under" must be answerable from
+#   an audit log, not from memory or chat history. This hook gives
+#   that audit log existence — without it, the only record is
+#   whatever Anthropic shows you in their billing dashboard, which
+#   is per-account but not per-project-per-session.
+#
+# OPERATOR-SIDE BRIDGE FOR (1,178 cumulative reactions):
+#   #18435 Desktop multi-account profile switcher (542 reactions)
+#   #27302 Web app per-Connector multi-account (327 reactions)
+#   #36151 Mobile app multi-account switching (309 reactions)
+#
+# OUTPUT FORMAT:
+#   One line per session, pipe-separated for easy awk:
+#   <timestamp UTC> | <account> | <cwd> | session:<id> | turns:<n>
+#
+# AGGREGATION EXAMPLES:
+#   # Session count this month, grouped by account:
+#   awk -F' \\| ' '{print substr($1,1,7), $2}' ~/billing-logs/sessions.log \
+#     | grep "^$(date +%Y-%m)" \
+#     | awk '{print $2}' | sort | uniq -c
+#
+#   # All sessions for one client this month:
+#   grep "^$(date +%Y-%m)" ~/billing-logs/sessions.log | grep "| client-a |"
+#
+# CONFIGURATION (env vars):
+#   ANTHROPIC_ACCOUNT_LABEL   the active session's account label;
+#                              defaults to "unknown" if unset.
+#   CC_BILLING_LOG_DIR        directory for the log file;
+#                              defaults to $HOME/billing-logs.
+#   CC_BILLING_LOG_DISABLE    set to "1" to disable logging.
+#
+# RELATED:
+#   account-routing-preflight.sh (companion hook, SessionStart side)
+#   Multi-account operator guide:
+#     https://gist.github.com/yurukusa/d880ecc984af5d664f003daf85f956e3
+# ================================================================
+
+set -u
+
+if [ "${CC_BILLING_LOG_DISABLE:-0}" = "1" ]; then
+    exit 0
+fi
+
+LOG_DIR="${CC_BILLING_LOG_DIR:-$HOME/billing-logs}"
+LOG_FILE="$LOG_DIR/sessions.log"
+
+# Ensure log directory exists
+mkdir -p "$LOG_DIR" 2>/dev/null || {
+    echo "account-billing-log: cannot create $LOG_DIR" >&2
+    exit 0
+}
+
+# Resolve active account label
+ACCOUNT="${ANTHROPIC_ACCOUNT_LABEL:-unknown}"
+
+# Read Claude's session JSON from stdin (best-effort)
+INPUT=$(cat 2>/dev/null || echo '{}')
+
+# Extract session metadata — accept multiple field shapes
+SESSION_ID=$(printf '%s' "$INPUT" \
+    | jq -r '.session_id // .sessionId // .session.id // "unknown"' 2>/dev/null \
+    || echo "unknown")
+TURNS=$(printf '%s' "$INPUT" \
+    | jq -r '.turn_count // .turns // .session.turn_count // 0' 2>/dev/null \
+    || echo "0")
+
+# Sanitize any pipe characters in cwd to keep the log parseable
+CWD_SANITIZED=$(printf '%s' "$PWD" | tr '|' '_')
+
+# Append the log line
+TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+printf '%s | %s | %s | session:%s | turns:%s\n' \
+    "$TIMESTAMP" "$ACCOUNT" "$CWD_SANITIZED" "$SESSION_ID" "$TURNS" \
+    >> "$LOG_FILE"
+
+# Stop hooks should always exit 0 unless they want to block —
+# billing logging is advisory.
+exit 0

package/examples/account-routing-preflight.sh

@@ -0,0 +1,123 @@
+#!/bin/bash
+# ================================================================
+# account-routing-preflight.sh — Refuse session when the active
+#                                Anthropic account doesn't match
+#                                the project's declared expectation
+# ================================================================
+# PURPOSE:
+#   Operators running multiple Anthropic accounts (work + personal,
+#   multiple clients, multiple organizations) routinely launch
+#   Claude Code from the wrong shell context and accidentally bill
+#   the wrong account. This hook catches that mistake at session
+#   start by comparing ANTHROPIC_ACCOUNT_LABEL against a per-project
+#   declaration in .claude/expected-account.
+#
+#   The hook does NOT set the account. Hooks run as subprocesses
+#   and cannot modify the parent claude process's environment.
+#   Account switching must happen via shell alias or direnv before
+#   `claude` is launched. This hook is the safety net: if the wrong
+#   account is loaded when the session starts, it refuses the session
+#   with an explicit error rather than billing silently.
+#
+# TRIGGER: SessionStart
+# MATCHER: ""
+#
+# OPERATOR-SIDE BRIDGE FOR (1,178 cumulative reactions):
+#   #18435 Desktop multi-account profile switcher (542 reactions)
+#   #27302 Web app per-Connector multi-account (327 reactions)
+#   #36151 Mobile app multi-account switching (309 reactions)
+#
+# SETUP:
+#   1. Set ANTHROPIC_ACCOUNT_LABEL alongside ANTHROPIC_API_KEY in
+#      your account-switching mechanism (alias / direnv / wrapper):
+#
+#      alias cc-work='ANTHROPIC_API_KEY=$WORK_KEY ANTHROPIC_ACCOUNT_LABEL=work claude'
+#
+#   2. In each project root that should be tied to a specific
+#      account, create .claude/expected-account with the label:
+#
+#      echo "work" > ~/projects/work-monorepo/.claude/expected-account
+#      echo "client-a" > ~/projects/clients/client-a/.claude/expected-account
+#
+#   3. Wire the hook in settings.json:
+#
+#      {
+#        "hooks": {
+#          "SessionStart": [
+#            {
+#              "matcher": "",
+#              "hooks": [
+#                { "type": "command",
+#                  "command": "$HOME/.claude/hooks/account-routing-preflight.sh" }
+#              ]
+#            }
+#          ]
+#        }
+#      }
+#
+# BEHAVIOR:
+#   - No .claude/expected-account in $PWD → pass through silently.
+#   - File exists, label matches ANTHROPIC_ACCOUNT_LABEL → pass.
+#   - File exists, label mismatch → exit 2 with explicit message
+#     showing expected vs active account.
+#
+# CONFIGURATION (env vars):
+#   ANTHROPIC_ACCOUNT_LABEL   the active session's account label;
+#                              defaults to "unknown" if unset.
+#   CC_ACCOUNT_PREFLIGHT_DISABLE  set to "1" to disable the gate.
+#
+# RELATED ISSUES:
+#   #18435, #27302, #36151 (the 1,178-reaction cluster)
+# ================================================================
+
+set -u
+
+if [ "${CC_ACCOUNT_PREFLIGHT_DISABLE:-0}" = "1" ]; then
+    exit 0
+fi
+
+EXPECTED_FILE="$PWD/.claude/expected-account"
+if [ ! -f "$EXPECTED_FILE" ]; then
+    # No declared expectation for this project — silent pass-through
+    exit 0
+fi
+
+EXPECTED=$(cat "$EXPECTED_FILE" 2>/dev/null | tr -d '[:space:]')
+if [ -z "$EXPECTED" ]; then
+    # File exists but is empty — silent pass-through
+    exit 0
+fi
+
+ACTIVE="${ANTHROPIC_ACCOUNT_LABEL:-unknown}"
+
+if [ "$ACTIVE" = "$EXPECTED" ]; then
+    # Match — proceed silently
+    exit 0
+fi
+
+# Mismatch — refuse the session
+cat >&2 <<EOF
+
+⛔ Account mismatch detected at session start.
+
+   Project path:    $PWD
+   Project expects: $EXPECTED
+   Active account:  $ACTIVE
+
+The active Anthropic account does not match what this project
+declares in .claude/expected-account. Launching claude under
+the active account would bill the wrong account.
+
+Fix:
+  1. Exit this claude session.
+  2. Switch accounts via your shell alias or direnv:
+       cc-${EXPECTED} ...
+  3. Verify ANTHROPIC_ACCOUNT_LABEL is set to "${EXPECTED}":
+       echo "\$ANTHROPIC_ACCOUNT_LABEL"
+  4. Relaunch claude from this directory.
+
+To disable this gate temporarily, export
+CC_ACCOUNT_PREFLIGHT_DISABLE=1.
+
+EOF
+exit 2

package/examples/agent-sdk-credit-pool-monitor.sh

@@ -0,0 +1,145 @@
+#!/bin/bash
+# agent-sdk-credit-pool-monitor.sh — track `claude -p` usage against the June 15 credit pool cliff
+#
+# Solves: Anthropic's announcement on 2026-05-13 that, starting 2026-06-15,
+#         `claude -p` and Agent SDK usage draws from a separate per-plan monthly
+#         credit pool (Pro $20, Max 5x $100, Max 20x $200). Unused credit does
+#         not roll over. Operators running heavy programmatic automation under
+#         subscription tiers have no visibility into their projected post-cliff
+#         cost until they hit the credit ceiling and programmatic usage stops.
+#
+#         Public references (seven Tier-1 outlets, May 13-14, 2026):
+#         - The Register: "Anthropic tosses agents into the API billing pool"
+#         - SiliconANGLE: "Anthropic announces programmatic credit pool as agentic tool use rises"
+#         - XDA Developers: per-tier credit pool figures + Theo Browne 25x quote
+#         - devtoolpicks: per-tier token math + Ben Hylak GPUs quote
+#         - latent.space: "Codex Rises, Claude Meters Programmatic Usage"
+#         - VentureBeat: third-party agent reinstatement with a catch
+#         - PromptZone: cross-customer impact
+#         HN threads: 48126281 (parent), 48126438 (companion), 48129813 (Show HN
+#         workaround Claude-pee), 48130374 (Tell HN follow-up).
+#
+# Event:  PreToolUse   Matcher: Bash
+# Action: When a Bash tool call invokes `claude -p ...` or `claude --print ...`,
+#         append a timestamped entry to ~/.claude/logs/claude-p-calls.log,
+#         then compute the running 30-day call count and the projected monthly
+#         cost. Emit an advisory message to stderr if the projection exceeds
+#         the operator's configured credit pool ceiling.
+#
+#         Before June 15, the message is a pre-cliff warning ("if this pattern
+#         continues, your post-cliff cost will be X"). On or after June 15,
+#         the message is a real-time credit-pool drawdown alert.
+#
+#         The hook never blocks. It is advisory only.
+#
+# Configuration (environment variables):
+#   AGENT_SDK_TIER                   pro | max5x | max20x | team-std | team-prem (default: pro)
+#                                    Sets the credit pool ceiling for projection comparison.
+#   AGENT_SDK_AVG_CALL_COST          estimated average per-call USD cost (default: 0.05)
+#                                    Override if your workload differs from the typical 49,000-token
+#                                    Sonnet 4.6 invocation (~$0.05). See Cost Cliff Survival Guide
+#                                    Chapter 2 Source 3 for token-level calibration.
+#   AGENT_SDK_LOG                    log path (default: ~/.claude/logs/claude-p-calls.log)
+#   AGENT_SDK_WARN_THRESHOLD_PCT     projection-vs-ceiling % above which to warn (default: 75)
+#   AGENT_SDK_QUIET                  set to 1 to suppress informational messages
+#
+# Exit codes:
+#   0  always (advisory only — never blocks the Bash call)
+
+set -u
+
+INPUT=$(cat 2>/dev/null || true)
+
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+[ "$TOOL" != "Bash" ] && exit 0
+
+CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$CMD" ] && exit 0
+
+# Detect `claude -p ...` and `claude --print ...` as whole command words.
+# Avoid matching `./my-claude -p` / `someone-claude -p` (hyphen prefix). We
+# require `claude` to be at the start or after a shell separator, immediately
+# followed (after whitespace) by `-p` or `--print`.
+if ! printf '%s' "$CMD" | grep -qE '(^|[;&| 	])claude[ 	]+(-p|--print)(\b|$)'; then
+  exit 0
+fi
+
+TIER="${AGENT_SDK_TIER:-pro}"
+AVG_CALL_COST="${AGENT_SDK_AVG_CALL_COST:-0.05}"
+WARN_PCT="${AGENT_SDK_WARN_THRESHOLD_PCT:-75}"
+QUIET="${AGENT_SDK_QUIET:-0}"
+LOG_PATH="${AGENT_SDK_LOG:-$HOME/.claude/logs/claude-p-calls.log}"
+
+# Tier ceilings, in USD per month. Values per Anthropic announcement 2026-05-13
+# (verified via XDA Developers 2026-05-13 and SiliconANGLE 2026-05-14).
+case "$TIER" in
+  pro)        CEILING=20  ;;
+  max5x)      CEILING=100 ;;
+  max20x)     CEILING=200 ;;
+  team-std)   CEILING=20  ;;
+  team-prem)  CEILING=100 ;;
+  *)
+    {
+      echo "agent-sdk-credit-pool-monitor: unknown AGENT_SDK_TIER='$TIER'"
+      echo "  Expected one of: pro / max5x / max20x / team-std / team-prem"
+      echo "  Defaulting to 'pro' (\$20/month ceiling). Set AGENT_SDK_TIER to silence."
+    } >&2
+    CEILING=20
+    ;;
+esac
+
+# Ensure log directory exists.
+mkdir -p "$(dirname "$LOG_PATH")" 2>/dev/null
+
+# Append a timestamped entry (epoch seconds + cmd length).
+NOW=$(date +%s 2>/dev/null || echo 0)
+CMD_LEN=$(printf '%s' "$CMD" | wc -c | tr -d ' ')
+printf '%s\t%s\n' "$NOW" "$CMD_LEN" >> "$LOG_PATH" 2>/dev/null
+
+# Count entries within the last 30 days (2,592,000 seconds).
+WINDOW_START=$((NOW - 2592000))
+[ "$WINDOW_START" -lt 0 ] && WINDOW_START=0
+
+COUNT=$(awk -F'\t' -v cutoff="$WINDOW_START" '$1 >= cutoff { c++ } END { print c+0 }' "$LOG_PATH" 2>/dev/null)
+[ -z "$COUNT" ] && COUNT=0
+
+# Project monthly cost at AVG_CALL_COST per call.
+PROJECTED=$(awk -v c="$COUNT" -v r="$AVG_CALL_COST" 'BEGIN { printf "%.2f", c * r }')
+
+# Compare projection to ceiling.
+PCT=$(awk -v p="$PROJECTED" -v ceil="$CEILING" 'BEGIN { printf "%.0f", (ceil > 0 ? p / ceil * 100 : 0) }')
+
+# Determine cliff window. Hard date 2026-06-15 00:00 UTC = 1781308800
+CLIFF_TS=1781308800
+PRE_CLIFF=$([ "$NOW" -lt "$CLIFF_TS" ] && echo 1 || echo 0)
+
+BANNER='ⓘ agent-sdk-credit-pool-monitor (June 15, 2026 cliff)'
+
+if [ "$PCT" -ge "$WARN_PCT" ]; then
+  {
+    echo "$BANNER"
+    echo "  30-day \`claude -p\` calls: $COUNT (projected: \$$PROJECTED / month)"
+    echo "  Tier '$TIER' ceiling: \$$CEILING — your projection is ${PCT}% of ceiling."
+    if [ "$PRE_CLIFF" = "1" ]; then
+      echo "  Pre-cliff: this projection becomes your effective programmatic budget"
+      echo "  on 2026-06-15. Above-ceiling usage will charge at full API rates."
+    else
+      echo "  Post-cliff: \$$PROJECTED already approaches the \$$CEILING credit pool."
+      echo "  Above-ceiling usage charges at full API rates; non-rollover monthly."
+    fi
+    echo "  Response paths (Migration Playbook Edition 2, Chapter 8 decision tree):"
+    echo "    - Path A: stay; restructure for cache hit ratio"
+    echo "    - Path B': model-only swap (e.g., Z.AI GLM Coding Plan)"
+    echo "    - Path D: hybrid delegation (e.g., Kimi K2.5 as side-worker)"
+    echo "    - Path C: full DIY stack (3x ceiling threshold)"
+    echo "  Calibrate AVG_CALL_COST per Cost Cliff Survival Guide Chapter 2."
+  } >&2
+elif [ "$QUIET" != "1" ]; then
+  {
+    echo "$BANNER (info)"
+    echo "  30-day \`claude -p\` calls: $COUNT (projected: \$$PROJECTED / month)"
+    echo "  Tier '$TIER' ceiling: \$$CEILING (${PCT}% used)."
+  } >&2
+fi
+
+exit 0

package/examples/agent-view-quota-decrement.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# ================================================================
+# agent-view-quota-decrement.sh — Decrement Task counter on completion
+# ================================================================
+# PURPOSE:
+#   Companion to agent-view-quota-warn.sh. Decrements the concurrent-
+#   Task counter when a Task tool returns, so the warn-side counter
+#   accurately reflects currently-running parallel agents.
+#
+# TRIGGER: PostToolUse
+# MATCHER: "Task"
+# ================================================================
+
+set -uo pipefail
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || echo "")
+[ "$TOOL_NAME" = "Task" ] || exit 0
+
+SESSION_KEY="${CLAUDE_CODE_SESSION_ID:-ppid-${PPID:-unknown}}"
+COUNTER_FILE="/tmp/cc-agent-view-tasks-${SESSION_KEY}"
+
+# Decrement (clamp at 0)
+COUNT=$(cat "$COUNTER_FILE" 2>/dev/null || echo "0")
+case "$COUNT" in
+    ''|*[!0-9]*) COUNT=0 ;;
+esac
+COUNT=$((COUNT - 1))
+[ "$COUNT" -lt 0 ] && COUNT=0
+echo "$COUNT" > "$COUNTER_FILE"
+
+exit 0

package/examples/agent-view-quota-warn.sh

@@ -0,0 +1,94 @@
+#!/bin/bash
+# ================================================================
+# agent-view-quota-warn.sh — Warn on parallel Task spawn quota burn
+# ================================================================
+# PURPOSE:
+#   Claude Code Agent View (v2.1.139+) lets operators run multiple
+#   Task / sub-agent sessions in parallel via /bg or Background
+#   Sessions. Each parallel agent burns quota at the full rate —
+#   ten parallel agents burn quota approximately ten times faster
+#   than a single interactive session. Plus, each session's one-line
+#   summary is generated by Haiku and billed as a normal API call.
+#
+#   This hook detects when an operator is about to spawn an Nth
+#   concurrent Task and emits a warning so they can decide whether
+#   to throttle. The warning includes the count of currently-tracked
+#   concurrent Tasks in the session.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Task"
+#
+# HOW IT WORKS:
+#   - Tracks concurrent Task invocations per session via a counter
+#     keyed on CLAUDE_CODE_SESSION_ID (falls back to PPID).
+#   - On Task spawn, increments counter and checks against threshold.
+#   - On Task completion (PostToolUse Task), decrement counter.
+#     (Use the companion hook below for the decrement side.)
+#   - Emits a warning to stderr if counter exceeds threshold.
+#   - Does NOT block (exit 0). Warning is advisory.
+#
+# CONFIGURATION:
+#   CC_AGENT_VIEW_WARN_THRESHOLD  (default 3) — warn when this many
+#                                  concurrent Tasks are tracked.
+#   CC_AGENT_VIEW_PEAK_THRESHOLD  (default 10) — louder warning above
+#                                  this count.
+#   CC_AGENT_VIEW_QUIET           (default unset) — suppress all
+#                                  warnings if set to "1".
+#
+# RELATED:
+#   - Issue #58570 (Agent View not enabled for Claude API users)
+#   - Hatena article on four Agent View pitfalls (2026-05-16):
+#     https://yurukusa-dev.hatenablog.com/entry/2026/05/16/104555
+# ================================================================
+
+set -uo pipefail
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || echo "")
+
+# Only act on Task tool spawns
+[ "$TOOL_NAME" = "Task" ] || exit 0
+
+# Suppression via env
+[ "${CC_AGENT_VIEW_QUIET:-0}" = "1" ] && exit 0
+
+THRESHOLD="${CC_AGENT_VIEW_WARN_THRESHOLD:-3}"
+PEAK="${CC_AGENT_VIEW_PEAK_THRESHOLD:-10}"
+
+# Identify session — prefer CLAUDE_CODE_SESSION_ID, fall back to PPID
+SESSION_KEY="${CLAUDE_CODE_SESSION_ID:-ppid-${PPID:-unknown}}"
+COUNTER_FILE="/tmp/cc-agent-view-tasks-${SESSION_KEY}"
+
+# Initialize if absent
+[ -f "$COUNTER_FILE" ] || echo "0" > "$COUNTER_FILE"
+
+# Read, increment, write
+COUNT=$(cat "$COUNTER_FILE" 2>/dev/null || echo "0")
+# Numeric guard
+case "$COUNT" in
+    ''|*[!0-9]*) COUNT=0 ;;
+esac
+COUNT=$((COUNT + 1))
+echo "$COUNT" > "$COUNTER_FILE"
+
+# Emit warning if threshold exceeded
+if [ "$COUNT" -ge "$PEAK" ]; then
+    cat >&2 <<EOF
+[agent-view-quota-warn] PEAK: ${COUNT} concurrent Tasks tracked in this session.
+  Each parallel Task burns quota at the full rate. At ${COUNT}x parallelism your
+  monthly credit allowance can be exhausted in 1/${COUNT}th of the usual time.
+  Plus, Agent View's per-session Haiku summary calls accumulate as billable
+  API calls (USD 1/MTok input on Haiku 4.5).
+  Set CC_AGENT_VIEW_QUIET=1 to suppress this warning.
+EOF
+elif [ "$COUNT" -ge "$THRESHOLD" ]; then
+    cat >&2 <<EOF
+[agent-view-quota-warn] ${COUNT} concurrent Tasks tracked. Parallel agent execution
+  multiplies quota burn linearly. Six days before the 2026-06-15 credit cliff,
+  the cost of parallel agents increases sharply — Pro USD 20, Max 5x USD 100,
+  Max 20x USD 200 monthly programmatic credit, then API rates above.
+  Set CC_AGENT_VIEW_QUIET=1 to suppress.
+EOF
+fi
+
+exit 0