cc-safe-setup 29.7.0 → 30.0.4

package/examples/auth-expiry-reminder.sh

@@ -0,0 +1,157 @@
+#!/bin/bash
+# auth-expiry-reminder.sh — Daily checkpoint reminder for authentication-state verification
+# in long-running Claude Code sessions (Cluster 19 candidate, axes 19C / 19G)
+#
+# Background:
+#   Cluster 19 candidate (Authentication Silent Failure) — 39+ open Claude Code issues
+#   filed 2026-05-14 through 2026-05-30 document a pattern where the operator's
+#   authentication state silently lapses across multiple surfaces. Two axes within
+#   the cluster are most cost-effective to address with a daily checkpoint:
+#
+#     19C — Session expiry silent failure
+#           (#60938 / #62354 HIGH BLOCKER / #61912 / #63919 2026-05-30 fresh)
+#     19G — Third-party SSO silent expiry
+#           (#63185 3P Bedrock SSO day-2+ / #62103 Brave Search API)
+#
+#   The shared structural shape: the auth surface reports success at one point in
+#   time, the operator works for a while, then a downstream call returns 401 /
+#   "Not logged in" / "Needs authentication" with no upstream signal that re-auth
+#   was required. The cost is the productive work that hit the silent failure
+#   mid-execution — recovery is gated behind a re-auth that may itself be in the
+#   failed state (per #60938).
+#
+#   The checkpoint pattern: at the start of each calendar day, before the first
+#   substantive request, verify the auth surface state. Day-2 silent expiry
+#   surfaces only when a downstream call fails — a deliberate checkpoint moves
+#   the discovery from mid-task failure to a controlled boundary.
+#
+#   Companion hook: auth-status-checker.sh (PR #490) names the full five-mitigation
+#   menu; this hook focuses on the time-based daily checkpoint specifically.
+#
+#   Reference:
+#     https://gist.github.com/yurukusa/58cb17bfda4d5ab31bd804809809d22f  (field guide)
+#
+# What this hook does:
+#   On SessionStart, when CC_AUTH_EXPIRY_REMINDER_REMIND=1 is set, checks whether
+#   the operator has already been reminded today (based on a date-stamped state
+#   file). If today's reminder has not fired, emits a short stderr advisory
+#   naming the two verification commands (Anthropic /account; the operator's own
+#   3P credential check) and stamps the state file to suppress the reminder for
+#   the rest of the calendar day.
+#
+#   The state file resets at the calendar-day boundary. The next morning's
+#   session start fires the reminder again, before the day's first substantive
+#   request.
+#
+# When this hook does NOT emit anything:
+#   - CC_AUTH_EXPIRY_REMINDER_REMIND is unset or empty
+#   - CC_AUTH_EXPIRY_REMINDER_DISABLE=1
+#   - CC_AUTH_EXPIRY_REMINDER_QUIET=1
+#   - Today's reminder has already been emitted (state file matches today's date)
+#
+# Hook config (settings.json):
+# {
+#   "hooks": {
+#     "SessionStart": [{
+#       "matcher": "",
+#       "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/auth-expiry-reminder.sh" }]
+#     }]
+#   }
+# }
+# And in your shell rc, opt in:
+#   export CC_AUTH_EXPIRY_REMINDER_REMIND=1
+#
+# Env vars:
+#   CC_AUTH_EXPIRY_REMINDER_REMIND=1   — opt-in trigger (required to emit)
+#   CC_AUTH_EXPIRY_REMINDER_DISABLE=1  — never emit
+#   CC_AUTH_EXPIRY_REMINDER_QUIET=1    — silent
+#   CC_AUTH_EXPIRY_REMINDER_STATE_DIR=<path> — state dir (default $HOME/.claude)
+#   CC_AUTH_EXPIRY_REMINDER_DATE=<YYYY-MM-DD> — date override (tests only)
+#
+# Design notes:
+#   - One-shot per calendar day. The reminder fires at the first SessionStart of
+#     the day and stays silent for the rest of the day. Multi-session operators
+#     do not get the same reminder N times.
+#   - Calendar-day boundary, not 24-hour rolling. A session at 23:55 followed by
+#     a session at 00:05 the next day correctly fires the next-day reminder, even
+#     though only 10 minutes have passed.
+#   - Companion to auth-status-checker. The checker hook names the full mitigation
+#     menu when the operator wants to read it; this hook is the daily-cadence
+#     trigger that surfaces specifically the two checkpoint commands.
+#   - Never blocks. Exit always 0.
+
+set -u
+
+# Hard disable path
+if [ "${CC_AUTH_EXPIRY_REMINDER_DISABLE:-0}" = "1" ]; then
+  exit 0
+fi
+
+# Quiet path
+if [ "${CC_AUTH_EXPIRY_REMINDER_QUIET:-0}" = "1" ]; then
+  exit 0
+fi
+
+# Opt-in gate
+if [ "${CC_AUTH_EXPIRY_REMINDER_REMIND:-0}" != "1" ]; then
+  exit 0
+fi
+
+# Resolve today's date (allow override for tests)
+TODAY="${CC_AUTH_EXPIRY_REMINDER_DATE:-}"
+if [ -z "$TODAY" ]; then
+  TODAY=$(date '+%Y-%m-%d' 2>/dev/null) || exit 0
+fi
+
+STATE_DIR="${CC_AUTH_EXPIRY_REMINDER_STATE_DIR:-$HOME/.claude}"
+mkdir -p "$STATE_DIR" 2>/dev/null || exit 0
+STATE_FILE="$STATE_DIR/auth-expiry-reminder.last"
+
+# Check whether today's reminder has already fired
+if [ -f "$STATE_FILE" ]; then
+  LAST_DATE=$(head -1 "$STATE_FILE" 2>/dev/null)
+  if [ "$LAST_DATE" = "$TODAY" ]; then
+    exit 0
+  fi
+fi
+
+# Stamp the state file with today's date before emitting (so a hook that crashes
+# mid-emit does not re-fire on the next invocation).
+printf '%s\n' "$TODAY" > "$STATE_FILE" 2>/dev/null || true
+
+cat >&2 <<EOF
+[auth-expiry-reminder] Daily authentication checkpoint ($TODAY).
+
+Cluster 19 candidate (Authentication Silent Failure) documents 39+ open Claude
+Code issues where authentication state silently lapses between sessions. Day-2
+silent expiry surfaces only when a downstream call fails — a deliberate
+checkpoint at the day's first session moves the discovery from mid-task failure
+to a controlled boundary.
+
+Before the first substantive request of the day, verify:
+
+  1) Anthropic auth surface — run /account and confirm authenticated state.
+     If "Not authenticated," re-auth before the next operation.
+
+  2) Third-party credential chains — for each 3P credential your workflow
+     depends on (Bedrock, Brave Search API, MCP OAuth servers, etc.), run the
+     credential's verification command. For Bedrock SSO this is typically
+     'aws sts get-caller-identity' or equivalent. Day-2+ silent expiry is the
+     specific failure mode at #63185.
+
+References for the silent-failure patterns this checkpoint catches:
+  https://github.com/anthropics/claude-code/issues/62354  (HIGH BLOCKER session expiry)
+  https://github.com/anthropics/claude-code/issues/63919  (2026-05-30 fresh, macOS)
+  https://github.com/anthropics/claude-code/issues/63185  (3P Bedrock SSO day-2+)
+  https://gist.github.com/yurukusa/58cb17bfda4d5ab31bd804809809d22f  (field guide)
+
+This reminder fires once per calendar day. To turn it off:
+  unset CC_AUTH_EXPIRY_REMINDER_REMIND
+  # or
+  export CC_AUTH_EXPIRY_REMINDER_QUIET=1
+
+Companion hook: auth-status-checker.sh names the full five-mitigation menu
+when you need the broader Cluster 19 context.
+EOF
+
+exit 0

