cc-safe-setup 29.7.0 → 30.0.4

package/scripts/june-15-deprecated-model-scan.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+# june-15-deprecated-model-scan.sh — Find hardcoded Claude model IDs that
+#   stop working on 2026-06-15 (and other retirement dates) before they break
+#   your code or CI with a hard error.
+#
+# Why this exists: the 2026-06-15 Anthropic change is widely explained as a
+#   *billing* change (programmatic usage moves to a separate credit pool). But
+#   the same date also *retires two model IDs from the API*. After retirement,
+#   a request using a retired model ID returns a hard error (HTTP 404,
+#   not_found_error) — your app or CI breaks, regardless of billing. The fix is
+#   mechanical: bump the hardcoded ID to its replacement. This script finds the
+#   IDs for you so nothing 404s on the 15th.
+#
+# What this does: a read-only grep of the directory you run it from for
+#   retired / soon-to-retire model ID strings, and prints each hit with its
+#   replacement. It does NOT modify any file, run any tool, or send any network
+#   request. All checks are local string matches.
+#
+# Usage:
+#   bash june-15-deprecated-model-scan.sh            # scan current directory
+#   bash june-15-deprecated-model-scan.sh path/to/repo
+#
+# Exit codes: 0 = no retired/soon-to-retire IDs found; 1 = found at least one.
+#   (CI-friendly: a non-zero exit fails the build so you fix it before the date.)
+#
+# Sources (Anthropic official model deprecations / migration guide):
+#   https://platform.claude.com/docs/en/about-claude/models/overview
+#   https://platform.claude.com/docs/en/about-claude/models/migration-guide
+# License: MIT. Author: yurukusa.
+
+set -uo pipefail
+
+ROOT="${1:-.}"
+
+# Each row: <deprecated-id>|<retirement-date>|<replacement-id>
+# Dates and replacements verified against Anthropic's official model docs.
+# The two 2026-06-15 IDs are the ones that retire *on the cliff date*.
+DEPRECATIONS=(
+  "claude-opus-4-20250514|2026-06-15|claude-opus-4-8"
+  "claude-sonnet-4-20250514|2026-06-15|claude-sonnet-4-6"
+  "claude-3-haiku-20240307|2026-04-19|claude-haiku-4-5"
+  # Already retired (return 404 today) — listed so you catch leftovers:
+  "claude-3-7-sonnet-20250219|2026-02-19 (retired)|claude-sonnet-4-6"
+  "claude-3-5-haiku-20241022|2026-02-19 (retired)|claude-haiku-4-5"
+  "claude-3-opus-20240229|2026-01-05 (retired)|claude-opus-4-8"
+  "claude-3-5-sonnet-20241022|2025-10-28 (retired)|claude-sonnet-4-6"
+  "claude-3-5-sonnet-20240620|2025-10-28 (retired)|claude-sonnet-4-6"
+  "claude-3-sonnet-20240229|2025-07-21 (retired)|claude-sonnet-4-6"
+)
+
+# Directories that never contain your source — skip to keep output clean.
+PRUNE='-path */node_modules/* -o -path */.git/* -o -path */dist/* -o -path */build/* -o -path */.venv/* -o -path */venv/* -o -path */__pycache__/*'
+
+echo "June 15 (and beyond) deprecated Claude model ID scan"
+echo "Scanning: $ROOT"
+echo "----------------------------------------------------------------------"
+
+found=0
+cliff_found=0
+
+for row in "${DEPRECATIONS[@]}"; do
+  id="${row%%|*}"
+  rest="${row#*|}"
+  date="${rest%%|*}"
+  repl="${rest#*|}"
+
+  # Read-only: grep for the literal ID across text files. -I skips binaries.
+  # shellcheck disable=SC2086
+  hits="$(find "$ROOT" -type f \( $PRUNE \) -prune -o -type f -print 2>/dev/null \
+            | xargs -r grep -InF -- "$id" 2>/dev/null)"
+
+  if [ -n "$hits" ]; then
+    found=1
+    case "$date" in
+      2026-06-15) cliff_found=1; flag="⛔ RETIRES ON THE 2026-06-15 CLIFF" ;;
+      *retired*)  flag="⚠  ALREADY RETIRED (returns 404 today)" ;;
+      *)          flag="⚠  retires $date" ;;
+    esac
+    echo
+    echo "$flag"
+    echo "  Deprecated: $id"
+    echo "  Replace with: $repl"
+    echo "  Found in:"
+    echo "$hits" | sed 's/^/    /'
+  fi
+done
+
+echo
+echo "----------------------------------------------------------------------"
+if [ "$found" -eq 0 ]; then
+  echo "✅ No retired or soon-to-retire model IDs found. Nothing breaks on 2026-06-15."
+  exit 0
+fi
+
+if [ "$cliff_found" -eq 1 ]; then
+  echo "Action: replace the IDs flagged ⛔ before 2026-06-15 — after that date"
+  echo "those requests return a hard 404 (not a billing message). The fix is the"
+  echo "ID swap shown above; no code logic changes."
+else
+  echo "Action: replace the flagged IDs with the current ones shown above."
+fi
+echo
+echo "Note: this finds *hardcoded* model strings. It does NOT detect the separate"
+echo "2026-06-15 billing change (claude -p / Agent SDK / GitHub Actions move to a"
+echo "separate credit pool). For that, see the free guides below."
+echo
+echo "Free, MIT — Claude Code safety hooks (rm -rf, secret leaks, force-push, more):"
+echo "  npx cc-safe-setup"
+echo "Free — the 2026-06-15 billing change, plain English (who's affected + 2 actions):"
+echo "  https://yurukusa.github.io/cc-safe-setup/claude-code-june-15-billing-change.html"
+exit 1

