claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/core/hooks/CHAIN-SEMANTICS.md

@@ -0,0 +1,84 @@
+# Hook chain execution semantics
+
+**Question.** When multiple hooks share a matcher inside `.claude/settings.json`, does Claude Code run them sequentially (in list order, with `exit 2` in one suppressing peers) or in parallel (all three spawn at once, `exit 2` in one does NOT stop the others)?
+
+This is load-bearing for every enforcement hook we ship — if we assume sequential but Claude Code runs parallel, hooks like `dev-required-on-commit` can't count on `doc-check-on-commit`'s exit code having already been observed.
+
+## 1 · Authoritative answer
+
+[Anthropic's hook reference](https://code.claude.com/docs/en/hooks) is explicit:
+
+> When multiple hooks match the same event, they all run in parallel.
+
+This is reproduced on `docs.anthropic.com/en/docs/claude-code/hooks` (same content, different origin). There is no "sequence" mode and no ordering guarantee beyond "all of them will fire".
+
+Practical consequence: `exit 2` from one hook does **not** preempt its peers. Every hook registered under a matcher runs to completion (or times out). The runtime aggregates their verdicts — any single deny wins, but all of them still executed side-effects.
+
+## 2 · Local simulation of both modes
+
+`run-experiment.sh` in this directory runs the three test hooks `h1` / `h2` / `h3` in both sequential and parallel modes and records a shared log. It isn't real Claude Code, but it demonstrates the mechanics of each mode clearly and verifies the test hooks work.
+
+### Sequential mode (what the settings.json list LOOKS like it does)
+
+```
+06:52:11.958 h1 start
+06:52:12.327 h1 exit=2
+06:52:12.376 h2 start        ← h2 only started after h1 finished
+06:52:12.924 h2 exit=0
+06:52:12.972 h3 start
+06:52:13.740 h3 exit=0
+```
+
+Total wall-clock: ~1.8s. Each hook's full duration is serialized.
+
+### Parallel mode (what Anthropic docs say Claude Code actually does)
+
+```
+06:52:13.815 h1 start        ← same millisecond
+06:52:13.815 h2 start        ← same millisecond
+06:52:13.815 h3 start        ← same millisecond
+06:52:14.161 h1 exit=2
+06:52:14.366 h2 exit=0
+06:52:14.583 h3 exit=0       ← h3 ran to completion despite h1 exit=2
+```
+
+Total wall-clock: ~0.77s (time of the slowest hook). All three start simultaneously; h1's `exit 2` does not suppress h2 or h3; the `h3-ran` marker file exists afterwards.
+
+## 3 · Verifying inside real Claude Code
+
+The local simulation only checks that hooks work in isolation. To confirm Claude Code's actual scheduler:
+
+1. Create a throwaway project directory.
+2. Copy `settings-experiment.json` into it as `.claude/settings.json` (substituting `${CLAUDE_PROJECT_DIR}` with the absolute path to the superkit clone).
+3. Open that directory in Claude Code and run any `Bash` tool call (`ls`, `pwd`, anything).
+4. Inspect:
+   - `${TMPDIR:-/tmp}/claude-chain-test.log` — the timestamps show whether hooks started within the same millisecond (parallel) or serially.
+   - `${TMPDIR:-/tmp}/claude-chain-test-h3-ran` — presence confirms h3 ran even though h1 exited 2.
+5. Record findings in this file under §5.
+
+## 4 · Architectural consequence (applies regardless of runtime version)
+
+Because Anthropic can change the runtime at any time and our local simulation can only show "parallel is possible, not mandatory", every hook we ship **MUST** behave correctly under BOTH semantics. The design contract:
+
+1. **Hooks are idempotent.** Running the same hook twice with the same payload yields the same decision and the same side-effects. No hook leaves a dangling lock, half-written state file, or incrementable counter that depends on not being called twice.
+2. **Decisions are independent.** A hook's verdict is computed from the payload plus the `${TMPDIR}`-backed state files — NOT from "what an earlier hook in the chain decided". `dev-required-on-commit.sh` reads the counter file that `dev-edit-counter.sh` wrote; it does not assume `doc-check-on-commit.sh` has already decided anything.
+3. **State writes are atomic.** `> file` and `>> file` are both atomic at the shell level. Hooks that need multi-step updates use `mv` after writing to a `.tmp` sibling.
+4. **settings.json order is cosmetic.** We still keep `block-dangerous-git → doc-check-on-commit → dev-required-on-commit → loop-guard` as a list for human readability, but no hook's logic depends on running before or after another hook.
+5. **Timeouts are explicit.** Every hook that does real I/O has `timeout: 60` in settings.json (or the shell-level `timeout 55` inside the script) so a misbehaving peer can't starve the whole chain.
+
+## 5 · Empirical findings (to fill in on the next real-runtime test)
+
+| Field | Value |
+|-------|-------|
+| Date tested | *(TBD)* |
+| Claude Code version | *(TBD, read from `/help` or `claude --version`)* |
+| OS | *(TBD)* |
+| Concurrency observed | *(parallel / sequential / other)* |
+| h3 marker present after h1 exit 2 | *(yes / no)* |
+| Notes | *(TBD)* |
+
+## 6 · References
+
+- Anthropic official hooks reference: `code.claude.com/docs/en/hooks`
+- `disler/claude-code-hooks-multi-agent-observability` — similar in-the-wild observations on concurrency
+- The test scaffolding files next to this document: `h1.sh`, `h2.sh`, `h3.sh`, `run-experiment.sh`, `settings-experiment.json`

package/packages/core/hooks/audit-settings-source.sh

@@ -0,0 +1,98 @@
+#!/bin/bash
+# audit-settings-source.sh — CVE-2025-59536 mitigation.
+# Triggers on: SessionStart
+# Profile: standard, strict (skipped on fast for startup speed)
+#
+# A malicious `.claude/settings.json` committed to an untrusted repo can
+# register a PreToolUse hook that runs arbitrary code on every tool call,
+# effectively an RCE on session open. Reference:
+#   research.checkpoint.com/2026/rce-and-api-token-exfiltration-through-
+#     claude-code-project-files-cve-2025-59536/
+#
+# This hook inspects .claude/settings.json in the current project:
+# - If the file exists AND was last touched by an author who is NOT the
+#   current git user OR was modified by ANY author in the last 7 days
+#   (likely a recent pull from an untrusted branch), print a loud warning
+#   to stderr AND touch ${TMPDIR:-/tmp}/claude-untrusted-settings-${SESSION}
+#   so downstream hooks can downgrade decisions.
+# - Fails open (exit 0) in every path — this is a warning, not a block.
+# Opt-out: CLAUDE_DISABLE_SETTINGS_AUDIT=1
+
+# Unified profile + disable check
+SUPERKIT_PROFILE_LIB="$(dirname "$0")/lib/profile.sh"
+[ -f "$SUPERKIT_PROFILE_LIB" ] || SUPERKIT_PROFILE_LIB="$(dirname "$0")/../lib/profile.sh"
+# shellcheck source=/dev/null
+[ -f "$SUPERKIT_PROFILE_LIB" ] && source "$SUPERKIT_PROFILE_LIB" && should_skip_hook "$(basename "$0" .sh)" && exit 0
+
+PROFILE="${CLAUDE_HOOK_PROFILE:-standard}"
+if [ "$PROFILE" = "fast" ] || [ "${CLAUDE_DISABLE_SETTINGS_AUDIT:-}" = "1" ]; then
+  exit 0
+fi
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+SETTINGS="$PROJECT_DIR/.claude/settings.json"
+
+# Only run inside a git repo with a settings.json to audit
+if [ ! -f "$SETTINGS" ] || ! git -C "$PROJECT_DIR" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Identify current git user (trusted author)
+MY_EMAIL=$(git -C "$PROJECT_DIR" config user.email 2>/dev/null)
+if [ -z "$MY_EMAIL" ]; then
+  # If we can't identify the user we can't classify foreignness — skip.
+  exit 0
+fi
+
+# Look at the last 10 commits touching .claude/settings.json
+LAST_COMMITS=$(git -C "$PROJECT_DIR" log --format='%H|%ae|%ct' -n 10 -- .claude/settings.json 2>/dev/null)
+if [ -z "$LAST_COMMITS" ]; then
+  # File exists but untracked — treat as trusted (user placed it manually).
+  exit 0
+fi
+
+NOW=$(date +%s)
+SEVEN_DAYS=$((7 * 24 * 3600))
+FOREIGN_RECENT=""
+while IFS='|' read -r sha email ts; do
+  [ -z "$sha" ] && continue
+  AGE=$((NOW - ts))
+  if [ "$email" != "$MY_EMAIL" ] && [ "$AGE" -lt "$SEVEN_DAYS" ]; then
+    FOREIGN_RECENT="${FOREIGN_RECENT}    - ${sha:0:8} by ${email} ($((AGE / 86400))d ago)\n"
+  fi
+done <<< "$LAST_COMMITS"
+
+if [ -z "$FOREIGN_RECENT" ]; then
+  exit 0
+fi
+
+# Touch marker so downstream hooks can consult it
+INPUT=$(cat 2>/dev/null || echo '')
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+SESSION_KEY="${SESSION_ID:-${CLAUDE_HOOK_PID:-$PPID}}"
+MARKER="${TMPDIR:-/tmp}/claude-untrusted-settings-${SESSION_KEY}"
+touch "$MARKER"
+
+cat >&2 <<EOF
+
+────────────────────────────────────────────────────────────────────
+⚠ SECURITY WARNING — .claude/settings.json was modified recently by
+  someone other than you. This file controls what hooks run on every
+  tool call. A malicious settings.json in an untrusted repo can
+  execute arbitrary code (CVE-2025-59536).
+
+  Recent foreign commits touching .claude/settings.json:
+$(echo -e "$FOREIGN_RECENT")
+  Actions:
+    1. Review the diff: git log -p .claude/settings.json
+    2. If anything looks off, open Claude Code with --no-hooks until
+       you've vetted the file.
+    3. To silence this warning: CLAUDE_DISABLE_SETTINGS_AUDIT=1
+
+  Reference: https://research.checkpoint.com/2026/
+    rce-and-api-token-exfiltration-through-claude-code-project-files-
+    cve-2025-59536/
+────────────────────────────────────────────────────────────────────
+
+EOF
+exit 0

package/packages/core/hooks/audit-trail.sh

@@ -0,0 +1,120 @@
+#!/bin/bash
+# audit-trail.sh — append-only hash-chained audit log (Task 10).
+# Triggers on: PostToolUse (Bash, Edit, Write, Skill). Profile: standard, strict.
+#
+# Writes one JSON line per tool call to ~/.claude/audit/YYYY-MM-DD.jsonl.
+# Each line contains:
+#   ts          — ISO 8601 UTC timestamp
+#   session_id  — Claude Code session_id from payload (falls back to PPID)
+#   project     — basename of $CLAUDE_PROJECT_DIR
+#   event       — tool name (Bash|Edit|Write|Skill|…) or semantic tag
+#   tool        — raw tool name
+#   decision    — "allow" (exit-0 peer consensus assumed) or "error" on parse fail
+#   tag         — override tag extracted from a git-commit command, if any
+#   files       — comma-joined staged/edited file list (short)
+#   counter     — current /dev edit counter value (reads the state file)
+#   marker_exists — whether /dev marker is present (true/false)
+#   prev_hash   — previous line's hash (genesis = 64 zeros)
+#   hash        — sha256(prev_hash || canonical_json_of_this_line_without_hash)
+#
+# The log is append-only. `/audit --verify-chain` recomputes the chain
+# and reports the first divergence. `/audit --discipline` aggregates.
+# Rotation: session-context-restore.sh moves logs older than 30 days to
+# ~/.claude/audit/archive/.
+#
+# Opt-out: CLAUDE_DISABLE_AUDIT_TRAIL=1.
+
+# Unified profile + disable check
+SUPERKIT_PROFILE_LIB="$(dirname "$0")/lib/profile.sh"
+[ -f "$SUPERKIT_PROFILE_LIB" ] || SUPERKIT_PROFILE_LIB="$(dirname "$0")/../lib/profile.sh"
+# shellcheck source=/dev/null
+[ -f "$SUPERKIT_PROFILE_LIB" ] && source "$SUPERKIT_PROFILE_LIB" && should_skip_hook "$(basename "$0" .sh)" && exit 0
+
+PROFILE="${CLAUDE_HOOK_PROFILE:-standard}"
+if [ "$PROFILE" = "fast" ] || [ "${CLAUDE_DISABLE_AUDIT_TRAIL:-}" = "1" ]; then
+  exit 0
+fi
+
+INPUT=$(cat 2>/dev/null || echo '{}')
+
+# ── Parse payload ────────────────────────────────────────────────────────
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // "Unknown"' 2>/dev/null)
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+SESSION_KEY=$(command -v superkit_session_key >/dev/null 2>&1 && superkit_session_key || printf '%s' "${SESSION_ID:-${CLAUDE_HOOK_PID:-$PPID}}")
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // "PostToolUse"' 2>/dev/null)
+
+# Tool-specific snippet
+FIELD=""
+case "$TOOL" in
+  Bash)
+    CMD=$(echo "$INPUT" | jq -r '.tool_input.command // .command // empty' 2>/dev/null)
+    # Keep first 120 chars for the log
+    FIELD=$(printf '%s' "$CMD" | head -c 120 | tr '\n' ' ')
+    ;;
+  Edit|Write|MultiEdit)
+    FIELD=$(echo "$INPUT" | jq -r '.tool_input.file_path // .file_path // empty' 2>/dev/null)
+    ;;
+  Skill)
+    FIELD=$(echo "$INPUT" | jq -r '.tool_input.skill // empty' 2>/dev/null)
+    ;;
+esac
+
+# Override tag if the command is a git commit
+TAG=""
+if [ "$TOOL" = "Bash" ]; then
+  TAG=$(printf '%s' "$CMD" | grep -oiE '\[(quick|no-dev|trivial|hotfix|wip)(:[^]]*)?\]' | head -1)
+fi
+
+# Counter + marker state
+COUNTER_FILE="${TMPDIR:-/tmp}/claude-edit-count-${SESSION_KEY}"
+MARKER_FILE="${TMPDIR:-/tmp}/claude-dev-marker-${SESSION_KEY}"
+COUNTER=$(cat "$COUNTER_FILE" 2>/dev/null || echo 0)
+[ -f "$MARKER_FILE" ] && MARKER="true" || MARKER="false"
+
+PROJECT=$(basename "${CLAUDE_PROJECT_DIR:-$(pwd)}")
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# ── Prepare log directory + chain state ──────────────────────────────────
+AUDIT_DIR="$HOME/.claude/audit"
+LAST_HASH_FILE="$AUDIT_DIR/.last-hash-${SESSION_KEY}"
+mkdir -p "$AUDIT_DIR" 2>/dev/null
+
+PREV_HASH=$(cat "$LAST_HASH_FILE" 2>/dev/null)
+if [ -z "$PREV_HASH" ] || [ ${#PREV_HASH} -ne 64 ]; then
+  PREV_HASH=$(printf '%064d' 0)   # genesis = 64 zeros
+fi
+
+# ── Emit canonical JSON (without hash) and compute hash over it ──────────
+# `jq -c` produces deterministic compact output given ordered keys.
+PAYLOAD=$(jq -cn \
+  --arg ts       "$TS" \
+  --arg sid      "$SESSION_KEY" \
+  --arg project  "$PROJECT" \
+  --arg event    "$EVENT" \
+  --arg tool     "$TOOL" \
+  --arg field    "$FIELD" \
+  --arg tag      "$TAG" \
+  --arg counter  "$COUNTER" \
+  --arg marker   "$MARKER" \
+  --arg prev     "$PREV_HASH" \
+  '{ts:$ts,session_id:$sid,project:$project,event:$event,tool:$tool,field:$field,tag:$tag,counter:($counter|tonumber),marker_exists:($marker=="true"),prev_hash:$prev}' \
+  2>/dev/null)
+
+if [ -z "$PAYLOAD" ]; then
+  exit 0  # jq failure — skip logging rather than corrupt the chain
+fi
+
+HASH=$(printf '%s' "$PAYLOAD" | shasum -a 256 | cut -d' ' -f1)
+
+# ── Append line + update last-hash atomically ────────────────────────────
+LINE=$(printf '%s' "$PAYLOAD" | jq -c --arg h "$HASH" '. + {hash:$h}')
+LOG_FILE="$AUDIT_DIR/$(date -u +%Y-%m-%d).jsonl"
+
+# Append is atomic for < PIPE_BUF-byte writes; our lines are always small.
+printf '%s\n' "$LINE" >> "$LOG_FILE"
+
+# Update last-hash via mv-rename for atomicity
+TMP_HASH="$AUDIT_DIR/.last-hash-${SESSION_KEY}.$$"
+printf '%s' "$HASH" > "$TMP_HASH" && mv -f "$TMP_HASH" "$LAST_HASH_FILE"
+
+exit 0

package/packages/core/hooks/block-dangerous-git.sh

@@ -0,0 +1,189 @@
+#!/bin/bash
+# block-dangerous-git.sh — PreToolUse hook for Bash
+# Blocks dangerous git commands: --no-verify, --force, reset --hard, branch -D
+
+# Unified profile + disable check
+SUPERKIT_PROFILE_LIB="$(dirname "$0")/lib/profile.sh"
+[ -f "$SUPERKIT_PROFILE_LIB" ] || SUPERKIT_PROFILE_LIB="$(dirname "$0")/../lib/profile.sh"
+# shellcheck source=/dev/null
+[ -f "$SUPERKIT_PROFILE_LIB" ] && source "$SUPERKIT_PROFILE_LIB" && should_skip_hook "$(basename "$0" .sh)" && exit 0
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+
+if [ -z "$COMMAND" ]; then
+  exit 0
+fi
+
+# ── Strip commit-MESSAGE payloads before scanning ────────────────────────────
+# A commit message that merely *describes* --no-verify / a force push must not
+# trip the guards below (this fired twice in prod while writing commit messages
+# that document these very rules). We remove the -m / --message arguments and
+# the body of a `git commit -F -` heredoc, then run every existing regex on the
+# REMAINDER unchanged — so chained segments (&&, ;, |) OUTSIDE the message are
+# still scanned: `git commit -m "x" && git push --force` must still block.
+# Safety bias: when a strip is uncertain we remove too LITTLE (a false block is
+# annoying but safe) rather than too much (which could hide a real command).
+SCAN_COMMAND="$COMMAND"
+
+# (a/b) Strip -m / --message arguments. Quoted forms are removed FIRST, so a
+#       spurious << or && that lives INSIDE a message is gone before it can
+#       matter; unquoted single-token forms are removed last (they stop at the
+#       first whitespace or shell metacharacter ; & | < > ( ) so a glued
+#       `-m foo;git push --force` keeps the `;git push` for scanning). The
+#       attached unquoted `-mfoo` form is left alone deliberately (rare; erring
+#       toward strip-less — worst case is a harmless false block).
+SCAN_COMMAND=$(printf '%s' "$SCAN_COMMAND" | sed -E \
+  -e 's/--message="[^"]*"//g' \
+  -e "s/--message='[^']*'//g" \
+  -e 's/--message[[:space:]]+"[^"]*"//g' \
+  -e "s/--message[[:space:]]+'[^']*'//g" \
+  -e 's/(^|[[:space:]])-m"[^"]*"/\1/g' \
+  -e "s/(^|[[:space:]])-m'[^']*'/\1/g" \
+  -e 's/(^|[[:space:]])-m[[:space:]]+"[^"]*"/\1/g' \
+  -e "s/(^|[[:space:]])-m[[:space:]]+'[^']*'/\1/g" \
+  -e 's/--message=[^[:space:];&|<>()]*//g' \
+  -e 's/--message[[:space:]]+[^[:space:];&|<>()]*//g' \
+  -e 's/(^|[[:space:]])-m[[:space:]]+[^[:space:];&|<>()]*/\1/g')
+
+# (c) Strip a `git commit ... <<MARKER ... MARKER` heredoc BODY (message fed via
+#     -F -). Runs AFTER the -m strip so that a << appearing only inside an -m
+#     message has already been removed and cannot trigger a false heredoc. Only
+#     the body lines are dropped — the opener line and anything after the
+#     terminator are kept and scanned, so a chained dangerous command survives.
+SCAN_COMMAND=$(printf '%s' "$SCAN_COMMAND" | awk '
+BEGIN { in_h = 0; marker = ""; dash = 0 }
+function get_marker(line,   rest) {
+  if (match(line, /<<-?/)) {
+    rest = substr(line, RSTART + RLENGTH)
+    if (match(rest, /[A-Za-z_][A-Za-z0-9_]*/))
+      return substr(rest, RSTART, RLENGTH)
+  }
+  return ""
+}
+{
+  if (in_h) {
+    t = $0
+    if (dash) sub(/^\t+/, "", t)
+    if (t == marker) { in_h = 0; print; next }
+    next
+  }
+  if ($0 ~ /git[[:space:]]+commit/) {
+    m = get_marker($0)
+    if (m != "") { in_h = 1; marker = m; dash = ($0 ~ /<<-/); print; next }
+  }
+  print
+}')
+
+if echo "$SCAN_COMMAND" | grep -qE '\-\-no-verify'; then
+  cat >&2 <<'EOF'
+BLOCKED: --no-verify is not allowed.
+  Why: pre-commit hooks exist to catch regressions before they land.
+  Suggested alternative:
+    1) Run the failing hook manually, read its output, fix the issue.
+    2) If the hook itself is wrong, amend the hook config with a
+       documented reason rather than silencing it at every commit.
+EOF
+  exit 2
+fi
+
+if { echo "$SCAN_COMMAND" | grep -qE 'git[[:space:]]+push' \
+     && echo "$SCAN_COMMAND" | grep -qE '(^|[[:space:]])(--force([[:space:]=]|$)|-f([[:space:]]|$))'; } \
+   || echo "$SCAN_COMMAND" | grep -qE 'git[[:space:]]+push[[:space:]]+[^[:space:]]+[[:space:]]+\+'; then
+  cat >&2 <<'EOF'
+BLOCKED: Force push is not allowed.
+  Why: overwrites remote history; collaborators' clones break silently.
+       +refspec pushes (git push origin +main) force non-fast-forward too.
+  Suggested alternative:
+    git push --force-with-lease          # safe — refuses if remote moved
+    git push --force-with-lease=<branch>  # even safer — scopes to your ref
+EOF
+  exit 2
+fi
+
+if echo "$SCAN_COMMAND" | grep -qE 'git\s+reset\s+--hard'; then
+  cat >&2 <<'EOF'
+BLOCKED: git reset --hard can destroy work.
+  Why: drops uncommitted changes AND moves HEAD — double hit.
+  Suggested alternative:
+    git stash push -u -m 'before-reset'   # preserve WIP first
+    git reset --soft <ref>                # keep staged + WC
+    git reset --mixed <ref>               # keep WC only
+    git restore --source=<ref> <path>     # narrow, per-file restore
+EOF
+  exit 2
+fi
+
+if echo "$SCAN_COMMAND" | grep -qE 'git\s+branch\s+-D'; then
+  cat >&2 <<'EOF'
+BLOCKED: git branch -D force-deletes.
+  Why: drops a branch even if its commits are unmerged / unpushed.
+  Suggested alternative:
+    git branch -d <name>                  # safe — refuses if unmerged
+    git push origin --delete <name>       # delete remote counterpart
+    git reflog show <name>                # recover if you just -D'd one
+EOF
+  exit 2
+fi
+
+if echo "$SCAN_COMMAND" | grep -qE 'git[[:space:]]+checkout[[:space:]]+(\.([[:space:]]|$)|--([[:space:]]|$)|-f([[:space:]]|$)|--force([[:space:]]|$))'; then
+  cat >&2 <<'EOF'
+BLOCKED: git checkout discards uncommitted changes.
+  Why: checkout of '.', '--', '-f', or '--force' overwrites working-tree
+       edits with no undo — the uncommitted work is gone for good.
+  Suggested alternative:
+    git stash push -u -m before-discard   # preserve WIP first
+    git restore --source=<ref> <path>     # narrow, per-file restore
+EOF
+  exit 2
+fi
+
+if echo "$SCAN_COMMAND" | grep -qE 'git[[:space:]]+clean[[:space:]]+-[A-Za-z]*f|git[[:space:]]+clean[[:space:]]+.*--force'; then
+  cat >&2 <<'EOF'
+BLOCKED: git clean -f permanently deletes untracked files.
+  Why: removes untracked files/dirs outright — git cannot recover them.
+  Suggested alternative:
+    git clean -n                          # dry run — list what WOULD be removed
+    git stash push -u                     # stash untracked instead of deleting
+EOF
+  exit 2
+fi
+
+if echo "$SCAN_COMMAND" | grep -qE 'git[[:space:]]+switch[[:space:]]+.*(--discard-changes|--force([[:space:]]|$)|-[A-Za-z]*f([[:space:]]|$)|-C([[:space:]]|$))'; then
+  cat >&2 <<'EOF'
+BLOCKED: git switch --discard-changes / -C throws away work.
+  Why: forces the switch and drops uncommitted changes with no undo.
+  Suggested alternative:
+    git stash push -u -m before-switch    # preserve WIP first
+    git switch <branch>                   # plain switch keeps your changes
+EOF
+  exit 2
+fi
+
+# ── Task 18: stash-commit bypass patterns ─────────────────────────────────
+# Real incident from github.com/anthropics/claude-code/issues/40117 — a
+# stash+commit+stash-pop sequence can slip staged changes past hook
+# scrutiny. Also catch -q/--quiet combined with --no-verify and
+# --amend --no-verify which target pre-commit gate bypass.
+
+if echo "$SCAN_COMMAND" | grep -qE 'git\s+stash.*&&.*git\s+commit.*stash\s+pop'; then
+  echo "BLOCKED: stash → commit → stash pop bypass pattern detected." >&2
+  echo "  This pattern is a known way to slip staged work past commit-gate hooks." >&2
+  echo "  Commit the staged work directly, then stash/pop the remainder." >&2
+  exit 2
+fi
+
+if echo "$SCAN_COMMAND" | grep -qE 'git\s+commit.*(-q|--quiet).*--no-verify'; then
+  echo "BLOCKED: git commit -q/--quiet combined with --no-verify." >&2
+  echo "  This combination exists solely to silence the hook failure. Fix the" >&2
+  echo "  underlying pre-commit-hook error instead of muting it." >&2
+  exit 2
+fi
+
+if echo "$SCAN_COMMAND" | grep -qE 'git\s+commit.*--amend.*--no-verify'; then
+  echo "BLOCKED: git commit --amend --no-verify is a pre-commit-hook bypass." >&2
+  echo "  Fix the hook error, stage the fix, then --amend without --no-verify." >&2
+  exit 2
+fi
+
+exit 0

package/packages/core/hooks/bundle-import-check.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+# PostToolUse hook: warn when new imports reference packages not in package.json
+# Profile: skip on fast, run on standard/strict
+
+# Unified profile + disable check
+SUPERKIT_PROFILE_LIB="$(dirname "$0")/lib/profile.sh"
+[ -f "$SUPERKIT_PROFILE_LIB" ] || SUPERKIT_PROFILE_LIB="$(dirname "$0")/../lib/profile.sh"
+# shellcheck source=/dev/null
+[ -f "$SUPERKIT_PROFILE_LIB" ] && source "$SUPERKIT_PROFILE_LIB" && should_skip_hook "$(basename "$0" .sh)" && exit 0
+
+PROFILE="${CLAUDE_HOOK_PROFILE:-standard}"
+if [ "$PROFILE" = "fast" ]; then exit 0; fi
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+# Only process TypeScript files
+if [ -z "$FILE_PATH" ] || [[ ! "$FILE_PATH" =~ \.(ts|tsx)$ ]]; then exit 0; fi
+
+# Get new content from edit or write
+NEW_STRING=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // empty')
+if [ -z "$NEW_STRING" ]; then exit 0; fi
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+# Extract package imports (skip relative imports starting with . or /)
+NEW_IMPORTS=$(echo "$NEW_STRING" | grep -oE "from ['\"]([^./][^'\"]*)['\"]" | sed "s/from ['\"]//;s/['\"]$//" | sort -u)
+if [ -z "$NEW_IMPORTS" ]; then exit 0; fi
+
+# Find nearest package.json by walking up from file path
+PKG_JSON=""
+SEARCH_DIR=$(dirname "$FILE_PATH")
+while [ "$SEARCH_DIR" != "/" ] && [ "$SEARCH_DIR" != "." ]; do
+  if [ -f "$SEARCH_DIR/package.json" ]; then
+    PKG_JSON="$SEARCH_DIR/package.json"
+    break
+  fi
+  SEARCH_DIR=$(dirname "$SEARCH_DIR")
+done
+
+if [ -z "$PKG_JSON" ] || [ ! -f "$PKG_JSON" ]; then exit 0; fi
+
+WARNINGS=""
+for IMPORT in $NEW_IMPORTS; do
+  # Extract base package name (handle scoped packages @org/pkg)
+  BASE_PKG=$(echo "$IMPORT" | sed 's|@\([^/]*\)/\([^/]*\).*|@\1/\2|; t; s|/.*||')
+
+  # Skip known built-in/virtual modules
+  case "$BASE_PKG" in
+    react|react-dom|react/jsx-runtime|vite/*) continue ;;
+  esac
+
+  if ! grep -q "\"$BASE_PKG\"" "$PKG_JSON" 2>/dev/null; then
+    WARNINGS="${WARNINGS}  - ${BASE_PKG}\n"
+  fi
+done
+
+if [ -n "$WARNINGS" ]; then
+  echo "WARNING: New dependencies not in package.json:" >&2
+  echo -e "$WARNINGS" >&2
+  echo "Consider: are these intentional? Check bundle size impact." >&2
+fi
+
+exit 0

package/packages/core/hooks/compact-state-inject.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+# compact-state-inject.sh — survive context compaction with disciplinary state
+# Triggers on: SessionStart (matcher "compact")
+# Profile: standard, strict
+#
+# After Claude Code compacts the conversation, the counter / marker /
+# override-cycle state we kept in session memory is wiped. We persist
+# the disciplinary snapshot via the audit log, then on SessionStart
+# (compact) we read back the last ~30 min of entries and inject a
+# ≤200 char summary into the fresh post-compact context so Claude
+# "remembers" its budget standing.
+#
+# Output format (Claude Code SessionStart additionalContext):
+#   {"hookSpecificOutput":{"hookEventName":"SessionStart",
+#     "additionalContext":"Session stats: …"}}
+#
+# Opt-out: CLAUDE_DISABLE_COMPACT_STATE=1
+
+# Unified profile + disable check
+SUPERKIT_PROFILE_LIB="$(dirname "$0")/lib/profile.sh"
+[ -f "$SUPERKIT_PROFILE_LIB" ] || SUPERKIT_PROFILE_LIB="$(dirname "$0")/../lib/profile.sh"
+# shellcheck source=/dev/null
+[ -f "$SUPERKIT_PROFILE_LIB" ] && source "$SUPERKIT_PROFILE_LIB" && should_skip_hook "$(basename "$0" .sh)" && exit 0
+
+PROFILE="${CLAUDE_HOOK_PROFILE:-standard}"
+if [ "$PROFILE" = "fast" ] || [ "${CLAUDE_DISABLE_COMPACT_STATE:-}" = "1" ]; then
+  exit 0
+fi
+
+INPUT=$(cat 2>/dev/null || echo '{}')
+SOURCE=$(echo "$INPUT" | jq -r '.source // .matcher // empty' 2>/dev/null)
+# Only fire after compaction — skip on fresh / resume sources
+if [ "$SOURCE" != "compact" ]; then
+  exit 0
+fi
+
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+SESSION_KEY="${SESSION_ID:-${CLAUDE_HOOK_PID:-$PPID}}"
+
+AUDIT_DIR="$HOME/.claude/audit"
+[ -d "$AUDIT_DIR" ] || exit 0
+
+# Count tagged overrides + /dev invocations in the last 60 minutes
+# (across all audit files — today + maybe yesterday at a day boundary).
+# Window widened for Opus 4.8 1M context: sessions last longer, so 60 min
+# keeps the post-compaction summary representative of the active stretch.
+cutoff=$(date -u -v-60M +%s 2>/dev/null || date -u -d '60 minutes ago' +%s 2>/dev/null || echo 0)
+
+overrides=0
+dev_invocations=0
+for f in "$AUDIT_DIR"/*.jsonl; do
+  [ -f "$f" ] || continue
+  while IFS= read -r line; do
+    sid=$(printf '%s' "$line" | jq -r '.session_id // empty' 2>/dev/null)
+    [ "$sid" != "$SESSION_KEY" ] && continue
+    ts=$(printf '%s' "$line" | jq -r '.ts // empty' 2>/dev/null)
+    [ -z "$ts" ] && continue
+    ts_epoch=$(date -u -j -f '%Y-%m-%dT%H:%M:%SZ' "$ts" +%s 2>/dev/null || \
+               date -u -d "$ts" +%s 2>/dev/null || echo 0)
+    [ "$ts_epoch" -lt "$cutoff" ] && continue
+    tag=$(printf '%s' "$line" | jq -r '.tag // empty' 2>/dev/null)
+    [ -n "$tag" ] && overrides=$((overrides + 1))
+    marker=$(printf '%s' "$line" | jq -r '.marker_exists // false' 2>/dev/null)
+    [ "$marker" = "true" ] && dev_invocations=$((dev_invocations + 1))
+  done < "$f"
+done
+
+# If nothing notable to inject, exit without emitting anything.
+if [ "$overrides" -eq 0 ] && [ "$dev_invocations" -eq 0 ]; then
+  exit 0
+fi
+
+# Build the summary. Keep under ~200 chars so it doesn't eat budget.
+if [ "$overrides" -ge 2 ]; then
+  msg="Disciplinary state after compaction: ${overrides} override tag(s) used in the last 60 min. The next override is rejected by the rolling-budget gate — please use /dev for the next code-changing commit."
+elif [ "$overrides" -eq 1 ]; then
+  msg="Disciplinary state after compaction: 1 override tag used in the last 60 min. One more within 60 min will raise strictness (threshold 3 → 2) and the one after that is blocked."
+else
+  msg="Disciplinary state after compaction: no overrides in the last 60 min, ${dev_invocations} /dev invocation(s) recorded."
+fi
+
+# Emit the SessionStart additionalContext JSON
+jq -cn --arg m "$msg" '{hookSpecificOutput:{hookEventName:"SessionStart",additionalContext:$m}}'
+exit 0