@bookedsolid/rea 0.30.0 → 0.31.0

package/hooks/delegation-advisory.sh

@@ -0,0 +1,162 @@
+#!/bin/bash
+# PostToolUse hook: delegation-advisory.sh
+# 0.31.0+ — delegation-telemetry completion (the *nudge*).
+#
+# Fires AFTER every write-class tool call. The settings.json matcher is
+# `Bash|Edit|Write|MultiEdit|NotebookEdit`. Reads the Claude Code hook
+# payload from stdin, pipes it to `rea hook delegation-advisory`, and
+# exits 0.
+#
+# 0.29.0 shipped the delegation-telemetry *observability* layer
+# (`delegation-capture.sh` + `rea audit specialists`). 0.31.0 closes the
+# loop with the *nudge*: `rea hook delegation-advisory` maintains a
+# per-session write-class counter and, the FIRST time that counter
+# crosses `policy.delegation_advisory.threshold` while the session has
+# recorded zero real delegation signals, prints a one-time stderr
+# advisory ("this session has done a lot of work without delegating to
+# a specialist").
+#
+# # Advisory, never gating
+#
+# This hook ALWAYS exits 0 (under normal operation). The advisory is a
+# nudge — it never blocks a tool call. The ONLY non-zero exit is 2
+# under HALT, to keep the kill-switch contract uniform with the rest of
+# the hook tree.
+#
+# # Synchronous, NOT detached
+#
+# Unlike `delegation-capture.sh` (which backgrounds `rea hook
+# delegation-signal` with `& disown` because the audit write must not
+# block tool dispatch), this hook runs the CLI SYNCHRONOUSLY. The
+# advisory text must reach the operator's stderr before the hook
+# returns — backgrounding it would race the hook's own exit and the
+# message could be lost or interleaved with the next tool call's
+# output. The CLI is cheap on the hot path: below the threshold it
+# only bumps an integer counter file and exits, no audit scan, no
+# roster discovery.
+#
+# # CLI-resolution trust boundary
+#
+# Same 2-tier sandboxed resolution `delegation-capture.sh`,
+# `protected-paths-bash-gate.sh`, and `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)
+# PATH lookup is INTENTIONALLY OMITTED — agent-controlled $PATH would
+# let a forged `rea` binary intercept this hook on every write-class
+# tool call. A realpath sandbox check ensures the resolved CLI lives
+# INSIDE realpath(CLAUDE_PROJECT_DIR) with an ancestor package.json
+# declaring `@bookedsolid/rea`.
+#
+# Exit codes:
+#   0 — always (under normal operation). Disabled-by-policy,
+#       below-threshold, already-fired, just-fired — all exit 0.
+#   2 — HALT active.
+
+set -uo pipefail
+
+# 1. HALT check. Even though this hook is advisory, refusing to run
+#    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 fixed 2-tier sandboxed order.
+#    PATH lookup is omitted on purpose (see header). Other install
+#    shapes silently drop the advisory — matching the bash-gate
+#    posture; the nudge is a convenience, not a security claim.
+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 advisory 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 write-class tool
+  # call and drown legitimate output.
+  exit 0
+fi
+
+# 3. Realpath sandbox check — mirrors delegation-capture.sh §3 and
+#    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 advisory (it 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 tool call.
+  printf 'rea: delegation-advisory skipped (sandbox check: %s)\n' "$sandbox_check" >&2
+  exit 0
+fi
+
+# 4. Read stdin and pipe to the CLI SYNCHRONOUSLY. The advisory must
+#    print before this hook returns — see the "Synchronous" note in
+#    the header. We pass CLAUDE_PROJECT_DIR through explicitly so the
+#    CLI resolves the same REA_ROOT this shim did. The CLI's own exit
+#    code is the hook's exit code: 0 normally, 2 under HALT (the CLI
+#    re-checks HALT itself for defense-in-depth).
+INPUT=$(cat)
+printf '%s' "$INPUT" | "${REA_ARGV[@]}" hook delegation-advisory
+exit $?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/rea",
-  "version": "0.30.0",
+  "version": "0.31.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

@@ -58,3 +58,15 @@ context_protection:
 attribution:
   co_author:
     enabled: false
+# 0.31.0 delegation-advisory nudge — enabled for bst-internal-no-codex.
+# This is a bst-internal variant, so it inherits BST's delegation
+# discipline: the delegation-advisory.sh PostToolUse hook emits a
+# one-time stderr advisory when a session crosses `threshold`
+# write-class tool calls (Bash/Edit/Write/MultiEdit/NotebookEdit)
+# without dispatching a curated specialist. Advisory only — never
+# blocks. `exempt_subagents` omitted → schema default applies
+# (general-purpose, Explore, Plan, output-style-setup,
+# statusline-setup don't count as real delegation).
+delegation_advisory:
+  enabled: true
+  threshold: 25

package/profiles/bst-internal.yaml

@@ -67,3 +67,16 @@ architecture_review:
 attribution:
   co_author:
     enabled: false