package/examples/auth-macos-sleep-detector.sh

@@ -0,0 +1,185 @@
+#!/bin/bash
+# auth-macos-sleep-detector.sh — Detect recent macOS sleep/wake and advise auth re-verification
+# (Cluster 19 candidate, axis 19B — macOS sleep/wake silent auth invalidation)
+#
+# Background:
+#   Cluster 19 candidate axis 19B documents a class of authentication failures
+#   where macOS suspends the system mid-session, the auth token times out
+#   during the sleep window, and the user only sees the failure after the next
+#   prompt — silent expiration without a refresh signal.
+#
+#   Anchor cases in axis 19B:
+#     #59937 — Claude Code session loses MCP auth after macOS wake from sleep
+#     #60104 — Persistent 401 after laptop close/open cycle, no visible expiry signal
+#
+#   The structural shape: a session that was healthy before sleep returns 401
+#   or "not authenticated" on the first tool call after wake, even though the
+#   visible CLI state shows the same authenticated user. The recovery requires
+#   running the auth-status-checker advisory or executing `/login` manually —
+#   not just retrying the failed tool call.
+#
+#   This hook is a SessionStart advisory that fires when:
+#     - the operating system is macOS (uname -s == Darwin), AND
+#     - pmset reports a Wake event within the last CC_AUTH_MACOS_SLEEP_WINDOW
+#       seconds (default 1800 = 30 minutes), AND
+#     - the operator has not already seen the advisory in this session
+#
+#   The advisory recommends running `bash ~/.claude/hooks/auth-status-checker.sh`
+#   with CC_AUTH_STATUS_REMIND=1 to verify the token's freshness before the
+#   first tool call of the post-wake session.
+#
+#   Reference:
+#     https://gist.github.com/yurukusa/58cb17bfda4d5ab31bd804809809d22f (auth cluster field guide)
+#
+# When this hook does NOT emit anything:
+#   - CC_AUTH_MACOS_SLEEP_DISABLE=1
+#   - CC_AUTH_MACOS_SLEEP_QUIET=1
+#   - the operating system is not macOS (Linux, WSL, etc.)
+#   - pmset is unavailable or returns no recent Wake event
+#   - the advisory has already fired in this session
+#
+# Hook config (settings.json):
+# {
+#   "hooks": {
+#     "SessionStart": [{
+#       "matcher": "",
+#       "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/auth-macos-sleep-detector.sh" }]
+#     }]
+#   }
+# }
+#
+# Env vars:
+#   CC_AUTH_MACOS_SLEEP_DISABLE=1       — never emit
+#   CC_AUTH_MACOS_SLEEP_QUIET=1         — silent (process but never write to stderr)
+#   CC_AUTH_MACOS_SLEEP_WINDOW=<secs>   — wake-event freshness threshold (default 1800)
+#   CC_AUTH_MACOS_SLEEP_STATE_DIR=<p>   — one-shot state dir override (default ~/.claude/state)
+#   CC_AUTH_MACOS_SLEEP_SESSION_ID=<id> — session id override (tests)
+#   CC_AUTH_MACOS_SLEEP_FORCE_OS=<os>   — uname -s override (tests; use "Darwin"/"Linux")
+#   CC_AUTH_MACOS_SLEEP_PMSET_CMD=<cmd> — pmset binary override (tests; e.g. a stub script)
+#
+# Design notes:
+#   - Opt-out. Like oauth-refresh-monitor.sh, the signal is specific (macOS +
+#     recent wake event) and the cost of missing the advisory (silent 401 loop
+#     until the operator manually re-auths) exceeds the cost of a false advisory.
+#   - One-shot per session. The advisory fires once per session. A separate
+#     wake event in a long-running session does not re-fire — that would be
+#     covered by the PostToolUse oauth-refresh-monitor.sh signature scan.
+#   - Never blocks. Exit always 0. The auth state recovery is operator-action;
+#     a blocking hook would only add pain.
+#   - Non-macOS systems exit silently. Linux/WSL/other do not have the same
+#     sleep/wake auth invalidation pattern; the hook is a no-op there.
+#   - Test-friendly. The OS detection and pmset command are both overridable
+#     via env vars so the test harness can simulate Darwin + recent wake on
+#     any platform.
+
+set -u
+
+# Disable switch — exit silently if disabled
+if [[ "${CC_AUTH_MACOS_SLEEP_DISABLE:-0}" = "1" ]]; then
+    exit 0
+fi
+
+# OS detection (overridable for tests)
+OS_NAME="${CC_AUTH_MACOS_SLEEP_FORCE_OS:-$(uname -s 2>/dev/null || echo unknown)}"
+if [[ "$OS_NAME" != "Darwin" ]]; then
+    exit 0
+fi
+
+# pmset command resolution
+PMSET_CMD="${CC_AUTH_MACOS_SLEEP_PMSET_CMD:-pmset}"
+if ! command -v "$PMSET_CMD" >/dev/null 2>&1 && [[ ! -x "$PMSET_CMD" ]]; then
+    exit 0
+fi
+
+# Wake-event freshness threshold in seconds (default 1800 = 30 minutes)
+WINDOW="${CC_AUTH_MACOS_SLEEP_WINDOW:-1800}"
+if ! [[ "$WINDOW" =~ ^[0-9]+$ ]]; then
+    WINDOW=1800
+fi
+
+# State directory and one-shot guard
+STATE_DIR="${CC_AUTH_MACOS_SLEEP_STATE_DIR:-$HOME/.claude/state}"
+mkdir -p "$STATE_DIR" 2>/dev/null
+
+SESSION_ID="${CC_AUTH_MACOS_SLEEP_SESSION_ID:-${CLAUDE_SESSION_ID:-default}}"
+GUARD_FILE="$STATE_DIR/auth-macos-sleep-${SESSION_ID}.fired"
+
+if [[ -f "$GUARD_FILE" ]]; then
+    exit 0
+fi
+
+# Read pmset log and find the most recent Wake event
+# pmset -g log emits lines like:
+#   2026-05-31 18:42:15 +0900 Wake               Wake from Normal Sleep ...
+# We grep for "Wake" and parse the last entry's timestamp.
+PMSET_OUTPUT=$("$PMSET_CMD" -g log 2>/dev/null | grep -E '\bWake\b' | tail -1)
+
+if [[ -z "$PMSET_OUTPUT" ]]; then
+    exit 0
+fi
+
+# Extract timestamp (first two fields: "YYYY-MM-DD HH:MM:SS")
+WAKE_TS_STR=$(echo "$PMSET_OUTPUT" | awk '{print $1, $2}')
+
+# Convert wake timestamp to epoch
+# macOS date: date -j -f "%Y-%m-%d %H:%M:%S" "..." +%s
+# Linux date: date -d "..." +%s
+WAKE_EPOCH=$(date -j -f "%Y-%m-%d %H:%M:%S" "$WAKE_TS_STR" +%s 2>/dev/null)
+if [[ -z "$WAKE_EPOCH" ]] || ! [[ "$WAKE_EPOCH" =~ ^[0-9]+$ ]]; then
+    # Fallback for GNU date
+    WAKE_EPOCH=$(date -d "$WAKE_TS_STR" +%s 2>/dev/null)
+fi
+
+if [[ -z "$WAKE_EPOCH" ]] || ! [[ "$WAKE_EPOCH" =~ ^[0-9]+$ ]]; then
+    exit 0
+fi
+
+NOW_EPOCH=$(date +%s)
+GAP=$(( NOW_EPOCH - WAKE_EPOCH ))
+
+if [[ $GAP -lt 0 ]] || [[ $GAP -gt $WINDOW ]]; then
+    exit 0
+fi
+
+# Mark one-shot guard
+touch "$GUARD_FILE" 2>/dev/null
+
+# Quiet mode: process but do not write to stderr
+if [[ "${CC_AUTH_MACOS_SLEEP_QUIET:-0}" = "1" ]]; then
+    exit 0
+fi
+
+# Emit advisory
+cat >&2 <<EOF
+
+────────────────────────────────────────────────────────────────────
+  Auth advisory — Cluster 19 axis 19B (macOS sleep/wake)
+────────────────────────────────────────────────────────────────────
+  macOS Wake event detected ${GAP}s ago (within ${WINDOW}s window).
+
+  The Cluster 19 axis 19B pattern: a session healthy before sleep
+  may return 401 on the first tool call after wake — the auth token
+  silently expires during the sleep window with no refresh signal.
+
+  Anchor cases: #59937, #60104.
+
+  Recommended check (run once before the first tool call):
+
+    CC_AUTH_STATUS_REMIND=1 bash ~/.claude/hooks/auth-status-checker.sh
+
+  If the check reports a stale token, run:
+
+    /login
+
+  to refresh the auth state cleanly. A bare retry of the failing tool
+  call will loop the 401 silently.
+
+  Field guide: https://gist.github.com/yurukusa/58cb17bfda4d5ab31bd804809809d22f
+
+  (This advisory fires once per session. To disable:
+   export CC_AUTH_MACOS_SLEEP_DISABLE=1)
+────────────────────────────────────────────────────────────────────
+
+EOF
+
+exit 0

