voidmachine 0.0.0 → 4.0.0

package/core-assets/enforce/ci-enforce.sh

@@ -0,0 +1,183 @@
+#!/usr/bin/env bash
+# ci-enforce — replay the void-machine enforcement floor over a PR diff.
+#
+# Critical path, secret-content, TDD and boundary rules execute through the SAME
+# portable Node bundle as local PreToolUse hooks.
+#
+# FAIL-CLOSED (DEV-393, the #62-64 class): a missing prerequisite or an
+# unresolvable base ref is an explicit RED check, never a silent green.
+#
+# Usage: ci-enforce.sh --base <ref>        # ref = the PR base, e.g. origin/main
+# Exit:  0 = clean, 1 = violations found OR fail-closed error.
+
+set -uo pipefail
+RUNNER="${BASH_SOURCE[0]%/*}/../hooks/_void-hook.mjs"
+
+BASE=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --base) BASE="${2:-}"; shift 2 ;;
+    -h | --help) printf 'Usage: ci-enforce.sh --base <ref>\n'; exit 0 ;;
+    *) printf '::error::void-enforce: unknown argument %s\n' "$1" >&2; exit 1 ;;
+  esac
+done
+
+fail_closed() {
+  printf '::error::void-enforce: %s\n' "$1"
+  printf 'void-enforce (fail-closed): %s\n' "$1" >&2
+  exit 1
+}
+
+command -v git >/dev/null 2>&1 || fail_closed "git not found on runner (cannot compute the diff)"
+NODE_BIN=$(command -v node 2>/dev/null) || fail_closed "Node.js not found on runner (cannot execute the shared floor)"
+[[ -f "$RUNNER" ]] || fail_closed "shared Node enforcement bundle missing at '$RUNNER'"
+[[ -n "$BASE" ]] || fail_closed "no base ref given (pass --base <ref>)"
+git rev-parse --verify "${BASE}^{commit}" >/dev/null 2>&1 \
+  || fail_closed "base ref '${BASE}' is unresolvable (checkout with fetch-depth: 0 and fetch the base)"
+# A three-dot diff needs a merge-base. A shallow clone or a rewritten/disjoint
+# base HAS the commit object but shares NO common ancestor: `git diff base...HEAD`
+# then exits 128 and prints nothing — indistinguishable from a clean diff, which
+# would fail OPEN. Verify the merge-base up front so this fails CLOSED instead.
+git merge-base "${BASE}" HEAD >/dev/null 2>&1 \
+  || fail_closed "no merge-base between '${BASE}' and HEAD (shallow clone or disjoint history — checkout with fetch-depth: 0)"
+
+FAIL=0
+
+# Committed, reviewable exemptions: `.github/void-enforce-allow` lists path globs
+# (one per line, # comments) skipped entirely. This is the Action equivalent of
+# the local VOID_MACHINE_ALLOW_SECRET_EDIT override — e.g. a file legitimately
+# NAMED for secrets (the harness's own secret-in-content.sh) that sensitive-path
+# would otherwise flag. A skip is LOGGED, never silent. Loaded once.
+ALLOW_GLOBS=()
+if [[ -f .github/void-enforce-allow ]]; then
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    line="${line%%#*}"       # strip trailing comment
+    read -r g <<<"$line" || true  # trim surrounding whitespace, take the glob
+    [[ -n "${g:-}" ]] && ALLOW_GLOBS+=("$g")
+  done <.github/void-enforce-allow
+fi
+_allowlisted() {
+  local p="$1" g
+  for g in "${ALLOW_GLOBS[@]:-}"; do
+    [[ -n "$g" ]] || continue
+    # shellcheck disable=SC2053 -- intentional glob match, $g is a pattern
+    [[ "$p" == $g ]] && return 0
+  done
+  return 1
+}
+
+# Escape a workflow-command MESSAGE value: % -> %25, CR/LF -> %0D/%0A.
+esc_msg() { printf '%s' "$1" | sed -e 's/%/%25/g' -e 's/\r/%0D/g' | awk 'NR>1{printf "%%0A"} {printf "%s",$0} END{print ""}'; }
+# Escape a PROPERTY value (file/title): also , -> %2C and : -> %3A.
+esc_prop() { printf '%s' "$1" | sed -e 's/%/%25/g' -e 's/:/%3A/g' -e 's/,/%2C/g'; }
+
+annotate() { # <level> <file> <line> <message>
+  printf '::%s file=%s,line=%s::%s\n' "$1" "$(esc_prop "$2")" "$3" "$(esc_msg "$4")"
+  if [[ "$1" == error ]]; then FAIL=1; fi
+}
+
+# Added lines of <file> in base...HEAD as `<new-line-number>\t<text>`, one per
+# added line, so a content match maps back to a real line for the annotation.
+# Returns 2 (not empty output) if the per-file git diff itself fails, so the
+# caller can fail CLOSED rather than mistake a git error for "no added lines".
+added_lines() {
+  local out
+  out=$(git diff "${BASE}"...HEAD -- "$1") || return 2
+  printf '%s' "$out" | awk '
+    /^@@/       { if (match($0, /\+[0-9]+/)) n = substr($0, RSTART+1, RLENGTH-1) + 0; next }
+    /^\+\+\+/   { next }
+    /^\+/       { print n "\t" substr($0, 2); n++; next }
+    /^-/        { next }
+    /^ /        { n++; next }
+  '
+}
+
+# Walk the changed files. Enumerate with -z (NUL-delimited) and
+# core.quotepath=false so paths with non-ASCII bytes, spaces, tabs or newlines
+# arrive RAW: under the default quotepath git octal-escapes and quotes such a
+# path, and the escaped string then matches no file — silently skipping every
+# content check (a leaked secret in `café.ts` would pass GREEN). Captured to a
+# file (a bash variable cannot hold the NUL delimiters) with an exit check so a
+# git error fails CLOSED, not silently clean.
+NAMES=$(mktemp) || fail_closed "cannot create a temp file"
+trap 'rm -f "$NAMES"' EXIT
+git -c core.quotepath=false diff --name-status -z "${BASE}"...HEAD >"$NAMES" \
+  || fail_closed "git diff --name-status failed for base '${BASE}'"
+
+# -z records: `status\0path\0`, or `R###\0old\0new\0` for renames/copies.
+while IFS= read -r -d '' status; do
+  case "$status" in
+    R* | C*) IFS= read -r -d '' _src || break; IFS= read -r -d '' path || break ;;
+    D*) IFS= read -r -d '' _gone || break; continue ;;  # a deletion cannot leak
+    *) IFS= read -r -d '' path || break ;;
+  esac
+  [[ -z "${path:-}" ]] && continue
+
+  if _allowlisted "$path"; then
+    printf 'void-enforce: %s skipped (allowlisted in .github/void-enforce-allow)\n' "$path"
+    continue
+  fi
+
+  # 1) Never-edit file (path only): lockfile / key / secret filename / .git.
+  if protected=$("$NODE_BIN" "$RUNNER" enforce-ci protected-file "$path" </dev/null 2>&1); then :; else
+    # A committed diff cannot prove whether the package manager generated it.
+    # Dependency refreshes may leave manifests unchanged; keep content scanning.
+    if [[ "$protected" == *": lockfile (regenerate via the package manager, do not hand-edit)" ]]; then
+      annotate warning "$path" 1 "lockfile diff requires dependency validation: frozen install, vulnerability audit, tests and review; generation is not verified by this check"
+    else
+      protected_reason="${protected##*: }"
+      annotate error "$path" 1 "protected file: ${protected_reason//$'\n'/ }"
+      continue
+    fi
+  fi
+
+  # TDD judges final source even when the diff only removes lines.
+  if tdd=$("$NODE_BIN" "$RUNNER" enforce-ci tdd-order "$path" </dev/null 2>&1); then
+    [[ -z "$tdd" ]] || printf 'void-enforce: %s\n' "${tdd//$'\n'/ }"
+  else
+    annotate error "$path" 1 "${tdd//$'\n'/ }"
+  fi
+
+  # 2+3) Content checks over the ADDED lines, with real line numbers.
+  diff_added=$(added_lines "$path") || fail_closed "git diff failed for '${path}' (cannot scan its content)"
+  [[ -z "$diff_added" ]] && continue
+  LNOS=()
+  while IFS= read -r line_number; do
+    LNOS+=("$line_number")
+  done < <(printf '%s\n' "$diff_added" | cut -f1)
+  added_text=$(printf '%s\n' "$diff_added" | cut -f2-)
+
+  if hits=$(printf '%s' "$added_text" | "$NODE_BIN" "$RUNNER" enforce-ci secret-content "$path" 2>&1); then :; else
+    FOUND=0
+    while IFS= read -r hit; do
+      [[ "$hit" =~ ^-\ .+:([0-9]+)$ ]] || continue
+      FOUND=1
+      rel="${BASH_REMATCH[1]}"
+      annotate error "$path" "${LNOS[rel - 1]:-1}" "leaked secret (see harness:security-guidance)"
+    done <<<"$hits"
+    [[ "$FOUND" -eq 1 ]] || annotate error "$path" 1 "secret scan failed closed: ${hits//$'\n'/ }"
+  fi
+
+  if hits=$(printf '%s' "$added_text" | "$NODE_BIN" "$RUNNER" enforce-ci boundary-direction "$path" 2>&1); then :; else
+    FOUND=0
+    while IFS= read -r hit; do
+      [[ "$hit" =~ ^-\ .+:([0-9]+)\ \-\>\ (.+)$ ]] || continue
+      FOUND=1
+      rel="${BASH_REMATCH[1]}"
+      annotate error "$path" "${LNOS[rel - 1]:-1}" "forbidden @repo/* import: ${BASH_REMATCH[2]}"
+    done <<<"$hits"
+    [[ "$FOUND" -eq 1 ]] || annotate error "$path" 1 "boundary scan failed closed: ${hits//$'\n'/ }"
+  fi
+  # NB: checks_dangerous_command (the local Bash runtime guard) is deliberately
+  # NOT replayed over the diff. A destructive PATTERN committed into a file is a
+  # weak signal that self-matches the harness's own detector, security docs, and
+  # test fixtures — net-negative false positives for a floor check. Deferred to a
+  # follow-up with a proper per-line allow tag (see docs/DECISIONS.md).
+done <"$NAMES"
+
+if [[ "$FAIL" -ne 0 ]]; then
+  printf 'void-enforce: floor violations found (see annotations above).\n' >&2
+  exit 1
+fi
+printf 'void-enforce: clean — no floor violations in the diff.\n'
+exit 0