package/scripts/measure-heredoc-shapes.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# measure-heredoc-shapes.sh — 「本文の中に危険な語を書くだけ」の同じ意図を、何通りの綴りで書けるか。
+# そのうち何通りが門に止められるかを実測する。
+#
+# 見つかっていること（2026-09-16）:
+#   scope-guard.sh は本文を素通しする行を持っている（40行目 `^\s*(echo|printf|cat\s*<<)`）。
+#   つまり作者は本文の除外を意図していた。だが `cat > file <<'EOF'` の形は
+#   `cat` の直後が `>` なので `cat\s*<<` に当たらず、素通しの対象から外れる。
+#   ★同じことをする綴りが何通りあって、どれが当たり どれが外れるかを表にする。
+set -u
+REPO="$(cd "$(dirname "$0")/.." && pwd)"
+SANDBOX="$(mktemp -d)"
+trap 'chmod -R u+w "$SANDBOX" 2>/dev/null; find "$SANDBOX" -mindepth 1 -delete 2>/dev/null; rmdir "$SANDBOX" 2>/dev/null' EXIT
+mkdir -p "$SANDBOX/home/.claude" "$SANDBOX/work"
+
+HOOK="${1:-$REPO/examples/scope-guard.sh}"
+BODY='The guard fires when Claude Code runs rm -rf /home/someone/project by itself.'
+SAFE='The guard fires when Claude Code runs ls -la /home/someone/project by itself.'
+
+shapes() {  # $1 = 本文
+  local b="$1"
+  printf '%s\n' \
+    "cat > /tmp/note.md <<'EOF'|$b|EOF" \
+    "cat <<'EOF' > /tmp/note.md|$b|EOF" \
+    "cat <<'EOF'|$b|EOF" \
+    "tee /tmp/note.md <<'EOF'|$b|EOF" \
+    "python3 - <<'PY'|print(\"$b\")|PY" \
+    "echo \"$b\" > /tmp/note.md||" \
+    "printf '%s' \"$b\" > /tmp/note.md||" \
+    "git commit -m \"$b\"||"
+}
+
+run() {  # $1 = コマンド文字列
+  jq -cn --arg c "$1" '{hook_event_name:"PreToolUse",tool_name:"Bash",tool_input:{command:$c},cwd:"'"$SANDBOX/work"'"}' \
+    | timeout 5 env HOME="$SANDBOX/home" bash "$HOOK" >/dev/null 2>&1
+  echo $?
+}
+
+echo "門＝$(basename "$HOOK")"
+echo
+printf '%-42s %-10s %-10s %s\n' "綴り（本文に語を書くだけ・削除はしない）" "危険な語" "無害な語" "判定"
+printf '%s\n' "--------------------------------------------------------------------------------"
+mis=0; ok=0; shape=0
+while IFS= read -r line; do
+  IFS='|' read -r head body tail <<< "$line"
+  cmd="$head"
+  [ -n "$body" ] && cmd="$cmd
+$body"
+  [ -n "$tail" ] && cmd="$cmd
+$tail"
+  b=$(run "$cmd")
+  # 同じ綴りで、語だけ無害に差し替えたもの
+  safe_cmd="${cmd//rm -rf/ls -la}"
+  c=$(run "$safe_cmd")
+  if [ "$b" = "2" ] && [ "$c" != "2" ]; then verdict="★語で誤爆"; mis=$((mis+1))
+  elif [ "$b" = "2" ] && [ "$c" = "2" ]; then verdict="形ごと停止"; shape=$((shape+1))
+  else verdict="素通し"; ok=$((ok+1)); fi
+  printf '%-42s %-10s %-10s %s\n' "$(printf '%s' "$head" | cut -c1-40)" "exit $b" "exit $c" "$verdict"
+done < <(shapes "$BODY")
+echo
+echo "★語で誤爆 $mis 通り / 形ごと停止 $shape 通り / 素通し $ok 通り（全 8 通り）"
+echo
+echo "★この表の「誤爆」は機械の判定で、設計の意図とは別物。"
+echo "  2026-09-16 の直しのあとに1通りだけ残る python3 - <<'PY' は、意図して止めている:"
+echo "  ヒアドキュメントの本体が実行される受け手（bash/sh と、shell を呼びうるインタプリタ）は"
+echo "  本文として落とさない。誤って安心させる側の誤りのほうが高くつくため、安全側へ倒してある。"
+echo "  直す前は 4通りが誤爆だった（cat のリダイレクトが先／tee／python／コミットの伝言）。"