package/examples/auth-path-detector.sh

@@ -0,0 +1,171 @@
+#!/bin/bash
+# ================================================================
+# auth-path-detector.sh — Warn before driving an auth/login flow,
+#                        especially on a resource that the user did
+#                        not explicitly authorize.
+# ================================================================
+# PURPOSE:
+#   When the next tool call appears to navigate to or operate on an
+#   authentication path (login page, OAuth authorization endpoint,
+#   credential entry form, SSO/SAML callback), emit a warning so the
+#   operator can confirm that the resource is the one the user
+#   permitted. Prevents the failure mode reported in Issue #55909
+#   (Cowork mode) where a halt signal was followed by the model
+#   driving a login flow on a different browser identifier than the
+#   user had limited the work to.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash|WebFetch|WebSearch|mcp__.*__(go|navigate|click|form)"
+#   In practice, configure with a broad matcher; this script inspects
+#   the tool input and exits silently when no auth indicator is found.
+#
+# WHY THIS MATTERS:
+#   In Issue #55909, the user limited operations to a remote browser,
+#   but the model continued to a different browser when one operation
+#   failed and opened a login page there. Authentication context is
+#   bound to a browser/profile identifier; driving a login flow on
+#   the wrong identifier silently writes credentials into the wrong
+#   trust boundary. The user's repeated halt signals were reframed
+#   as "let me just do this one part" — bargaining language that the
+#   halt-signal-detector hook also checks.
+#
+#   This hook is a complementary check at the auth-path boundary.
+#   Even when the halt signal is absent, an auth flow on a non-
+#   authorized resource is high-stakes and should be confirmed.
+#
+# WHAT IT CHECKS:
+#   1. Read the tool name and tool_input from the PreToolUse payload
+#   2. Extract the URL/command/text fields most likely to contain a
+#      navigation target
+#   3. Search for auth-path indicators (login, signin, oauth, etc.)
+#   4. If found, emit a warning to stderr with the matched substring
+#   5. If CC_AUTH_PATH_BLOCK=1, also exit 2 to block the tool call
+#
+# OUTPUT:
+#   Warning to stderr with the matched indicator and a reference to
+#   Issue #55909. Exit 0 (advisory) by default.
+#
+# CONFIGURATION:
+#   CC_AUTH_PATH_BLOCK    — set to "1" to block the tool call (exit 2)
+#                          when an auth-path indicator is detected.
+#                          Default is advisory only.
+#   CC_AUTH_PATH_EXTRA    — additional comma-separated path tokens to
+#                          match (case-insensitive). Example:
+#                          "verify,callback".
+#   CC_AUTH_PATH_ALLOW    — comma-separated substrings; if the matched
+#                          URL/command contains any, suppress the
+#                          warning. Use to whitelist intentional
+#                          flows (e.g. "localhost:3000/login").
+#
+# RELATED ISSUES:
+#   https://github.com/anthropics/claude-code/issues/55909
+# ================================================================
+
+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-auth-path-detector-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [auth-path-detector]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+INPUT=$(cat)
+
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+
+if [ -z "$TOOL_NAME" ]; then
+    exit 0
+fi
+
+# Pull every plausible string field from tool_input where a URL or
+# auth-path command might live. Concatenate them so a single regex
+# pass covers the relevant surface.
+HAYSTACK=$(printf '%s' "$INPUT" | jq -r '
+    def s($v): if ($v | type) == "string" then $v else "" end;
+    [
+      s(.tool_input.url),
+      s(.tool_input.URL),
+      s(.tool_input.command),
+      s(.tool_input.prompt),
+      s(.tool_input.query),
+      s(.tool_input.path),
+      s(.tool_input.target),
+      s(.tool_input.location),
+      s(.tool_input.address),
+      s(.tool_input.endpoint),
+      s(.tool_input.text),
+      s(.tool_input.value)
+    ] | join(" ")
+' 2>/dev/null)
+
+if [ -z "$HAYSTACK" ] || [ "$HAYSTACK" = "         " ]; then
+    exit 0
+fi
+
+# Auth path indicators. Each token is matched case-insensitively
+# against the haystack. The patterns are conservative to keep false
+# positives low — they expect URL-style separators or word
+# boundaries.
+#
+# Notes on selection:
+# - /login, /signin, /sign-in, /log-in are the most common form paths
+# - /oauth, /authorize, /authorization cover OAuth grant entry points
+# - /sso, /saml cover federation callbacks
+# - /credentials, /password, /reset-password cover credential entry
+# - login.microsoftonline.com / accounts.google.com are concrete IdPs
+# - Japanese surface: ログイン, 認証, 認可
+AUTH_BASE='/login\b|/log-in\b|/signin\b|/sign-in\b|/sign_in\b|/log_in\b|/oauth\b|/oauth2\b|/authorize\b|/authorization\b|/sso\b|/saml\b|/openid\b|/credentials?\b|/password\b|/reset-password\b|/forgot-password\b|/auth/callback\b|/auth/token\b|login\.microsoftonline\.com|accounts\.google\.com|auth0\.com|okta\.com|github\.com/login|gitlab\.com/users/sign_in|ログイン|サインイン|認証ページ|ログインページ'
+
+EXTRA="${CC_AUTH_PATH_EXTRA:-}"
+if [ -n "$EXTRA" ]; then
+    EXTRA_PATTERN=$(printf '%s' "$EXTRA" | tr ',' '|')
+    AUTH_PATTERN="${AUTH_BASE}|${EXTRA_PATTERN}"
+else
+    AUTH_PATTERN="$AUTH_BASE"
+fi
+
+MATCH=$(printf '%s' "$HAYSTACK" | grep -oiE "$AUTH_PATTERN" | head -1)
+
+if [ -z "$MATCH" ]; then
+    exit 0
+fi
+
+# Allowlist: suppress when the haystack contains a permitted substring
+ALLOW="${CC_AUTH_PATH_ALLOW:-}"
+if [ -n "$ALLOW" ]; then
+    OLDIFS=$IFS
+    IFS=','
+    for token in $ALLOW; do
+        token_trimmed=$(printf '%s' "$token" | sed 's/^ *//;s/ *$//')
+        if [ -n "$token_trimmed" ] && printf '%s' "$HAYSTACK" | grep -qiF "$token_trimmed"; then
+            IFS=$OLDIFS
+            exit 0
+        fi
+    done
+    IFS=$OLDIFS
+fi
+
+SNIPPET=$(printf '%s' "$HAYSTACK" | head -c 200 | tr '\n' ' ')
+cat >&2 <<EOF
+🔐 auth-path-detector: 道具の呼び出しが認証の経路に向かっています。
+  道具: ${TOOL_NAME}
+  検出した目印: ${MATCH}
+  文脈の冒頭: ${SNIPPET}
+  確認のお願い:
+    1. この資源 (ブラウザ、 識別子、 場所) は利用者が明示的に許可したものですか
+    2. 認証の文脈はブラウザの識別子に紐付いています。 別の識別子で操作すると、 認証の合図が別の信頼の境界に書き込まれます
+    3. 利用者の停止の合図 (やめて、 stop など) があった直後の認証の経路の駆動は、 部分的な協力の依頼に見えます
+  Reference: https://github.com/anthropics/claude-code/issues/55909
+EOF
+
+if [ "${CC_AUTH_PATH_BLOCK:-0}" = "1" ]; then
+    exit 2
+fi
+
+exit 0

package/examples/auth-status-checker.sh

@@ -0,0 +1,157 @@
+#!/bin/bash
+# auth-status-checker.sh — Surface the Cluster 19 candidate (Authentication Silent Failure)
+# situation at session start for operators running long sessions or 3P credential chains
+#
+# Background:
+#   In the 17 days between 2026-05-14 and 2026-05-30, anthropics/claude-code accumulated
+#   at least 39 open issues related to authentication silent failure. The unifying root
+#   mechanism: the operator sees an authentication success signal at one point in time
+#   and discovers — sometimes hours, sometimes days later — that the authenticated state
+#   has silently lapsed. The user-side experience is identical across surfaces: log in
+#   successfully, work for a while, hit a 401 / "Not logged in" / "Needs authentication"
+#   / 403 error wall, with no upstream signal that re-auth was required.
+#
+#   This is the same structural shape as Cluster 1 (Sub-agent Observability — "done"
+#   report with empty tool calls) and Cluster 11F (Cowork handoff silent failure —
+#   completed result that never relays back): a positive-looking surface signal that
+#   does not reflect the underlying state.
+#
+#   Seven sub-cluster axes documented (2026-05-30):
+#     19A MCP OAuth failure paths (#59460 / #59725 / #60260 / #61139)
+#     19B macOS sleep/wake invalidation (#59937 / #60104)
+#     19C Session expiry silent failure (#60938 / #62354 HIGH BLOCKER /
+#         #61912 / #63919 2026-05-30 fresh)
+#     19D VS Code extension forced daily re-login (#61923)
+#     19E Multi-window auth state inconsistency (#62790)
+#     19F Cowork authentication failure (#61563, intersection with Cluster 11)
+#     19G Third-party SSO silent expiry (#63185 3P Bedrock SSO day-2+ / #62103)
+#
+#   Cluster 19 is still a candidate; tracked at cluster-tracker.html pending full
+#   promotion criteria (15+ aggregate reactions or tenth independent axis surfacing).
+#
+#   Reference:
+#     https://gist.github.com/yurukusa/58cb17bfda4d5ab31bd804809809d22f  (field guide)
+#
+# What this hook does:
+#   On SessionStart, when CC_AUTH_STATUS_CHECKER_REMIND=1 is set, emits a stderr
+#   advisory naming the five operator-side mitigations from the Cluster 19 field
+#   guide. The hook is fully opt-in — silent by default. The advisory does not
+#   try to detect the operator's auth surface state; auto-detection across MCP,
+#   VS Code, Cowork, Bedrock, and macOS sleep/wake would be unreliable, and a
+#   wrong guess is worse than no guess.
+#
+# When this hook does NOT emit anything:
+#   - CC_AUTH_STATUS_CHECKER_REMIND is unset or empty
+#   - CC_AUTH_STATUS_CHECKER_DISABLE=1
+#   - CC_AUTH_STATUS_CHECKER_QUIET=1
+#
+# Hook config (settings.json):
+# {
+#   "hooks": {
+#     "SessionStart": [{
+#       "matcher": "",
+#       "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/auth-status-checker.sh" }]
+#     }]
+#   }
+# }
+# And in your shell rc, opt in:
+#   export CC_AUTH_STATUS_CHECKER_REMIND=1
+#
+# Env vars:
+#   CC_AUTH_STATUS_CHECKER_REMIND=1   — opt-in trigger (required to emit)
+#   CC_AUTH_STATUS_CHECKER_DISABLE=1  — never emit (overrides REMIND)
+#   CC_AUTH_STATUS_CHECKER_QUIET=1    — silent (overrides REMIND)
+#
+# Design notes:
+#   - Opt-in by default. The advisory is only useful to operators with long sessions,
+#     3P credential chains, multi-machine VS Code, or macOS sleep/wake patterns.
+#     Defaulting silent avoids noise for short-session single-surface operators.
+#   - No auto-detection of auth surface. Operators may use MCP, VS Code, Cowork,
+#     Bedrock, Brave, or any combination simultaneously; detecting which surfaces
+#     are active would require shell-side env var inspection and would still miss
+#     in-process credential state. The advisory lets the operator self-select the
+#     applicable mitigations.
+#   - Candidate-cluster framing. The advisory clearly states Cluster 19 is a
+#     candidate (not yet promoted) and links the field guide for the full context.
+#   - Never blocks. Exit always 0.
+
+set -u
+
+# Hard disable path
+if [ "${CC_AUTH_STATUS_CHECKER_DISABLE:-0}" = "1" ]; then
+  exit 0
+fi
+
+# Quiet path
+if [ "${CC_AUTH_STATUS_CHECKER_QUIET:-0}" = "1" ]; then
+  exit 0
+fi
+
+# Opt-in gate
+if [ "${CC_AUTH_STATUS_CHECKER_REMIND:-0}" != "1" ]; then
+  exit 0
+fi
+
+cat >&2 <<'EOF'
+[auth-status-checker] Cluster 19 candidate advisory: authentication state can
+silently lapse across multiple Claude Code surfaces. 39+ open issues filed in
+the 17 days from 2026-05-14 to 2026-05-30 document seven structural surfaces:
+
+  19A MCP OAuth failure paths (DCR re-runs, empty accessToken, token-expired loop)
+  19B macOS sleep/wake invalidation (401 persists, full reboot to clear)
+  19C Session expiry silent failure (HIGH BLOCKER: #62354, fresh: #63919 2026-05-30)
+  19D VS Code extension forced daily re-login on multi-machine shared accounts
+  19E Multi-window /account state inconsistency after one window logs in/out
+  19F Cowork authentication failure (intersection with Cluster 11)
+  19G Third-party SSO silent expiry (Bedrock day-2+, Brave API credentials)
+
+The unifying pattern: log in succeeds, the session reports success, and then
+hours or days later a downstream call returns 401 / "Not logged in" / 403 with
+no upstream signal that re-auth was required. Cost: the operator's productive
+work that hit the silent failure mid-execution is lost, and re-auth is gated
+behind a session that may itself be in the failed state (per #60938).
+
+Five operator-side mitigations (apply the ones that match your surface):
+
+  1) Periodic /account health check (axes 19C / 19G)
+     For long sessions, run /account every 30-60 minutes. When the check
+     returns "Not authenticated," re-auth before the next substantive
+     operation rather than discovering the expiry mid-task.
+
+  2) Single-window discipline for auth changes (axis 19E)
+     Close all Claude Code windows before any explicit re-auth. After
+     re-auth, open new windows rather than reusing existing ones.
+
+  3) CLI preference over VS Code extension for shared accounts (axis 19D)
+     If the same Anthropic account is used across multiple machines,
+     prefer the CLI. The extension's refresh-token rejection on shared
+     accounts is the specific failure mode.
+
+  4) Daily re-auth checkpoint for third-party SSO (axis 19G)
+     Build a daily morning checkpoint: run /account and verify any 3P
+     credentials (Bedrock, Brave Search API) before the first
+     substantive request. Day-2 silent expiry surfaces only when a
+     downstream call fails — a deliberate checkpoint prevents that loss.
+
+  5) Scheduled reboot for macOS sleep/wake (axis 19B)
+     If your workflow has consistent overnight sleep, schedule a morning
+     reboot. The 401 state persists across explicit re-auth and only
+     clears on full reboot per #60104.
+
+This is a candidate cluster — full Cluster 19 promotion happens when
+cumulative reactions cross 15 or a tenth independent axis surfaces. The
+cc-safe-setup tracker (cluster-tracker.html) records the current state.
+
+To silence this advisory once you have applied the relevant mitigations:
+  unset CC_AUTH_STATUS_CHECKER_REMIND
+  # or
+  export CC_AUTH_STATUS_CHECKER_QUIET=1
+
+References:
+  https://github.com/anthropics/claude-code/issues/63919  (2026-05-30 fresh)
+  https://github.com/anthropics/claude-code/issues/63185  (3P Bedrock SSO day-2+)
+  https://github.com/anthropics/claude-code/issues/62354  (HIGH BLOCKER session expiry)
+  https://gist.github.com/yurukusa/58cb17bfda4d5ab31bd804809809d22f  (field guide)
+EOF
+
+exit 0