+# 0.31.0 delegation-advisory nudge — enabled for bst-internal.
+# The delegation-advisory.sh PostToolUse hook emits a one-time stderr
+# advisory when a session crosses `threshold` write-class tool calls
+# (Bash/Edit/Write/MultiEdit/NotebookEdit) without dispatching a
+# curated specialist. Advisory only — never blocks a tool call. BST's
+# own delegation discipline (CLAUDE.md routes all non-trivial work
+# through rea-orchestrator) is load-bearing, so the nudge ships on.
+# `exempt_subagents` omitted → the schema default applies
+# (general-purpose, Explore, Plan, output-style-setup, statusline-setup
+# don't count as real delegation).
+delegation_advisory:
+  enabled: true
+  threshold: 25

package/profiles/client-engagement.yaml

@@ -35,3 +35,14 @@ context_protection:
 attribution:
   co_author:
     enabled: false
+# 0.31.0 delegation-advisory nudge — disabled for client-engagement.
+# The delegation-advisory.sh PostToolUse hook emits a one-time stderr
+# advisory when a session crosses `threshold` write-class tool calls
+# without dispatching a curated specialist. Client projects vary too
+# much in their delegation conventions to ship the nudge on by
+# default — opt in per-repo via .rea/policy.yaml:
+#   delegation_advisory:
+#     enabled: true
+#     threshold: 25
+delegation_advisory:
+  enabled: false

package/profiles/lit-wc.yaml

@@ -29,3 +29,13 @@ notification_channel: ''
 attribution:
   co_author:
     enabled: false
+# 0.31.0 delegation-advisory nudge — disabled for lit-wc.
+# The delegation-advisory.sh PostToolUse hook emits a one-time stderr
+# advisory when a session crosses `threshold` write-class tool calls
+# without dispatching a curated specialist. External profiles ship
+# `enabled: false` — opt in per-repo via .rea/policy.yaml:
+#   delegation_advisory:
+#     enabled: true
+#     threshold: 25
+delegation_advisory:
+  enabled: false

package/profiles/minimal.yaml

@@ -25,3 +25,14 @@ notification_channel: ''
 attribution:
   co_author:
     enabled: false
+# 0.31.0 delegation-advisory nudge — disabled for minimal.
+# The delegation-advisory.sh PostToolUse hook emits a one-time stderr
+# advisory when a session crosses `threshold` write-class tool calls
+# without dispatching a curated specialist. The minimal profile ships
+# bare defaults — `enabled: false` keeps it opinion-free. Opt in
+# per-repo via .rea/policy.yaml:
+#   delegation_advisory:
+#     enabled: true
+#     threshold: 25
+delegation_advisory:
+  enabled: false

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

@@ -44,3 +44,14 @@ notification_channel: ''
 attribution:
   co_author:
     enabled: false
+# 0.31.0 delegation-advisory nudge — disabled for open-source-no-codex.
+# The delegation-advisory.sh PostToolUse hook emits a one-time stderr
+# advisory when a session crosses `threshold` write-class tool calls
+# without dispatching a curated specialist. "You should delegate more"
+# is an opinion not every OSS team shares, so external profiles ship
+# `enabled: false` — opt in per-repo via .rea/policy.yaml:
+#   delegation_advisory:
+#     enabled: true
+#     threshold: 25
+delegation_advisory:
+  enabled: false

package/profiles/open-source.yaml

@@ -29,3 +29,14 @@ notification_channel: ''
 attribution:
   co_author:
     enabled: false
+# 0.31.0 delegation-advisory nudge — disabled for open-source.
+# The delegation-advisory.sh PostToolUse hook emits a one-time stderr
+# advisory when a session crosses `threshold` write-class tool calls
+# without dispatching a curated specialist. "You should delegate more"
+# is an opinion not every OSS team shares, so external profiles ship
+# `enabled: false` — opt in per-repo via .rea/policy.yaml:
+#   delegation_advisory:
+#     enabled: true
+#     threshold: 25
+delegation_advisory:
+  enabled: false

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

@@ -88,12 +88,31 @@ rea_invoke() {
 ENABLED=$(rea_invoke hook policy-get attribution.co_author.enabled 2>/dev/null)
 REA_RC=$?
 
+# REA_RC interpretation:
+#   0          — rea CLI ran and returned a value (or empty for an
+#                unset key). Use the CLI reads.
+#   non-zero   — rea CLI unreachable (127 sentinel), too old to know
+#                `hook policy-get`, OR the policy YAML is unparseable.
+#                In every one of those cases the policy file ITSELF
+#                may still be valid block-form YAML, so fall back to
+#                the embedded python3 parser. The realistic invalid-
+#                config case — `enabled: true` with an empty name or
+#                email — is caught downstream by the `[ -z "$CO_NAME" ]`
+#                defense-in-depth guard, which exits 0 without
+#                augmenting regardless of which reader produced the
+#                values. (An earlier 0.30.1 revision fail-closed on
+#                non-127 exit codes; codex round 1 showed that
+#                regressed the supported stale-CLI / pre-`pnpm i` flow,
+#                because an old `rea` exits non-zero exactly like an
+#                unparseable policy — the two are indistinguishable by
+#                exit code.)
 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.
+  # rea CLI unreachable / stale / policy unparseable — fall back to the
+  # Python block-form parser.
   CO_AUTHOR_PARSE=$(python3 - "$POLICY_FILE" <<'PY' 2>/dev/null
 import re
 import sys