package/scripts/measure-literal-match-misfire.sh

@@ -0,0 +1,110 @@
+#!/bin/bash
+# measure-literal-match-misfire.sh — 配っているフックのうち、何本が「コマンドの中身」ではなく
+# 「コマンド文字列に含まれる語」で判定していて、本文の中の語だけで誤爆するかを実測する。
+#
+# なぜ必要か（2026-09-16 に自分で踏んだ）:
+#   販売文の下書きに "deleted project files with rm -rf" という一文を書いてヒアドキュメントで
+#   保存しようとしたら、PreToolUse のフックが exit 2 で止めた。削除は1件もしていない。
+#   フックが見ていたのはコマンドの意味ではなく、コマンド文字列そのものだった。
+#
+# 数え方（先に決める。後から境界を動かさない）:
+#   母数 = examples/*.sh のうち (1) tool_input.command を読む かつ (2) exit 2 を含む もの。
+#          この2つを満たさないフックは、そもそも Bash のコマンドを見て止める役ではない。
+#   危険側 (A) = 本当にその操作をするコマンド。止まるのが正しい。
+#   本文側 (B) = 同じ語が「ヒアドキュメントの中身」にあるだけで、その操作はしないコマンド。
+#                止まらないのが正しい。
+#   無害側 (C) = B とまったく同じ形で、危険な語だけを無害な語に置き換えたもの。
+#                ★これが無いと「B が止まった理由」が分からない。許可リスト方式のフックは
+#                  先頭の cat が許可されていないだけで止まるので、語とは無関係に B を止める。
+#                  C でも止まるなら、それは語の誤爆ではなく「その形を丸ごと止めている」。
+#   判定 = A で止まり、B で止まり、C で止まらない → ★語による誤爆（本文の語だけが原因）
+#          A で止まり、B で止まらない                → 正しく切り分けている
+#          B も C も止まる                           → 語とは無関係にその形を止めている
+#          A で止まらない                            → この入力の担当ではない
+#
+# 安全（フックを本当に実行するので、副作用を隔離する）:
+#   - HOME と cwd を使い捨ての一時ディレクトリへ差し替える（フックの書き込み先は $HOME 配下が大半）
+#   - cwd は git リポジトリにしない（git を叩くフックが実在のツリーへ触らないように）
+#   - 破壊的な操作を自分で実行するフックは、走らせる前に名前で除外する
+#     （2026-09-14 に test.sh の中の本物の git stash で作業ツリーを持って行かれた実績がある）
+#   - 各フックは timeout で切る
+set -u
+
+REPO="$(cd "$(dirname "$0")/.." && pwd)"
+EXAMPLES="$REPO/examples"
+SANDBOX="$(mktemp -d)"
+trap 'chmod -R u+w "$SANDBOX" 2>/dev/null; find "$SANDBOX" -mindepth 1 -delete 2>/dev/null; rmdir "$SANDBOX" 2>/dev/null' EXIT
+
+mkdir -p "$SANDBOX/home/.claude" "$SANDBOX/work"
+
+# 撃つ語の組。危険側と本文側で、含まれる語は同一にする（そこが対照の肝）。
+DANGER_CMD='rm -rf /tmp/some-scratch-dir'
+BODY_CMD="cat > /tmp/note.md <<'EOF'
+The guard fires when Claude Code runs rm -rf /tmp/some-scratch-dir by itself.
+EOF"
+# C＝Bと1語だけ違う。危険な語を無害な語へ置き換えてある（他は同一）
+HARMLESS_CMD="cat > /tmp/note.md <<'EOF'
+The guard fires when Claude Code runs ls -la /tmp/some-scratch-dir by itself.
+EOF"
+
+payload() {  # $1 = コマンド文字列
+  jq -cn --arg c "$1" \
+    '{hook_event_name:"PreToolUse", tool_name:"Bash", tool_input:{command:$c}, cwd:"'"$SANDBOX/work"'"}'
+}
+
+run_hook() {  # $1 = フックのパス, $2 = 入力のJSON。返すのは終了コード
+  printf '%s' "$2" | timeout 5 env HOME="$SANDBOX/home" \
+    bash "$1" >/dev/null 2>&1
+  echo $?
+}
+
+# 破壊的な操作を自分で実行するフックは走らせない（測る価値より事故の危険が大きい）
+DESTRUCTIVE_RE='git[[:space:]]+stash[[:space:]]+push|git[[:space:]]+reset[[:space:]]+--hard|git[[:space:]]+clean[[:space:]]+-|shutdown|reboot|pkill|killall'
+
+total=0; skipped=0; misfire=0; correct=0; notmine=0; shapeblock=0
+: > "$SANDBOX/misfire.txt"
+: > "$SANDBOX/correct.txt"
+: > "$SANDBOX/shape.txt"
+
+A_JSON="$(payload "$DANGER_CMD")"
+B_JSON="$(payload "$BODY_CMD")"
+C_JSON="$(payload "$HARMLESS_CMD")"
+
+for f in "$EXAMPLES"/*.sh; do
+  grep -q 'tool_input\.command' "$f" || continue
+  grep -qE '(^|[^0-9])exit[[:space:]]+2' "$f" || continue
+  total=$((total+1))
+  if grep -qE "$DESTRUCTIVE_RE" "$f"; then
+    skipped=$((skipped+1)); continue
+  fi
+  a=$(run_hook "$f" "$A_JSON")
+  b=$(run_hook "$f" "$B_JSON")
+  c=$(run_hook "$f" "$C_JSON")
+  name="$(basename "$f")"
+  if [ "$a" != "2" ]; then
+    notmine=$((notmine+1))
+  elif [ "$b" != "2" ]; then
+    correct=$((correct+1)); echo "$name" >> "$SANDBOX/correct.txt"
+  elif [ "$c" = "2" ]; then
+    # B も C も止まる＝語ではなく、その形（cat のヒアドキュメント）を丸ごと止めている
+    shapeblock=$((shapeblock+1)); echo "$name" >> "$SANDBOX/shape.txt"
+  else
+    misfire=$((misfire+1)); echo "$name" >> "$SANDBOX/misfire.txt"
+  fi
+done
+
+echo "母数（コマンドを読み、exit 2 を持つフック）: $total"
+echo "  走らせずに外した（破壊的な操作を自分でする）: $skipped"
+echo "  この入力の担当ではない（危険側でも止めない）: $notmine"
+echo "  ★正しい（危険側で止まり、本文側では止まらない）: $correct"
+echo "  ★語による誤爆（本文の語だけが原因。無害側では止まらない）: $misfire"
+echo "  その形を丸ごと止めている（語とは無関係。許可リスト方式など）: $shapeblock"
+echo
+echo "--- 語による誤爆 ---"
+cat "$SANDBOX/misfire.txt"
+echo
+echo "--- 正しく切り分けたフック ---"
+cat "$SANDBOX/correct.txt"
+echo
+echo "--- 形を丸ごと止めているフック（語とは無関係） ---"
+cat "$SANDBOX/shape.txt"

package/scripts/probe-scope-guard-branches.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# probe-scope-guard-branches.sh — scope-guard.sh が持つ4つの止める分岐すべてを撃って、
+# 2026-09-16 の書き直しで退行していないことを確かめる。
+#
+# probe-skip-line-both-ways.sh は「本文と本物の切り分け」を見る検査で、
+# 親ディレクトリへの脱出と、よく知られた利用者ディレクトリの2分岐を撃っていない。
+# 片方だけ直した状態を見逃す型（memory: fixed-one-rule-left-the-twin）を避けるために分ける。
+set -u
+REPO="$(cd "$(dirname "$0")/.." && pwd)"
+HOOK="$REPO/examples/scope-guard.sh"
+S="$(mktemp -d)"
+trap 'chmod -R u+w "$S" 2>/dev/null; find "$S" -mindepth 1 -delete 2>/dev/null; rmdir "$S" 2>/dev/null' EXIT
+mkdir -p "$S/home/.claude" "$S/work"
+
+DEL='rm -rf'
+ng=0
+probe() {
+    local got
+    jq -cn --arg c "$2" '{hook_event_name:"PreToolUse",tool_name:"Bash",tool_input:{command:$c},cwd:"'"$S/work"'"}' \
+        | timeout 5 env HOME="$S/home" bash "$HOOK" >/dev/null 2>&1
+    got=$?
+    local verdict
+    if [ "$3" = "block" ]; then
+        [ "$got" = "2" ] && verdict="OK " || { verdict="NG★"; ng=$((ng+1)); }
+    else
+        [ "$got" = "2" ] && { verdict="NG★"; ng=$((ng+1)); } || verdict="OK "
+    fi
+    printf '%-4s exit %-2s 期待=%-6s %s\n' "$verdict" "$got" "$3" "$1"
+}
+
+echo "門＝scope-guard.sh / 4つの分岐すべてを撃つ"
+echo
+probe "分岐1 絶対パス"                       "$DEL /var/tmp/thing"                    block
+probe "分岐2 家の下"                         "$DEL ~/Projects/thing"                  block
+probe "分岐3 親への脱出"                     "$DEL ../sibling/thing"                  block
+probe "分岐4 Desktop"                        "$DEL Desktop/notes"                     block
+probe "分岐4 .ssh"                           "$DEL .ssh/known_hosts"                  block
+probe "分岐4 大文字小文字ちがい"             "$DEL desktop/notes"                     block
+echo
+echo "--- 止めてはいけない側（この門の役目は、プロジェクトの外を守ること） ---"
+probe "プロジェクトの中の相対パス"           "$DEL ./build"                           pass
+probe "本文に分岐4の語が在るだけ"            "cat > /tmp/n.md <<'EOF'
+Never let the agent run $DEL Desktop by itself.
+EOF"                                                                                  pass
+probe "伝言に分岐4の語が在るだけ"            "git commit -m \"guard $DEL .ssh\""       pass
+echo
+echo "不合格 $ng 件"
+exit $([ "$ng" -gt 0 ] && echo 1 || echo 0)

package/scripts/probe-skip-line-both-ways.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# probe-skip-line-both-ways.sh — scope-guard.sh の「文字列を出すコマンドは素通し」の行が、
+# 誤爆（本文の語で止まる）だけでなく、逆向き（本物を見逃す）にも壊れていないかを撃つ。
+#
+# その行＝`if echo "$CMD" | grep -qE '^\s*(echo|printf|cat\s*<<)'; then exit 0; fi`
+# コマンド**全体の先頭**しか見ていないので、先頭が echo なら、後ろに何が続いても素通しになるはず。
+# 誤って安心させる側の欠陥は、誤爆より高くつく（読者は守られていると思い込む）。
+set -u
+REPO="$(cd "$(dirname "$0")/.." && pwd)"
+HOOK="$REPO/examples/scope-guard.sh"
+S="$(mktemp -d)"
+trap 'chmod -R u+w "$S" 2>/dev/null; find "$S" -mindepth 1 -delete 2>/dev/null; rmdir "$S" 2>/dev/null' EXIT
+mkdir -p "$S/home/.claude" "$S/work"
+
+DEL='rm -rf'          # 組み立てて渡す（この検査を測る側の門に、この語で止められないため）
+TARGET='/home/someone/project'
+
+probe() {  # $1 = 説明, $2 = コマンド文字列, $3 = 期待（block か pass）
+  local got
+  jq -cn --arg c "$2" '{hook_event_name:"PreToolUse",tool_name:"Bash",tool_input:{command:$c},cwd:"'"$S/work"'"}' \
+    | timeout 5 env HOME="$S/home" bash "$HOOK" >/dev/null 2>&1
+  got=$?
+  local verdict
+  if [ "$3" = "block" ]; then
+    [ "$got" = "2" ] && verdict="OK " || verdict="NG★ 見逃し"
+  else
+    [ "$got" = "2" ] && verdict="NG★ 誤爆" || verdict="OK "
+  fi
+  printf '%-4s exit %-2s 期待=%-6s %s\n' "$verdict" "$got" "$3" "$1"
+}
+
+echo "門＝scope-guard.sh / 40行目の『文字列を出すコマンドは素通し』の行を両方向から撃つ"
+echo
+
+probe "素の削除（対照＝止まるべき）"                  "$DEL $TARGET"                      block
+probe "先頭が echo で、そのあとに削除が続く"          "echo starting && $DEL $TARGET"     block
+probe "先頭が printf で、そのあとに削除が続く"        "printf ok; $DEL $TARGET"           block
+probe "先頭が echo、削除の対象は家の下"               "echo hi; $DEL ~/important"         block
+probe "ヒアドキュメントの後ろに、本物の削除が続く"    "cat <<EOF > /tmp/x
+hi
+EOF
+$DEL $TARGET"                                                                              block
+probe "本文に語が在るだけ（cat のリダイレクトが先）"  "cat > /tmp/note.md <<'EOF'
+The guard fires when the agent runs $DEL $TARGET by itself.
+EOF"                                                                                       pass
+probe "本文に語が在るだけ（コミットの伝言）"          "git commit -m \"guard against $DEL $TARGET\"" pass
+
+echo
+echo "--- 直しが新しい穴を開けていないか（本体が実行される側のヒアドキュメント） ---"
+probe "bash のヒアドキュメント＝本体は実行される"     "bash <<'EOF'
+$DEL $TARGET
+EOF"                                                                                       block
+probe "sh のヒアドキュメント＝本体は実行される"       "sh <<'EOF'
+$DEL $TARGET
+EOF"                                                                                       block
+probe "python のヒアドキュメント＝安全側に倒す"       "python3 - <<'PY'
+import os; os.system('$DEL $TARGET')
+PY"                                                                                        block
+probe "パイプの先が bash＝本体は実行される"           "cat script.sh | bash <<'EOF'
+$DEL $TARGET
+EOF"                                                                                       block
+probe "コミットの伝言のあとに、本物の削除が続く"      "git commit -m \"note\" && $DEL $TARGET" block
+probe "tee で保存＝本体はデータ"                      "tee /tmp/note.md <<'EOF'
+The guard fires when the agent runs $DEL $TARGET by itself.
+EOF"                                                                                       pass

package/scripts/receipts-aggregate.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""receipts-aggregate — aggregate ~/.claude/receipts/*.jsonl into a denormalized table.
+
+Schema source: yurukusa schema-v2 sketch at
+  https://github.com/anthropics/claude-code/issues/61102#issuecomment-4514215413
+which proposes one-row-per-receipt denormalized columns wide enough to host all
+five boundary types' fields, sparse where a given boundary doesn't have a column.
+
+Consumed receipt sources:
+  - examples/scope-expansion-receipt.sh (PR #282, destructive-bash boundary)
+  - examples/dispatch-receipt.sh        (PR #283, agent-dispatch boundary)
+  - examples/dispatch-allowlist-preflight.sh (PR #286)
+  - examples/articulated-scope-capture.sh    (this PR, UserPromptSubmit companion)
+  - any future sibling boundary-type hook that writes ~/.claude/receipts/*.jsonl
+
+Output: CSV to stdout by default; --format json available.
+
+Filter: --boundary <type> restricts output to one boundary class.
+
+The aggregated table is the operator-side measurement substrate for §6.2 of
+ianymu/recognition-without-arrest — the empirical Mode 2.6 + Mode 3.3 question
+answerable from receipt corpora rather than from LLM-judge labels:
+
+    effective_arrest_rate = gate_installation_rate × gate_recall
+
+where gate_installation_rate is read from the receipt corpus directly, joined
+across boundary types on session_id + articulated_scope_hash.
+
+Stdlib-only per PR #280 precedent (no eval, no network, no pandas/polars dep);
+Python 3.10+. Output JSON/CSV is downstream-consumable by pandas, polars, jq,
+or duckdb without this script reaching beyond stdlib.
+
+Example usage:
+
+    # Aggregate all receipts, CSV to stdout
+    receipts-aggregate.py
+
+    # Filter to one boundary class, JSON output
+    receipts-aggregate.py --boundary destructive_bash --format json
+
+    # Explicit paths
+    receipts-aggregate.py ~/.claude/receipts/*.jsonl
+"""
+
+import argparse
+import csv
+import json
+import sys
+from pathlib import Path
+from typing import Iterator
+
+# Denormalized columns per yurukusa schema sketch.
+# Wide row, sparse columns: a given boundary type populates only the relevant
+# fields. Sparse data is empty string in CSV / null in JSON.
+COLUMNS = [
+    "ts",
+    "boundary_type",
+    "session_id",
+    "subagent_type",
+    "prompt_hash",
+    "prompt_length",
+    "articulated_scope_hash",
+    "articulated_scope_length",
+    "paths",
+    "scope_match",
+    "allowlist_match",
+    "mcp_tools_referenced",
+    "parent_covered_count",
+    "decision",
+    "additional_fields",
+]
+
+BOUNDARY_CHOICES = (
+    "destructive_bash",
+    "dispatch_start",
+    "dispatch_end",
+    "user_prompt_submit",
+    "post_tool_use_disk",
+    "all",
+)
+
+
+def iter_receipts(paths: list[Path]) -> Iterator[dict]:
+    """Yield one parsed receipt dict per JSONL line across all input files.
+
+    Malformed lines produce a warning to stderr and are skipped; valid lines
+    in the same file continue to be processed.
+    """
+    for path in paths:
+        try:
+            with path.open("r", encoding="utf-8") as f:
+                for line_no, raw in enumerate(f, start=1):
+                    raw = raw.strip()
+                    if not raw:
+                        continue
+                    try:
+                        yield json.loads(raw)
+                    except json.JSONDecodeError as e:
+                        print(
+                            f"warning: {path}:{line_no}: invalid JSON skipped ({e})",
+                            file=sys.stderr,
+                        )
+        except OSError as e:
+            print(f"warning: cannot read {path}: {e}", file=sys.stderr)
+
+
+def normalize(receipt: dict) -> dict:
+    """Project a parsed receipt to the denormalized COLUMNS schema.
+
+    Known fields land in their named column. Unknown fields land in
+    `additional_fields` as a JSON-encoded sub-object so no source data is
+    dropped — this preserves forward compatibility with future receipt
+    fields (e.g. schema v3) without requiring a code change here.
+    """
+    row = {}
+    extras = {}
+    for k, v in receipt.items():
+        if k in COLUMNS and k != "additional_fields":
+            # Coerce nested objects/lists to JSON string for CSV-safety
+            if isinstance(v, (dict, list)):
+                row[k] = json.dumps(v, sort_keys=True)
+            else:
+                row[k] = v
+        else:
+            extras[k] = v
+    for col in COLUMNS:
+        if col not in row and col != "additional_fields":
+            row[col] = ""
+    row["additional_fields"] = json.dumps(extras, sort_keys=True) if extras else ""
+    return row
+
+
+def emit_csv(rows: Iterator[dict]) -> None:
+    writer = csv.DictWriter(sys.stdout, fieldnames=COLUMNS)
+    writer.writeheader()
+    for row in rows:
+        writer.writerow(row)
+
+
+def emit_json(rows: Iterator[dict]) -> None:
+    json.dump(list(rows), sys.stdout, indent=2, sort_keys=True)
+    sys.stdout.write("\n")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Aggregate ~/.claude/receipts/*.jsonl into a denormalized table.",
+        epilog=(
+            "Schema source: yurukusa #61102#issuecomment-4514215413. "
+            "Output is downstream-consumable by pandas, polars, jq, or duckdb."
+        ),
+    )
+    parser.add_argument(
+        "paths",
+        nargs="*",
+        help="JSONL receipt files (default: ~/.claude/receipts/*.jsonl)",
+    )
+    parser.add_argument(
+        "--format",
+        choices=("csv", "json"),
+        default="csv",
+        help="output format (default: csv)",
+    )
+    parser.add_argument(
+        "--boundary",
+        choices=BOUNDARY_CHOICES,
+        default="all",
+        help="filter to a single boundary type (default: all)",
+    )
+    args = parser.parse_args(argv)
+
+    if args.paths:
+        paths = [Path(p) for p in args.paths]
+    else:
+        default = Path.home() / ".claude" / "receipts"
+        paths = sorted(default.glob("*.jsonl"))
+        if not paths:
+            print(
+                f"warning: no JSONL files in {default}",
+                file=sys.stderr,
+            )
+            return 0
+
+    receipts = iter_receipts(paths)
+    normalized = (normalize(r) for r in receipts)
+
+    if args.boundary != "all":
+        normalized = (r for r in normalized if r.get("boundary_type") == args.boundary)
+
+    if args.format == "csv":
+        emit_csv(normalized)
+    else:
+        emit_json(normalized)
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())