package/core-assets/hooks/_checks.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+# _checks.sh — pure detection functions for Void Machine enforcement floor.
+# SOURCED, never executed (leading underscore = library; exempt from the hook
+# size cap, still syntax-checked — see scripts/anti-bloat-check.sh).
+#
+# WHY this file exists (DEV-393): the floor (never-edit files, leaked secrets,
+# @repo/* import direction, catastrophic shell) must be enforced identically by
+# the PreToolUse hooks (Claude runtime, per-edit) AND the CI diff driver
+# (enforce/ci-enforce.sh, per-PR). Extracting the detection here makes it ONE
+# body of logic — the local hook and the server-side Action can never diverge.
+#
+# Contract: every function returns 1 and prints a payload on STDOUT when it
+# detects a violation; returns 0 and prints nothing when the input is clean.
+# Functions never `exit` (they are sourced) and never depend on the caller's
+# stdin plumbing (_hooklib.sh) — path comes as $1, edited content on stdin.
+# Content checks emit `<n>:<line>` (grep -n numbering over the scanned content)
+# so a caller can map a hit back to a real file line for an annotation.
+
+# checks_sensitive_path <path>: 1 + reason if the path is a never-edit file
+# (env/secret/key/credential/lockfile/.git), else 0. Case-insensitive: on a
+# case-insensitive FS .ENV and .env are the same file.
+checks_sensitive_path() {
+  local path="$1" base lpath
+  [[ -z "$path" ]] && return 0
+  base=$(basename "$path" | tr '[:upper:]' '[:lower:]')
+  lpath=$(printf '%s' "$path" | tr '[:upper:]' '[:lower:]')
+  if [[ "$base" =~ ^\.env(\..+)?$ ]] && [[ ! "$base" =~ \.(example|sample|template|dist)$ ]]; then
+    printf 'environment file with secrets\n'; return 1; fi
+  if [[ "$base" =~ \.(pem|key|p12|pfx|keystore|jks|asc)$ || "$base" =~ ^id_(rsa|ed25519|ecdsa|dsa)$ ]]; then
+    printf 'private key / certificate\n'; return 1; fi
+  if [[ "$base" =~ (\.npmrc$|\.netrc$|\.pgpass$) ]]; then
+    printf 'credential file\n'; return 1; fi
+  # The loose secret|credential NAME match is a heuristic; exempt markdown docs.
+  # A real credential file is never .md, and content secret-scanning still covers
+  # .md, so this only removes false positives (e.g. a decision note whose slug
+  # contains "…-byo-credentials.md" is documentation, not a credential file).
+  if [[ ! "$base" =~ \.md$ ]] && [[ "$base" =~ (secret|credential) ]]; then
+    printf 'credential file\n'; return 1; fi
+  case "$base" in
+    package-lock.json|pnpm-lock.yaml|yarn.lock|bun.lock|bun.lockb|cargo.lock|poetry.lock|composer.lock)
+      printf 'lockfile (regenerate via the package manager, do not hand-edit)\n'; return 1 ;;
+  esac
+  [[ "$lpath" =~ (^|/)\.git/ ]] && { printf 'internal git metadata\n'; return 1; }
+  return 0
+}
+
+# checks_boundary_imports <path> (content on stdin): 1 + `<n>:<line>` for each
+# forbidden @repo/* import from packages/<X>/ (X may only import @repo/core or
+# itself). No-ops for apps/, packages/core/, test/generated files — those
+# exemptions are check semantics, so they live here, not in each caller.
+checks_boundary_imports() {
+  local file="$1" content pkg re_import violations="" line import target
+  content=$(cat)
+  [[ "$file" =~ ^packages/[^/]+/ ]] || return 0
+  [[ "$file" =~ ^packages/core/ ]] && return 0
+  [[ "$file" =~ \.(test|spec)\.(ts|tsx)$|\.d\.ts$|/__generated__/ ]] && return 0
+  # The @repo/* direction is a TypeScript-source rule. Docs (.md — e.g. skill
+  # examples that show a forbidden `import ... from '@repo/db'` marked ✗) carry
+  # such imports as illustrations, never as real edges — only .ts/.tsx count.
+  [[ "$file" =~ \.(ts|tsx)$ ]] || return 0
+  pkg=$(printf '%s' "$file" | sed -E 's|^packages/([^/]+)/.*|\1|')
+  re_import="from[[:space:]]+['\"]@repo/([a-zA-Z0-9-]+)"
+  while IFS= read -r line; do
+    import=$(printf '%s' "$line" | grep -oE '@repo/[a-zA-Z0-9-]+' | head -1)
+    target=$(printf '%s' "$import" | sed 's|@repo/||')
+    if [[ -n "$target" && "$target" != "core" && "$target" != "$pkg" ]]; then
+      violations="${violations}${line}"$'\n'
+    fi
+  done < <(printf '%s' "$content" | grep -nE "$re_import" | grep -vE '// *allow-boundary:' || true)
+  [[ -n "$violations" ]] && { printf '%s' "$violations"; return 1; }
+  return 0
+}
+
+# checks_secret_content <path> (content on stdin): 1 + `<n>:<line>` for each line
+# leaking a HIGH-confidence secret. Test-fixture paths are exempt (fake secrets
+# are legitimate there). POSIX ERE only (no grep -P, #64).
+checks_secret_content() {
+  local file="$1" content re_hi re_assign n=0 line val hits=""
+  content=$(cat)
+  [[ "$file" =~ \.(test|spec)\.|/__tests__/|/__fixtures__/|/fixtures/|/__generated__/ ]] && return 0
+
+  re_hi='AKIA[0-9A-Z]{16}|ASIA[0-9A-Z]{16}'                                  # AWS
+  re_hi="$re_hi"'|gh[posru]_[A-Za-z0-9]{36}|github_pat_[A-Za-z0-9_]{40,}'    # GitHub
+  re_hi="$re_hi"'|sk_live_[A-Za-z0-9]{20,}|rk_live_[A-Za-z0-9]{20,}'         # Stripe
+  re_hi="$re_hi"'|sk-ant-[A-Za-z0-9_-]{40,}|sk-proj-[A-Za-z0-9_-]{40,}'      # Anthropic/OpenAI
+  re_hi="$re_hi"'|sk-[A-Za-z0-9]{40,}|xox[baprs]-[A-Za-z0-9-]{10,}'          # OpenAI/Slack
+  re_hi="$re_hi"'|AIza[0-9A-Za-z_-]{35}'                                     # Google API
+  re_hi="$re_hi"'|-----BEGIN [A-Z ]*PRIVATE KEY-----'                        # PEM
+  re_assign='(_KEY|_SECRET|_TOKEN|_PASSWORD|_PASSWD|_APIKEY)["'\'' ]*[:=][ ]*["'\'']([A-Za-z0-9+/=_-]{24,})["'\'']'
+
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    n=$((n + 1))
+    printf '%s' "$line" | grep -qE 'allow-secret-pattern:' && continue
+    if printf '%s' "$line" | grep -qE "$re_hi"; then hits="${hits}${n}:${line}"$'\n'; continue; fi
+    printf '%s' "$line" | grep -qiE "$re_assign" || continue
+    val=$(printf '%s' "$line" | sed -E "s/.*[:=][ ]*[\"']([A-Za-z0-9+/=_-]{24,})[\"'].*/\1/")
+    printf '%s' "$line" | grep -qiE 'process\.env|import\.meta\.env|xxx|changeme|example|redacted|your[-_]|<[a-z]|placeholder|todo' && continue
+    [[ "$val" =~ ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ ]] && continue
+    [[ "$val" =~ ^[0-9a-fA-F]+$ ]] && continue
+    printf '%s' "$val" | grep -qE '[A-Za-z]' && printf '%s' "$val" | grep -qE '[0-9]' || continue
+    hits="${hits}${n}:${line}"$'\n'
+  done < <(printf '%s' "$content")
+
+  [[ -n "$hits" ]] && { printf '%s' "$hits"; return 1; }
+  return 0
+}
+
+# checks_dangerous_command (command text on stdin): 1 + a short label if the
+# text contains a catastrophic shell pattern (recursive root delete, fork bomb,
+# raw-device write, root chmod/chown, force-push, unsafe git flags, DROP/
+# TRUNCATE). Best-effort blocklist, not a complete boundary.
+checks_dangerous_command() {
+  local cmd norm
+  cmd=$(cat)
+  [[ -z "$cmd" ]] && return 0
+  norm=$(printf '%s' "$cmd" | tr -d "\"'")
+  local HOME_ROOT='(/\*?|~/?\*?|\$HOME/?\*?|\$\{HOME\}/?\*?)'
+  local RM_TARGET='('"$HOME_ROOT"'|\./?\*?|\*)'
+
+  if printf '%s' "$norm" | grep -qE '(^|[;&|[:space:]])rm([[:space:]]+(-[a-zA-Z]+|--[a-z-]+))*[[:space:]]+(-[a-zA-Z]*[rR]|--recursive)' \
+    && printf '%s' "$norm" | grep -qE "(^|[;&|[:space:]])rm([[:space:]]+[a-zA-Z-]+)*[[:space:]]+(--[[:space:]]+)?${RM_TARGET}([[:space:]]|$)"; then
+    printf 'recursive delete of a root path\n'; return 1; fi
+
+  printf '%s' "$cmd" | grep -qE ':\(\)[[:space:]]*\{[[:space:]]*:[[:space:]]*\|[[:space:]]*:' \
+    && { printf 'fork bomb\n'; return 1; }
+
+  printf '%s' "$cmd" | grep -qE '\bmkfs(\.[a-z0-9]+)?\b|\bdd\b[^|]*\bof=/dev/|>[[:space:]]*/dev/(sd|nvme|hd|disk)' \
+    && { printf 'filesystem / raw-device write\n'; return 1; }
+
+  if printf '%s' "$norm" | grep -qE 'ch(mod|own)([[:space:]]+[a-zA-Z0-9-]+)*[[:space:]]+(-[a-zA-Z]*R|--recursive)' \
+    && printf '%s' "$norm" | grep -qE "[[:space:]](--[[:space:]]+)?${HOME_ROOT}([[:space:]]|$)"; then
+    printf 'recursive permission/ownership change on a root path\n'; return 1; fi
+
+  printf '%s' "$cmd" | grep -qE 'git[[:space:]]+push\b[^&|;]*[[:space:]](--force([^-]|$)|-f([[:space:]]|$))' \
+    && { printf 'git push --force (use --force-with-lease)\n'; return 1; }
+
+  if printf '%s' "$cmd" | grep -qE '\bgit\b([[:space:]]+-[^[:space:]]+)*[[:space:]]+(rebase|am|apply|cherry-pick)\b' \
+    && printf '%s' "$cmd" | grep -qE '(--exec([[:space:]=]|$)|--rebase-merges|--strategy-option|--unsafe-paths)'; then
+    printf 'git command-execution / unsafe-path flag\n'; return 1; fi
+
+  printf '%s' "$cmd" | grep -qiE '\b(drop[[:space:]]+(database|table|schema)|truncate[[:space:]]+table)\b' \
+    && { printf 'destructive SQL (DROP / TRUNCATE)\n'; return 1; }
+
+  return 0
+}

