@bookedsolid/rea 0.28.2 → 0.30.0

package/dist/registry/loader.d.ts

@@ -18,20 +18,20 @@ declare const RegistryServerSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
 }, "strict", z.ZodTypeAny, {
     name: string;
+    enabled: boolean;
+    env: Record<string, string>;
     command: string;
     args: string[];
-    env: Record<string, string>;
-    enabled: boolean;
     env_passthrough?: string[] | undefined;
     tier_overrides?: Record<string, Tier> | undefined;
 }, {
     name: string;
     command: string;
-    args?: string[] | undefined;
+    enabled?: boolean | undefined;
     env?: Record<string, string> | undefined;
+    args?: string[] | undefined;
     env_passthrough?: string[] | undefined;
     tier_overrides?: Record<string, Tier> | undefined;
-    enabled?: boolean | undefined;
 }>;
 declare const RegistrySchema: z.ZodObject<{
     version: z.ZodLiteral<"1">;
@@ -45,30 +45,30 @@ declare const RegistrySchema: z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
     }, "strict", z.ZodTypeAny, {
         name: string;
+        enabled: boolean;
+        env: Record<string, string>;
         command: string;
         args: string[];
-        env: Record<string, string>;
-        enabled: boolean;
         env_passthrough?: string[] | undefined;
         tier_overrides?: Record<string, Tier> | undefined;
     }, {
         name: string;
         command: string;
-        args?: string[] | undefined;
+        enabled?: boolean | undefined;
         env?: Record<string, string> | undefined;
+        args?: string[] | undefined;
         env_passthrough?: string[] | undefined;
         tier_overrides?: Record<string, Tier> | undefined;
-        enabled?: boolean | undefined;
     }>, "many">>;
     reviewer: z.ZodOptional<z.ZodEnum<["codex", "claude-self"]>>;
 }, "strict", z.ZodTypeAny, {
     version: "1";
     servers: {
         name: string;
+        enabled: boolean;
+        env: Record<string, string>;
         command: string;
         args: string[];
-        env: Record<string, string>;
-        enabled: boolean;
         env_passthrough?: string[] | undefined;
         tier_overrides?: Record<string, Tier> | undefined;
     }[];
@@ -78,11 +78,11 @@ declare const RegistrySchema: z.ZodObject<{
     servers?: {
         name: string;
         command: string;
-        args?: string[] | undefined;
+        enabled?: boolean | undefined;
         env?: Record<string, string> | undefined;
+        args?: string[] | undefined;
         env_passthrough?: string[] | undefined;
         tier_overrides?: Record<string, Tier> | undefined;
-        enabled?: boolean | undefined;
     }[] | undefined;
     reviewer?: "codex" | "claude-self" | undefined;
 }>;

package/hooks/delegation-capture.sh

@@ -0,0 +1,158 @@
+#!/bin/bash
+# PreToolUse hook: delegation-capture.sh
+# 0.29.0+ — delegation-telemetry MVP.
+#
+# Fires BEFORE every `Agent` or `Skill` tool call. Reads the Claude
+# Code hook payload from stdin, pipes it to
+# `rea hook delegation-signal --detach`, and exits 0 immediately.
+#
+# The signal is OBSERVATIONAL — never gates tool dispatch. Worst-case
+# latency budget is ~50ms even when the audit chain is under
+# cross-process contention, because the audit append runs in the
+# background (via `&`) and the CLI subcommand itself only validates
+# the payload before forking the writer.
+#
+# Matcher: `Agent|Skill` (NOT `Task|Skill` — `TaskCreate`/`TaskList`
+# are the unrelated todo-list tools and MUST NOT match).
+#
+# # CLI-resolution trust boundary
+#
+# Codex round 3 P1 (2026-05-12): pre-fix this hook resolved the rea
+# binary via `$REA_ROOT/node_modules/.bin/rea` then PATH-walked
+# `command -v rea`. Either path was attacker-influenced in a consumer
+# repo with a forged `node_modules/.bin/rea` symlink or a
+# PATH-prepended fake `rea` binary — giving attacker-controlled code
+# execution on every Agent/Skill dispatch.
+#
+# Fix: this hook now uses the same 2-tier sandboxed resolution that
+# protected-paths-bash-gate.sh + blocked-paths-bash-gate.sh use:
+#   1. node_modules/@bookedsolid/rea/dist/cli/index.js (consumer-side
+#      published artifact)
+#   2. dist/cli/index.js under CLAUDE_PROJECT_DIR (the rea repo's own
+#      dogfood install)
+#
+# A realpath sandbox check ensures the resolved CLI lives INSIDE
+# realpath(CLAUDE_PROJECT_DIR) — catches symlink-out attacks.
+#
+# Exit codes:
+#   0 — always (under normal operation). Failure to write the audit
+#       signal must NEVER block Claude Code's tool dispatch. Stderr
+#       breadcrumbs surface diagnostic info to the operator. HALT
+#       still exits 2 because the kill-switch contract must hold.
+#   2 — HALT active.
+
+set -uo pipefail
+
+# 1. HALT check. Even though this hook is observational, refusing to
+#    emit signals while frozen matches the rest of the hook tree and
+#    keeps the kill-switch contract uniform.
+# shellcheck source=_lib/halt-check.sh
+source "$(dirname "$0")/_lib/halt-check.sh"
+check_halt
+REA_ROOT=$(rea_root)
+
+proj="${CLAUDE_PROJECT_DIR:-$REA_ROOT}"
+
+# 2. Resolve the rea CLI through the same fixed 2-tier sandboxed order
+#    the protected-paths / blocked-paths bash gates use. PATH lookup
+#    is INTENTIONALLY OMITTED — agent-controlled $PATH would let a
+#    forged `rea` binary on a consumer machine intercept the
+#    delegation signal on every Agent/Skill dispatch. The trade-off:
+#    consumers MUST have `@bookedsolid/rea` installed under
+#    `node_modules` (the common case after `pnpm i`) OR be running
+#    against the rea repo's own dogfood (where dist/cli/index.js
+#    holds the canonical CLI). Other install shapes silently drop the
+#    signal — matching the bash-gate posture.
+REA_ARGV=()
+RESOLVED_CLI_PATH=""
+if [ -f "$proj/node_modules/@bookedsolid/rea/dist/cli/index.js" ]; then
+  REA_ARGV=(node "$proj/node_modules/@bookedsolid/rea/dist/cli/index.js")
+  RESOLVED_CLI_PATH="$proj/node_modules/@bookedsolid/rea/dist/cli/index.js"
+elif [ -f "$proj/dist/cli/index.js" ]; then
+  # rea repo dogfood: the project IS @bookedsolid/rea.
+  REA_ARGV=(node "$proj/dist/cli/index.js")
+  RESOLVED_CLI_PATH="$proj/dist/cli/index.js"
+fi
+
+if [ "${#REA_ARGV[@]}" -eq 0 ]; then
+  # No rea CLI in scope — drop the signal silently. This is the
+  # expected state during bootstrap (consumer ran `rea init` but
+  # hasn't installed the npm package yet) or in non-rea repos. A
+  # noisy stderr warning here would fire on every Agent/Skill
+  # dispatch and drown legitimate signals.
+  exit 0
+fi
+
+# 3. Realpath sandbox check — mirrors protected-paths-bash-gate.sh §6.
+#    The resolved CLI MUST live inside realpath(CLAUDE_PROJECT_DIR)
+#    AND have an ancestor package.json declaring `@bookedsolid/rea`
+#    as its `name`. Catches symlink-out attacks where an attacker
+#    writes node_modules/@bookedsolid/rea → /tmp/forged-tree.
+if ! command -v node >/dev/null 2>&1; then
+  # Node not on PATH — we can't verify the CLI shape. Fail safe by
+  # dropping the signal (observability is not a security claim; the
+  # rest of the Bash gate suite refuses on this path).
+  exit 0
+fi
+
+sandbox_check=$(node -e '
+  const fs = require("fs");
+  const path = require("path");
+  const cli = process.argv[1];
+  const projDir = process.argv[2];
+  let real, realProj;
+  try { real = fs.realpathSync(cli); } catch (e) {
+    process.stdout.write("bad:realpath");
+    process.exit(1);
+  }
+  try { realProj = fs.realpathSync(projDir); } catch (e) {
+    process.stdout.write("bad:realpath-proj");
+    process.exit(1);
+  }
+  const sep = path.sep;
+  const projWithSep = realProj.endsWith(sep) ? realProj : realProj + sep;
+  if (!(real === realProj || real.startsWith(projWithSep))) {
+    process.stdout.write("bad:cli-escapes-project");
+    process.exit(1);
+  }
+  // Walk up looking for package.json with the protected name.
+  let cur = path.dirname(path.dirname(path.dirname(real))); // pkg root
+  let found = false;
+  for (let i = 0; i < 20 && cur && cur !== path.dirname(cur); i += 1) {
+    const pj = path.join(cur, "package.json");
+    if (fs.existsSync(pj)) {
+      try {
+        const data = JSON.parse(fs.readFileSync(pj, "utf8"));
+        if (data && data.name === "@bookedsolid/rea") { found = true; break; }
+      } catch (e) { /* keep walking */ }
+    }
+    cur = path.dirname(cur);
+  }
+  if (!found) {
+    process.stdout.write("bad:no-rea-pkg-json");
+    process.exit(1);
+  }
+  process.stdout.write("ok");
+' -- "$RESOLVED_CLI_PATH" "$proj" 2>/dev/null)
+
+if [ "$sandbox_check" != "ok" ]; then
+  # CLI failed the sandbox check — silent drop. The forensic
+  # breadcrumb in stderr is intentional but trimmed so this doesn't
+  # become spammy on every dispatch.
+  printf 'rea: delegation-capture skipped (sandbox check: %s)\n' "$sandbox_check" >&2
+  exit 0
+fi
+
+# 4. Read stdin and pipe to the CLI. `--detach` tells the CLI to
+#    suppress stderr output (no parent shell is listening); we ALSO
+#    background the whole pipeline with `&` and `disown` so the
+#    shell hook returns instantly even if the CLI's own startup
+#    takes a few ms.
+INPUT=$(cat)
+{
+  printf '%s' "$INPUT" | "${REA_ARGV[@]}" hook delegation-signal --detach \
+    >/dev/null 2>&1 &
+  disown 2>/dev/null || true
+} 2>/dev/null
+
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/rea",
-  "version": "0.28.2",
+  "version": "0.30.0",
   "description": "Agentic governance layer for Claude Code — policy enforcement, hook-based safety gates, audit logging, and Codex-integrated adversarial review for AI-assisted projects",
   "license": "MIT",
   "author": "Booked Solid Technology <oss@bookedsolid.tech> (https://bookedsolid.tech)",

package/profiles/bst-internal-no-codex.yaml

@@ -43,3 +43,18 @@ context_protection:
     - pnpm run test
     - pnpm run lint
   max_bash_output_lines: 100
+# 0.30.0 attribution augmenter — opt-in.
+# Husky prepare-commit-msg hook appends a Co-Authored-By trailer to
+# every commit when enabled. Even the bst-internal profile ships
+# `enabled: false` so other BST contributors using the profile don't
+# silently route their commits onto the profile author's GitHub
+# heatmap; opt-in lives in repo-local edits to .rea/policy.yaml.
+# attribution:
+#   co_author:
+#     enabled: true
+#     name: 'Your Name'
+#     email: 'you@example.com'
+#     skip_merge: false
+attribution:
+  co_author:
+    enabled: false

package/profiles/bst-internal.yaml

@@ -51,3 +51,19 @@ architecture_review:
     - hooks/_lib/
     - templates/
     - profiles/
+# 0.30.0 attribution augmenter — opt-in.
+# Husky prepare-commit-msg hook appends a Co-Authored-By trailer to
+# every commit when enabled. Even the bst-internal profile ships
+# `enabled: false` so other BST contributors using the profile don't
+# silently route their commits onto the profile author's GitHub
+# heatmap; opt-in lives in repo-local edits to .rea/policy.yaml
+# because the identity to roll commits onto is per-developer.
+# attribution:
+#   co_author:
+#     enabled: true
+#     name: 'Your Name'
+#     email: 'you@example.com'
+#     skip_merge: false
+attribution:
+  co_author:
+    enabled: false

package/profiles/client-engagement.yaml

@@ -21,3 +21,17 @@ context_protection:
     - pnpm run build
     - pnpm run test
   max_bash_output_lines: 100
+# 0.30.0 attribution augmenter — opt-in.
+# Husky prepare-commit-msg hook appends a Co-Authored-By trailer to
+# every commit when enabled. client-engagement profile ships
+# `enabled: false`; opt-in lives in repo-local edits to .rea/policy.yaml
+# because the identity to roll commits onto is per-developer.
+# attribution:
+#   co_author:
+#     enabled: true
+#     name: 'Your Name'
+#     email: 'you@example.com'
+#     skip_merge: false
+attribution:
+  co_author:
+    enabled: false

package/profiles/lit-wc.yaml

@@ -15,3 +15,17 @@ blocked_paths:
   - .github/workflows/publish.yml
   - tokens/
 notification_channel: ''
+# 0.30.0 attribution augmenter — opt-in.
+# Husky prepare-commit-msg hook appends a Co-Authored-By trailer to
+# every commit when enabled. lit-wc profile ships `enabled: false`;
+# opt-in lives in repo-local edits to .rea/policy.yaml because the
+# identity to roll commits onto is per-developer.
+# attribution:
+#   co_author:
+#     enabled: true
+#     name: 'Your Name'
+#     email: 'you@example.com'
+#     skip_merge: false
+attribution:
+  co_author:
+    enabled: false

package/profiles/minimal.yaml

@@ -9,3 +9,19 @@ blocked_paths:
   - .env
   - .env.*
 notification_channel: ''
+# 0.30.0 attribution augmenter — opt-in.
+# When enabled: true, the husky prepare-commit-msg hook appends a
+# Co-Authored-By trailer to every commit (or every non-merge commit
+# when skip_merge: true). Idempotent on email match (case-insensitive).
+# Profile defaults are off; opt in per-repo via .rea/policy.yaml —
+# the identity to roll commits onto is per-developer.
+#
+# attribution:
+#   co_author:
+#     enabled: true
+#     name: 'Your Name'
+#     email: 'you@example.com'
+#     skip_merge: false
+attribution:
+  co_author:
+    enabled: false

package/profiles/open-source-no-codex.yaml

@@ -31,3 +31,16 @@ blocked_paths:
   - .github/workflows/release.yml
   - .github/workflows/publish.yml
 notification_channel: ''
+# 0.30.0 attribution augmenter — opt-in.
+# Husky prepare-commit-msg hook appends a Co-Authored-By trailer to
+# every commit when enabled. Profile defaults are off — opt in
+# per-repo via .rea/policy.yaml because the identity is per-developer.
+# attribution:
+#   co_author:
+#     enabled: true
+#     name: 'Your Name'
+#     email: 'you@example.com'
+#     skip_merge: false
+attribution:
+  co_author:
+    enabled: false

package/profiles/open-source.yaml

@@ -16,3 +16,16 @@ blocked_paths:
   - .github/workflows/release.yml
   - .github/workflows/publish.yml
 notification_channel: ''
+# 0.30.0 attribution augmenter — opt-in.
+# Husky prepare-commit-msg hook appends a Co-Authored-By trailer to
+# every commit when enabled. Profile defaults are off — opt in
+# per-repo via .rea/policy.yaml because the identity is per-developer.
+# attribution:
+#   co_author:
+#     enabled: true
+#     name: 'Your Name'
+#     email: 'you@example.com'
+#     skip_merge: false
+attribution:
+  co_author:
+    enabled: false

package/templates/prepare-commit-msg.husky.sh

@@ -0,0 +1,295 @@
+#!/bin/sh
+# rea:prepare-commit-msg v1
+# rea:augment-body-v1
+#
+# Husky prepare-commit-msg hook installed by `rea init` / `rea upgrade`.
+# Do NOT edit by hand — the file is refreshed on every rea upgrade.
+#
+# Governance contract: when policy.attribution.co_author.enabled is
+# `true`, append a `Co-Authored-By: <name> <email>` trailer to the
+# commit message file. Idempotent on email match (case-insensitive,
+# line-anchored). Skips merge commits when policy.attribution.co_author
+# .skip_merge is true.
+#
+# Triggers under all five commit sources git delivers:
+#   - $2 unset / empty   (`git commit` with no body provided)
+#   - $2 = 'message'     (`git commit -m "..."`)
+#   - $2 = 'template'    (commit.template configured)
+#   - $2 = 'merge'       (merge commit; honored by skip_merge: true)
+#   - $2 = 'squash'      (squash merge / rebase)
+#   - $2 = 'commit'      (`git commit --amend`)
+#
+# Skip conditions:
+#   - REA_SKIP_ATTRIBUTION=1 in env (per-invocation override)
+#   - .rea/HALT present (kill switch active)
+#   - $1 (message file path) missing or not a file
+#   - policy.attribution.co_author.enabled !== true
+#
+# Coexistence: this hook does NOT block on anything. The companion
+# `commit-msg` hook (which runs AFTER prepare-commit-msg in git's
+# lifecycle) still enforces `block_ai_attribution`. A human trailer
+# `Co-Authored-By: Real Name <real@email.tld>` is NOT AI attribution
+# (no AI noreply domain, no AI name keyword) and is not blocked.
+
+set -u
+
+COMMIT_MSG_FILE="${1:-}"
+COMMIT_SOURCE="${2:-}"
+
+# Skip conditions: any missing precondition exits 0 silently. The hook
+# is purely additive; refusing here would break commits with no upside.
+
+# Missing message file → nothing to augment.
+if [ -z "$COMMIT_MSG_FILE" ] || [ ! -f "$COMMIT_MSG_FILE" ]; then
+  exit 0
+fi
+
+# Per-invocation override.
+if [ -n "${REA_SKIP_ATTRIBUTION:-}" ]; then
+  exit 0
+fi
+
+REA_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+
+# HALT kill switch — refuse to mutate anything while frozen.
+if [ -f "${REA_ROOT}/.rea/HALT" ]; then
+  exit 0
+fi
+
+POLICY_FILE="${REA_ROOT}/.rea/policy.yaml"
+if [ ! -f "$POLICY_FILE" ]; then
+  exit 0
+fi
+
+# Delegate policy reads to the canonical rea CLI when available so we
+# get the zod-validated document regardless of whether the operator
+# wrote block-form (`attribution:\n  co_author:\n    enabled: true`)
+# or inline-form (`attribution: { co_author: { enabled: true } }`)
+# YAML. Codex round 1 P2: the prior Python inline parser only handled
+# block form. When the CLI is unreachable (fresh consumer install
+# pre-`pnpm i`, foreign dev environment, …) we fall back to the
+# embedded Python state machine — it correctly handles block-form
+# YAML, which is what `rea init` writes.
+#
+# Locator priority mirrors `.husky/pre-push`: project node_modules →
+# dogfood dist → PATH.
+rea_invoke() {
+  if [ -x "${REA_ROOT}/node_modules/.bin/rea" ]; then
+    "${REA_ROOT}/node_modules/.bin/rea" "$@"
+  elif [ -f "${REA_ROOT}/dist/cli/index.js" ] && [ -f "${REA_ROOT}/package.json" ] && grep -q '"name": *"@bookedsolid/rea"' "${REA_ROOT}/package.json" 2>/dev/null; then
+    node "${REA_ROOT}/dist/cli/index.js" "$@"
+  elif command -v rea >/dev/null 2>&1; then
+    rea "$@"
+  else
+    return 127
+  fi
+}
+
+ENABLED=$(rea_invoke hook policy-get attribution.co_author.enabled 2>/dev/null)
+REA_RC=$?
+
+if [ "$REA_RC" = "0" ]; then
+  CO_NAME=$(rea_invoke hook policy-get attribution.co_author.name 2>/dev/null || printf '')
+  CO_EMAIL=$(rea_invoke hook policy-get attribution.co_author.email 2>/dev/null || printf '')
+  SKIP_MERGE=$(rea_invoke hook policy-get attribution.co_author.skip_merge 2>/dev/null || printf 'false')
+elif command -v python3 >/dev/null 2>&1; then
+  # rea CLI unreachable — fall back to Python block-form parser.
+  CO_AUTHOR_PARSE=$(python3 - "$POLICY_FILE" <<'PY' 2>/dev/null
+import re
+import sys
+
+path = sys.argv[1]
+try:
+    with open(path, 'r', encoding='utf-8') as fh:
+        lines = fh.readlines()
+except OSError:
+    print('false'); print(''); print(''); print('false'); sys.exit(0)
+
+in_attr = False
+in_co = False
+enabled = 'false'
+name = ''
+email = ''
+skip_merge = 'false'
+
+def strip_value(raw):
+    raw = raw.rstrip('\n').rstrip()
+    if len(raw) >= 2 and raw[0] == raw[-1] and raw[0] in ("'", '"'):
+        return raw[1:-1]
+    if '#' in raw:
+        raw = raw.split('#', 1)[0].rstrip()
+    return raw
+
+for line in lines:
+    stripped_line = line.rstrip('\n')
+    if re.match(r'^\s*#', stripped_line):
+        continue
+    if re.match(r'^attribution:\s*(#.*)?$', stripped_line):
+        in_attr = True; in_co = False; continue
+    if in_attr and re.match(r'^\S', stripped_line):
+        in_attr = False; in_co = False
+    if in_attr and re.match(r'^\s+co_author:\s*(#.*)?$', stripped_line):
+        in_co = True; continue
+    if in_co:
+        m = re.match(r'^(\s*)\S', stripped_line)
+        if m and len(m.group(1)) <= 2:
+            in_co = False; continue
+        if re.search(r'enabled:\s*true(\s|$)', stripped_line):
+            enabled = 'true'
+        elif re.search(r'enabled:\s*false(\s|$)', stripped_line):
+            enabled = 'false'
+        if re.search(r'skip_merge:\s*true(\s|$)', stripped_line):
+            skip_merge = 'true'
+        elif re.search(r'skip_merge:\s*false(\s|$)', stripped_line):
+            skip_merge = 'false'
+        m = re.search(r'name:\s*(.*)$', stripped_line)
+        if m:
+            name = strip_value(m.group(1))
+        m = re.search(r'email:\s*(.*)$', stripped_line)
+        if m:
+            email = strip_value(m.group(1))
+
+print(enabled); print(name); print(email); print(skip_merge)
+PY
+)
+  if [ -z "$CO_AUTHOR_PARSE" ]; then
+    exit 0
+  fi
+  ENABLED=$(printf '%s\n' "$CO_AUTHOR_PARSE" | sed -n '1p')
+  CO_NAME=$(printf '%s\n' "$CO_AUTHOR_PARSE" | sed -n '2p')
+  CO_EMAIL=$(printf '%s\n' "$CO_AUTHOR_PARSE" | sed -n '3p')
+  SKIP_MERGE=$(printf '%s\n' "$CO_AUTHOR_PARSE" | sed -n '4p')
+else
+  # Neither rea CLI nor python3 reachable — silent no-op.
+  exit 0
+fi
+
+if [ "$ENABLED" != "true" ]; then
+  exit 0
+fi
+
+# Defense-in-depth: if we got here with enabled=true but no identity,
+# the policy loader's cross-field refinement was bypassed (or someone
+# edited the YAML around the load path). Bail without augmenting and
+# emit a stderr advisory so the operator sees the misconfig at commit
+# time. We deliberately do NOT exit non-zero — refusing the commit
+# would be more disruptive than the silent no-op (the loader + doctor
+# already surface the misconfig at policy load and at `rea doctor`).
+#
+# When `rea audit record <topic>` lands in a future release this
+# branch should emit a `rea.attribution_augmented_invalid_config`
+# record instead of stderr. Tracked as a 0.31.0+ item.
+if [ -z "$CO_NAME" ] || [ -z "$CO_EMAIL" ]; then
+  printf 'rea: attribution.co_author.enabled=true but %s%s%s is empty — augmenter no-op.\n' \
+    "$([ -z "$CO_NAME" ] && printf name)" \
+    "$([ -z "$CO_NAME" ] && [ -z "$CO_EMAIL" ] && printf '+')" \
+    "$([ -z "$CO_EMAIL" ] && printf email)" >&2
+  printf 'rea: edit .rea/policy.yaml — set name + email, OR set enabled: false.\n' >&2
+  exit 0
+fi
+
+# skip_merge: true → skip when commit source is 'merge'.
+if [ "$SKIP_MERGE" = "true" ] && [ "$COMMIT_SOURCE" = "merge" ]; then
+  exit 0
+fi
+
+# Idempotency: scan the current message file for a Co-Authored-By line
+# that names the same email (case-insensitive). Line-anchored — body
+# prose mentioning the email in passing does NOT count.
+LOWER_EMAIL=$(printf '%s' "$CO_EMAIL" | tr '[:upper:]' '[:lower:]')
+# grep -E with case-insensitive flag; portable across BSD + GNU grep.
+# The pattern: ^co-authored-by: <anything> <EMAIL>[ws]*$
+# Email is regex-escaped via the conservative approach: assume the
+# email passed policy validation (only safe chars per loader regex
+# /^[^\s<>@]+@[^\s<>@]+\.[^\s<>@]+$/), so the only metachars present
+# are `.` and possibly `+` / `-`. We escape `.` and rely on the
+# permissive char set.
+ESCAPED_EMAIL=$(printf '%s' "$LOWER_EMAIL" | sed 's/[.[\*^$(){}+?|]/\\&/g')
+if grep -iE "^co-authored-by:[[:space:]]*[^<]*<${ESCAPED_EMAIL}>[[:space:]]*$" \
+  "$COMMIT_MSG_FILE" >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Build the trailer line. Idempotency above already lower-cased the
+# email for comparison; we ship the trailer with the policy-supplied
+# casing so the user's preferred display name + email render verbatim.
+TRAILER="Co-Authored-By: ${CO_NAME} <${CO_EMAIL}>"
+
+# Find the insert point: at the bottom of the message, after stripping
+# trailing blank/comment lines (git's scissors line `# -- >8 --` and
+# everything below is appended verbatim to preserve git's own view).
+TMP_BODY=$(mktemp "${TMPDIR:-/tmp}/rea-pcm.XXXXXX") || exit 0
+TMP_TAIL=$(mktemp "${TMPDIR:-/tmp}/rea-pcm.XXXXXX") || { rm -f "$TMP_BODY"; exit 0; }
+trap 'rm -f "$TMP_BODY" "$TMP_TAIL"' EXIT INT TERM
+
+# Split the file: body (above the scissors marker) vs. tail (scissors
+# and everything below). Codex round 2 P1: previously used python3
+# unconditionally — on environments where rea CLI is reachable but
+# python3 is missing, the split silently failed and the user's commit
+# body got dropped. awk is universally available on POSIX systems and
+# does the same work.
+SCISSORS='# ------------------------ >8 ------------------------'
+awk -v scissors="$SCISSORS" -v body_dst="$TMP_BODY" -v tail_dst="$TMP_TAIL" '
+  BEGIN { found = 0 }
+  {
+    if (!found && $0 == scissors) found = 1
+    if (found) print > tail_dst
+    else        print > body_dst
+  }
+' "$COMMIT_MSG_FILE"
+
+# Determine whether the body's last non-blank/non-comment line is a
+# real git trailer (`Key: value` where Key matches `[A-Za-z][-A-Za-z0-9]*`)
+# AND part of a multi-line trailer block (not the subject of a single-line
+# conventional commit). Codex round 3 P1: the round-2 fix correctly
+# rejected commit-prose `: ` patterns but still matched the conventional
+# commit subject form `feat: add x` because that line is ALSO
+# `[A-Za-z][-A-Za-z0-9]*: <value>`. The right distinguisher: a real
+# trailer block has at least one preceding non-blank body line; a bare
+# `feat: x` commit is just a subject and always needs a separator.
+LAST_BODY_LINE=$(awk '
+  /^[[:space:]]*#/ { next }
+  /^[[:space:]]*$/ { next }
+  { lastline = $0 }
+  END { if (lastline != "") print lastline }
+' "$TMP_BODY")
+BODY_LINE_COUNT=$(awk '
+  /^[[:space:]]*#/ { next }
+  /^[[:space:]]*$/ { next }
+  { count++ }
+  END { print count + 0 }
+' "$TMP_BODY")
+
+SEPARATOR_NEEDED=1
+if [ -z "$LAST_BODY_LINE" ]; then
+  SEPARATOR_NEEDED=0
+elif [ "$BODY_LINE_COUNT" -gt 1 ] && printf '%s' "$LAST_BODY_LINE" | grep -qE '^[A-Za-z][-A-Za-z0-9]*: '; then
+  SEPARATOR_NEEDED=0
+fi
+
+# Trim trailing blank lines from the body so the trailer lands cleanly
+# (without leaving a triple-newline before it).
+TMP_BODY_TRIMMED=$(mktemp "${TMPDIR:-/tmp}/rea-pcm.XXXXXX") || exit 0
+awk '
+  { lines[NR] = $0; total = NR }
+  END {
+    end = total
+    while (end > 0 && lines[end] ~ /^[[:space:]]*$/) { end-- }
+    for (i = 1; i <= end; i++) print lines[i]
+  }
+' "$TMP_BODY" > "$TMP_BODY_TRIMMED"
+
+# Compose the new file: trimmed body + (optional blank) + trailer + tail.
+{
+  cat "$TMP_BODY_TRIMMED"
+  if [ "$SEPARATOR_NEEDED" -eq 1 ]; then
+    printf '\n'
+  fi
+  printf '%s\n' "$TRAILER"
+  if [ -s "$TMP_TAIL" ]; then
+    cat "$TMP_TAIL"
+  fi
+} > "${COMMIT_MSG_FILE}.rea-tmp" && mv "${COMMIT_MSG_FILE}.rea-tmp" "$COMMIT_MSG_FILE"
+
+rm -f "$TMP_BODY_TRIMMED"
+exit 0