package/core-assets/hooks/_hooklib.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+# _hooklib.sh — shared helpers for the PreToolUse Edit|Write enforcement hooks.
+# SOURCED, never executed (leading underscore = library; excluded from the
+# hook-size anti-bloat rule, see scripts/anti-bloat-check.sh). Goals (#63):
+#   - parse the Claude Code stdin JSON exactly once per hook;
+#   - never fail OPEN when jq is missing: scalar fields fall back to pure-bash
+#     extraction, and content-scanning hooks fail CLOSED with one explicit
+#     message rather than silently skipping enforcement (the audited bug: an
+#     unguarded jq call exited 127 under `set -e`, which Claude treats as a
+#     non-blocking error, so the whole hook layer went dark without jq);
+#   - share the physical-path root normalization introduced for #62.
+# Every symbol is prefixed hooklib_ / _hooklib_.
+
+# hooklib_read: consume stdin once. Sets HOOK_INPUT and HOOK_JQ (1 iff jq usable).
+hooklib_read() {
+  HOOK_INPUT=$(cat)
+  if command -v jq >/dev/null 2>&1; then HOOK_JQ=1; else HOOK_JQ=0; fi
+}
+
+# hooklib_str <jq-filter> <bash-key>: extract a JSON scalar string from
+# HOOK_INPUT. jq when available; else a pure-bash regex on the (unescaped)
+# "<bash-key>": "<value>" pair — exact for the flat scalar fields we read.
+hooklib_str() {
+  if [[ "${HOOK_JQ:-0}" == 1 ]]; then
+    printf '%s' "$HOOK_INPUT" | jq -r "$1 // empty" 2>/dev/null || true
+  else
+    local re="\"$2\"[[:space:]]*:[[:space:]]*\"([^\"]*)\""
+    [[ "$HOOK_INPUT" =~ $re ]] && printf '%s' "${BASH_REMATCH[1]}"
+    return 0
+  fi
+}
+
+hooklib_tool() { hooklib_str '.tool_name' 'tool_name'; }
+hooklib_file() { hooklib_str '.tool_input.file_path' 'file_path'; }
+
+# hooklib_content: the edited text (.content for Write, .new_string for Edit).
+# jq gives the exact, unescaped text. Returns 1 (prints nothing) when jq is
+# absent — a pure-bash JSON string-unescape is not reliable enough to scan for
+# forbidden patterns, so the caller must gate on hooklib_require_jq first.
+hooklib_content() {
+  [[ "${HOOK_JQ:-0}" == 1 ]] || return 1
+  printf '%s' "$HOOK_INPUT" | jq -r '.tool_input.content // .tool_input.new_string // empty' 2>/dev/null || true
+}
+
+# hooklib_command: shell command (.command string, or Codex argv array joined).
+hooklib_command() {
+  if [[ "${HOOK_JQ:-0}" == 1 ]]; then
+    printf '%s' "$HOOK_INPUT" \
+      | jq -r 'if (.tool_input.command? | type) == "array" then (.tool_input.command | join(" ")) else (.tool_input.command // empty) end' 2>/dev/null || true
+  else
+    hooklib_str '.tool_input.command' 'command'
+  fi
+}
+
+# Framing for the hooklib_edits stream (ASCII RS/US). Edited content routinely
+# contains newlines and tabs, so neither can frame the records.
+_HOOKLIB_RS=$'\036'
+_HOOKLIB_US=$'\037'
+
+# _hooklib_patch_text: the raw apply_patch envelope, whichever field a given
+# Codex build carries it in. Same candidate list as the floor's
+# protect-sensitive-files, so the two can never disagree on where a patch lives.
+_hooklib_patch_text() {
+  printf '%s' "$HOOK_INPUT" \
+    | jq -r '[.tool_input.input, .tool_input.patch, .tool_input.content, .tool_input.command]
+             | map(select(. != null))
+             | map(if type == "array" then join("\n") else . end)
+             | .[]' 2>/dev/null || true
+}
+
+# _hooklib_parse_patch: stdin = an apply_patch envelope; stdout = one
+# <path>US<added-content>RS record per Add/Update section. Only ADDED (`+`)
+# lines are collected, so a REMOVED or untouched context line can never trip a
+# forbidden-pattern scan — the Codex equivalent of Claude's `.new_string`. A
+# Delete section yields no record: there is nothing left to scan.
+_hooklib_parse_patch() {
+  awk -v USEP="$_HOOKLIB_US" -v RSEP="$_HOOKLIB_RS" '
+    function emit() { if (path != "") printf "%s%s%s%s", path, USEP, buf, RSEP }
+    /^\*\*\* (Add|Update) File: / { emit(); path = substr($0, index($0, "File: ") + 6); buf = ""; next }
+    /^\*\*\* Delete File: /       { emit(); path = ""; buf = ""; next }
+    /^\*\*\* (Begin|End) Patch/   { next }
+    { if (path != "" && substr($0, 1, 1) == "+" && substr($0, 1, 3) != "+++") buf = buf substr($0, 2) "\n" }
+    END { emit() }
+  '
+}
+
+# hooklib_edits: the edits of THIS tool call as a NORMALIZED, runtime-agnostic
+# stream of <path>US<new-content>RS records — one per edited file. It exists so a
+# content-scanning hook iterates instead of assuming Claude's single-file shape:
+#   - Claude: Edit|Write  -> one record (.tool_input.file_path + .content/.new_string)
+#   - Codex:  apply_patch -> one record per patched file, carrying its added lines
+# Wiring those hooks for Codex WITHOUT this would fire them against an empty
+# payload: a wired-but-dead hook, which is a silent enforcement hole rather than
+# an honest absence. Requires jq (exact content extraction) — callers gate on
+# hooklib_require_jq first. Read it with:
+#   while IFS= read -r -d "$_HOOKLIB_RS" rec; do
+#     file="${rec%%"$_HOOKLIB_US"*}"; new="${rec#*"$_HOOKLIB_US"}"
+#   done < <(hooklib_edits)
+hooklib_edits() {
+  # Without jq: degrade to the pure-bash file_path, emitting one CONTENTLESS
+  # record. That keeps the PATH-ONLY hooks (tdd-guard, auto-format) enforcing on
+  # the Claude shape exactly as they did before this stream existed. It does not
+  # weaken the content-scanning hooks: those call hooklib_require_jq BEFORE the
+  # loop and have already exited 2 by the time they would read a record (#63).
+  # A Codex patch simply cannot be parsed without jq, so it yields nothing.
+  if [[ "${HOOK_JQ:-0}" != 1 ]]; then
+    local bash_file
+    bash_file=$(hooklib_file)
+    [[ -n "$bash_file" ]] && printf '%s%s%s' "$bash_file" "$_HOOKLIB_US" "$_HOOKLIB_RS"
+    return 0
+  fi
+  # A file_path means the single-file runtime shape. The patch parse is then
+  # deliberately skipped: file CONTENT that happens to document the apply_patch
+  # format (this repo's own docs do) would otherwise forge phantom records.
+  if [[ -n "$(hooklib_file)" ]]; then
+    printf '%s' "$HOOK_INPUT" \
+      | jq -j --arg us "$_HOOKLIB_US" --arg rs "$_HOOKLIB_RS" \
+          '.tool_input.file_path + $us + ((.tool_input.content // .tool_input.new_string) // "") + $rs' \
+          2>/dev/null || true
+    return 0
+  fi
+  _hooklib_patch_text | _hooklib_parse_patch
+  return 0
+}
+
+# hooklib_require_jq [name]: a content-scanning hook cannot verify an edit
+# without jq. Rather than fail OPEN (the #63 bug), block once with an explicit,
+# actionable message. jq is a documented prerequisite (void-machine doctor).
+hooklib_require_jq() {
+  [[ "${HOOK_JQ:-0}" == 1 ]] && return 0
+  printf '%s: jq is required to inspect edit content but is not installed.\n' "${1:-hook}" >&2
+  printf 'Blocking rather than silently skipping enforcement. Install jq\n' >&2
+  printf '(e.g. brew install jq) or run: void-machine doctor.\n' >&2
+  exit 2
+}
+
+# hooklib_root: the project root in physical form (CLAUDE_PROJECT_DIR, else the
+# git toplevel, else pwd). Trailing slash stripped.
+hooklib_root() {
+  local r
+  r=$(_hooklib_phys "${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}")
+  printf '%s' "${r%/}"
+}
+
+# hooklib_relpath <path>: strip the project-root prefix so root-anchored globs
+# match the ABSOLUTE paths Claude Code passes (#62). Physical-path compare
+# (logical/physical roots differ under symlinks, e.g. macOS /var -> /private/var).
+hooklib_relpath() {
+  local file="$1" root
+  [[ "$file" == /* ]] || { printf '%s' "$file"; return 0; }
+  root=$(hooklib_root)
+  file=$(_hooklib_phys "$file")
+  case "$file" in "$root"/*) file="${file#"$root"/}" ;; esac
+  printf '%s' "$file"
+}
+
+# _hooklib_phys: resolve the longest existing directory prefix to its physical
+# path, then re-append the trailing (possibly non-existent) components.
+_hooklib_phys() {
+  local p="$1" t=""
+  while [[ ! -d "$p" && "$p" == */* ]]; do t="/${p##*/}$t"; p="${p%/*}"; done
+  if [[ -d "$p" ]]; then printf '%s%s' "$(cd "$p" && pwd -P)" "$t"; else printf '%s' "$1"; fi
+}