@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/scripts/hooks/pre-send-audit.sh

@@ -1,267 +1,58 @@
 #!/bin/bash
-# Pre-send audit hook — gates outbound communications
-# Called by Claude Code PreToolUse hook before Slack/Gmail/WhatsApp sends.
-# Reads the PreToolUse payload from stdin, screens the outbound CONTENT
-# against the banned-phrase list (policies/communication-style.md), runs a
-# recipient allowlist sanity check, and enforces hourly + daily rate caps.
+# Pre-send audit hook — gates outbound communications.
+# Called by Claude Code PreToolUse hook before Slack/Gmail/WhatsApp/Cohort sends.
 #
 # Usage: pre-send-audit.sh <channel_type>
 #   channel_type: slack | slack-draft | gmail | whatsapp | cohort
 #
 # `cohort` is the PreToolUse channel `maestro global-setup` wires into
 # ~/.claude/settings.json for EVERY mcp__cohort outbound tool (messaging_send,
-# messaging_send_voice_note, email_send, email_draft_send, org_rpc) — the
-# persona gate below (section a2) is what the front-door session relies on to
-# never expose its own machinery to a human (design spec 2026-09-08 §3.6). The
-# same patterns run in-process in lib/comms/send-gate.mjs (screenPersona) for
-# the lanes no hook fronts: `maestro inbox reply`, the daemon's delivery, the
-# adapters. Keep the two lists in sync.
+# messaging_send_voice_note, email_send, email_draft_send, org_rpc).
 #
-# Stdin: Claude Code PreToolUse JSON payload:
-#   { "tool_name": "...", "tool_input": { "text"|"message"|"body"|"bodyText": "...",
-#     "subject": "...", "params": { …an org_rpc body… },
-#     "to"|"recipient"|"channel": "..." }, ... }
+# THIN WRAPPER. Every rule this script used to carry in bash + jq — the banned
+# AI-tell phrases (policies/communication-style.md), the filler openers, the
+# persona gate (PERSONA_PATTERNS and internal session names: <first>-main,
+# state/session/peers.json, MAESTRO_SESSION_NAMES), the recipient allowlist
+# (MAESTRO_SEND_ALLOWLIST) and the hourly/daily caps (MAESTRO_SEND_PER_HOUR /
+# MAESTRO_SEND_PER_DAY, counters under MAESTRO_RUNTIME_DIR) — now runs in
+# lib/comms/send-gate.mjs (`--pre-send-hook`), the module every in-process send
+# path already shares. One implementation means the Claude Code hook and a
+# native engine gate cannot drift. scripts/hooks/pre-send-audit.parity.test.mjs
+# proves the verdicts, reasons and counters match the previous shell script
+# (kept as scripts/hooks/fixtures/pre-send-audit.legacy.sh) over the hook's
+# test corpus.
 #
-# Exit codes:
-#   0 = allowed (stdout message shown to Claude)
-#   2 = blocked / any parse|IO error (stderr reason shown as rejection).
-#       Claude Code blocks the tool call on any non-zero exit, so EVERY
-#       failure path below intentionally fails CLOSED with exit 2.
+# Stdin: the Claude Code PreToolUse JSON payload, passed through untouched.
 #
-# Design note: this script does NOT use `set -e`. A non-zero from a grep
-# (no match) or an arithmetic expansion must not silently abort the script
-# into an implicit success/fail-open state. Instead every gate is checked
-# explicitly and the script ends with `exit 0` only after all checks pass.
+# Exit codes:
+#   0 = allowed (stdout shown to Claude)
+#   2 = blocked (stderr reason shown as the rejection)
+# Claude Code does NOT block on exit 1, so every failure here — no node, no
+# gate module, a crash inside the gate — is mapped to exit 2 (fail closed).
 
 set -uo pipefail
 
-# --- fail-closed helper -----------------------------------------------------
 deny() {
-    # $1 = human-readable reason
     echo "BLOCKED: ${1:-pre-send audit failed}" >&2
     exit 2
 }
 
-CHANNEL_TYPE="${1:-}"
-[ -n "$CHANNEL_TYPE" ] || deny "Channel type required (slack|slack-draft|gmail|whatsapp|cohort)"
-
-# jq is mandatory — without it we cannot inspect content, so refuse to send.
-command -v jq >/dev/null 2>&1 || deny "jq not available — cannot screen outbound content (fail closed)"
-
-# --- read stdin payload -----------------------------------------------------
-TOOL_INPUT=$(cat)
-[ -n "$TOOL_INPUT" ] || deny "Empty hook payload — nothing to audit (fail closed)"
-
-# Validate that the payload is well-formed JSON before doing anything else.
-if ! printf '%s' "$TOOL_INPUT" | jq -e . >/dev/null 2>&1; then
-    deny "Malformed hook payload (not valid JSON) — fail closed"
-fi
-
-# Extract the outbound text. Claude Code wraps the tool args under
-# tool_input; for robustness we also look at the top level. We concatenate
-# every plausible content field so a banned phrase anywhere is caught.
-# `params` is where org_rpc carries an outbound body; `bodyText`/`subject` are
-# the mail-desk (email_draft_send / email_send) content fields.
-CONTENT=$(printf '%s' "$TOOL_INPUT" | jq -r '
-    [ .tool_input // {} , ( .tool_input.params? | if type=="object" then . else {} end ) , . ]
-    | map(
-        ( .text? // empty ),
-        ( .message? // empty ),
-        ( .body? // empty ),
-        ( .bodyText? // empty ),
-        ( .subject? // empty ),
-        ( .content? // empty ),
-        ( .blocks? | if type=="array" or type=="object" then tojson else empty end )
-      )
-    | map(if type=="string" then . else tojson end)
-    | flatten
-    | map(select(. != null and . != ""))
-    | join("\n")
-' 2>/dev/null) || deny "Failed to parse outbound content (fail closed)"
-
-# Extract the recipient for the allowlist sanity check (optional field).
-RECIPIENT=$(printf '%s' "$TOOL_INPUT" | jq -r '
-    ( .tool_input // {} ) as $ti
-    | ( $ti.to? // $ti.recipient? // $ti.channel? // $ti.email? // $ti.thread_ts? // .to? // .recipient? // empty )
-    | if . == null then "" else (. | tostring) end
-' 2>/dev/null) || deny "Failed to parse recipient (fail closed)"
-
-# --- (a) banned-phrase screen ----------------------------------------------
-# Source of truth: policies/communication-style.md (kept in sync manually).
-# Matching is case-insensitive and substring-based. Opener phrases
-# ("Certainly!" / "Absolutely!") are common in legitimate prose mid-sentence,
-# so we anchor those to the start of the content / a line.
-BANNED_SUBSTRINGS=(
-    "I'm here to help"
-    "I am here to help"
-    "Let me know if you need anything else"
-    "I hope this helps"
-    "Feel free to ask if you have any questions"
-    "As an AI"
-    "As a language model"
-    "I should clarify that I am"
-    "Great question!"
-    "Here's a comprehensive overview of"
-    "Here is a comprehensive overview of"
-    "I'd be happy to"
-    "I would be happy to"
-)
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)" || deny "cannot locate the hook directory (fail closed)"
+GATE="$HERE/../../lib/comms/send-gate.mjs"
+[ -f "$GATE" ] || deny "send gate module missing at $GATE (fail closed)"
 
-# Lowercased copy for case-insensitive substring matching.
-CONTENT_LC=$(printf '%s' "$CONTENT" | tr '[:upper:]' '[:lower:]')
-
-for phrase in "${BANNED_SUBSTRINGS[@]}"; do
-    phrase_lc=$(printf '%s' "$phrase" | tr '[:upper:]' '[:lower:]')
-    case "$CONTENT_LC" in
-        *"$phrase_lc"*)
-            deny "Banned AI-tell phrase in outbound message: \"$phrase\" (see policies/communication-style.md)"
-            ;;
-    esac
-done
-
-# Opener-only phrases: block when they begin the message or any line.
-# (Mid-sentence "absolutely" is fine; "Absolutely!" as a line opener is not.)
-if printf '%s' "$CONTENT" | grep -Eiq '(^|[[:cntrl:]])[[:space:]]*(Certainly!|Absolutely!|Great question!)'; then
-    deny "Banned filler opener (Certainly!/Absolutely!/Great question!) — see policies/communication-style.md"
-fi
-
-# --- (a2) persona-leak screen ----------------------------------------------
-# The agent is one persona to the humans it talks to; parallel sessions,
-# sub-sessions, subagents and workflows are internal workings. Outbound text
-# may not name them, and may not name Claude Code / a language model. The
-# denial carries the offending phrase so the session rewrites in its own voice
-# ("my team", "a colleague", "one of my analysts").
-#
-# Patterns are case-insensitive extended regexes. "subagent"/"sub-agent" is
-# blocked only when it is followed by said|reported|session — the bare noun in
-# an internal-process sentence is tolerated, the attribution of speech to a
-# machine part is not.
-PERSONA_PATTERNS=(
-    'claude[[:space:]]+code'
-    'claude[[:space:]]+sessions?'
-    'sub-sessions?'
-    'sub-?agents?[[:space:]]+(said|reported|sessions?)'
-    'workflow[[:space:]]+agents?'
-    'as[[:space:]]+an[[:space:]]+ai\b'
-    'language[[:space:]]+model'
-)
-for pat in "${PERSONA_PATTERNS[@]}"; do
-    hit=$(printf '%s' "$CONTENT" | grep -Eio -- "$pat" 2>/dev/null | head -n 1) || true
-    if [ -n "$hit" ]; then
-        deny "Persona leak in outbound message: \"$hit\" — rewrite in your own voice (my team / a colleague), never name the machinery"
-    fi
-done
-
-# Session names are internal identifiers and must never reach a human — but
-# the rule is BOUNDED, not guessed: `<first>-main` is always internal; any
-# other name is internal only when it is a registered peer
-# ($AGENT_ROOT/state/session/peers.json, written by `maestro session spawn`,
-# an array or {peers:[…]} of {name,…}) or listed in MAESTRO_SESSION_NAMES
-# (comma-separated). A colleague called Marc-Antoine, the slug james-kirkland
-# in a URL or the mailbox ethan-miller@ are ordinary text.
-#
-# The first name resolves, in order, from MAESTRO_AGENT_FIRST,
-# $AGENT_ROOT/config/agent.json (firstName, else the first word of fullName)
-# and the machine pointer ~/.claude/maestro-agent.json (agentName). When none
-# resolves the `<first>-main` check is skipped — the phrase gate above still
-# applies — because a wrong guess would block legitimate text.
-FIRST="${MAESTRO_AGENT_FIRST:-}"
-if [ -z "$FIRST" ]; then
-    for cand in "${AGENT_ROOT:-}/config/agent.json" "${AGENT_DIR:-}/config/agent.json" "$HOME/.claude/maestro-agent.json"; do
-        [ -f "$cand" ] || continue
-        FIRST=$(jq -r '(.firstName // .agentName // .fullName // "") | tostring | split(" ")[0] | ascii_downcase' "$cand" 2>/dev/null) || FIRST=""
-        [ -n "$FIRST" ] && [ "$FIRST" != "null" ] && break
-        FIRST=""
+NODE="$(command -v node 2>/dev/null || true)"
+if [ -z "$NODE" ]; then
+    # launchd and some hook runners carry a bare PATH.
+    for cand in /opt/homebrew/bin/node /usr/local/bin/node "${HOME:-}/.local/bin/node" /usr/bin/node; do
+        if [ -x "$cand" ]; then NODE="$cand"; break; fi
     done
 fi
-FIRST=$(printf '%s' "$FIRST" | tr '[:upper:]' '[:lower:]' | tr -cd 'a-z0-9-')
-
-SESSION_NAMES=()
-[ -n "$FIRST" ] && SESSION_NAMES+=("${FIRST}-main")
-for peers in "${AGENT_ROOT:-}/state/session/peers.json" "${AGENT_DIR:-}/state/session/peers.json"; do
-    [ -f "$peers" ] || continue
-    # A corrupt registry is an empty one: this must never fail the whole send closed.
-    while IFS= read -r pn; do
-        [ -n "$pn" ] && SESSION_NAMES+=("$pn")
-    done < <(jq -r '(if type=="array" then . elif type=="object" then (.peers // []) else [] end) | .[] | select(type=="object") | (.name // empty) | tostring | ascii_downcase' "$peers" 2>/dev/null || true)
-    break
-done
-if [ -n "${MAESTRO_SESSION_NAMES:-}" ]; then
-    IFS=',' read -r -a extra_names <<< "$MAESTRO_SESSION_NAMES"
-    # bash 3.2 (macOS) + set -u: an empty array expands as "unbound" — use the ${a[@]+"${a[@]}"} idiom.
-    for en in ${extra_names[@]+"${extra_names[@]}"}; do
-        en=$(printf '%s' "$en" | tr -d '[:space:]' | tr '[:upper:]' '[:lower:]')
-        [ -n "$en" ] && SESSION_NAMES+=("$en")
-    done
-fi
-for sname in ${SESSION_NAMES[@]+"${SESSION_NAMES[@]}"}; do
-    sname_re=$(printf '%s' "$sname" | sed 's/[.[\*^$()+?{|]/\\&/g')
-    # Word-bounded on [A-Za-z0-9_-]: "alex-main" hits, "alex-mainland" / "alex-main-street" do not.
-    name_hit=$(printf '%s' "$CONTENT" | grep -Eio -- "(^|[^[:alnum:]_-])${sname_re}([^[:alnum:]_-]|$)" 2>/dev/null | head -n 1 | sed -E 's/^[^[:alnum:]_-]//; s/[^[:alnum:]_-]$//') || true
-    if [ -n "$name_hit" ]; then
-        deny "Persona leak in outbound message: \"$name_hit\" is an internal session name — say \"my team\" or \"a colleague\" instead"
-    fi
-done
-
-# --- (b) recipient allowlist sanity check ----------------------------------
-# Only enforced when a recipient is present AND an allowlist file exists.
-# Allowlist file: one entry (channel id, email, handle) per line, '#' comments.
-ALLOWLIST_FILE="${MAESTRO_SEND_ALLOWLIST:-}"
-if [ -n "$RECIPIENT" ] && [ -n "$ALLOWLIST_FILE" ] && [ -f "$ALLOWLIST_FILE" ]; then
-    if ! grep -Eq -- "^[[:space:]]*$(printf '%s' "$RECIPIENT" | sed 's/[.[\*^$()+?{|]/\\&/g')[[:space:]]*(#.*)?$" "$ALLOWLIST_FILE" 2>/dev/null; then
-        deny "Recipient \"$RECIPIENT\" not on send allowlist ($ALLOWLIST_FILE)"
-    fi
-fi
-
-# --- (c) rate caps (hourly + daily) ----------------------------------------
-RUNTIME_DIR="${MAESTRO_RUNTIME_DIR:-$HOME/.maestro/runtime}/audit"
-if ! mkdir -p "$RUNTIME_DIR" 2>/dev/null; then
-    deny "Cannot create audit runtime dir $RUNTIME_DIR (fail closed)"
-fi
-
-COUNTER_FILE="$RUNTIME_DIR/send-counter.tsv"
-TODAY=$(date +%Y-%m-%d)
-HOUR=$(date +%H)
-TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-SEND_LOG="$RUNTIME_DIR/$TODAY-sends.jsonl"
-
-PER_HOUR_CAP="${MAESTRO_SEND_PER_HOUR:-3000}"
-PER_DAY_CAP="${MAESTRO_SEND_PER_DAY:-20000}"
-
-# Counter format (TSV): date<TAB>hour<TAB>hour_count<TAB>day_count
-# Reset whenever the date rolls over; reset the hour bucket when hour rolls.
-PREV_DATE=""; PREV_HOUR=""; HOUR_COUNT=0; DAY_COUNT=0
-if [ -f "$COUNTER_FILE" ]; then
-    IFS=$'\t' read -r PREV_DATE PREV_HOUR HOUR_COUNT DAY_COUNT < "$COUNTER_FILE" 2>/dev/null || true
-fi
-# Sanitise to integers (fail closed to 0 rather than aborting).
-case "$HOUR_COUNT" in (''|*[!0-9]*) HOUR_COUNT=0 ;; esac
-case "$DAY_COUNT"  in (''|*[!0-9]*) DAY_COUNT=0  ;; esac
-
-if [ "$PREV_DATE" != "$TODAY" ]; then
-    DAY_COUNT=0
-    HOUR_COUNT=0
-elif [ "$PREV_HOUR" != "$HOUR" ]; then
-    HOUR_COUNT=0
-fi
-
-if [ "$DAY_COUNT" -ge "$PER_DAY_CAP" ]; then
-    deny "Daily send limit ($PER_DAY_CAP) reached. Sends resume tomorrow."
-fi
-if [ "$HOUR_COUNT" -ge "$PER_HOUR_CAP" ]; then
-    deny "Hourly send limit ($PER_HOUR_CAP) reached. Sends resume next hour."
-fi
-
-# --- commit: increment counters + log allowed send -------------------------
-HOUR_COUNT=$((HOUR_COUNT + 1))
-DAY_COUNT=$((DAY_COUNT + 1))
-if ! printf '%s\t%s\t%s\t%s\n' "$TODAY" "$HOUR" "$HOUR_COUNT" "$DAY_COUNT" > "$COUNTER_FILE" 2>/dev/null; then
-    deny "Cannot write send counter (fail closed)"
-fi
-
-RECIPIENT_JSON=$(printf '%s' "$RECIPIENT" | jq -Rs . 2>/dev/null || printf '""')
-printf '{"timestamp":"%s","channel":"%s","recipient":%s,"status":"allowed"}\n' \
-    "$TIMESTAMP" "$CHANNEL_TYPE" "$RECIPIENT_JSON" >> "$SEND_LOG" 2>/dev/null || true
+[ -n "$NODE" ] || deny "node not available — cannot screen outbound content (fail closed)"
 
-echo "Audit: $CHANNEL_TYPE send screened and logged at $TIMESTAMP (hour: $HOUR_COUNT/$PER_HOUR_CAP, day: $DAY_COUNT/$PER_DAY_CAP)"
-exit 0
+"$NODE" "$GATE" --pre-send-hook "${1:-}"
+rc=$?
+case "$rc" in
+    0|2) exit "$rc" ;;
+    *) echo "BLOCKED: pre-send gate exited $rc (fail closed)" >&2; exit 2 ;;
+esac

package/scripts/hooks/pre-write-yaml-validate.mjs

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+/**
+ * pre-write-yaml-validate.mjs — PreToolUse gate on Write|Edit for agent state YAML.
+ *
+ * Why: the queue files under state/ are the agent's memory of what it owes whom. Three
+ * failure shapes have each cost a seat hours: (1) a Write that replaced a 119-row queue with
+ * the 6 rows the writer had in view (a clobber); (2) an Edit whose old_string matched twice
+ * and landed on the wrong row; (3) a plain scalar carrying an unquoted " #" that parsed
+ * cleanly and silently lost the rest of the value — the only trace is a provenance field
+ * ending on a dangling connector ("... @mention in"). All three pass a syntax check after the
+ * fact; only a gate that sees the WOULD-BE content before the write can refuse them.
+ *
+ * Contract (Claude Code PreToolUse): reads the hook payload on stdin —
+ *   { tool_name, tool_input: { file_path, content | old_string, new_string, replace_all } }
+ * Acts only on paths under state/queues, state/dashboards or state/indexes ending in .yaml
+ * (.yml). Computes the would-be file in memory (Write: `content`; Edit: the on-disk file with
+ * old_string replaced by new_string) and REFUSES — exit 2, a permissionDecision:"deny" JSON on
+ * stdout and the reason on stderr — when:
+ *   - an Edit's old_string is absent from the file, or matches more than once without
+ *     replace_all (the edit would land somewhere the writer did not look at);
+ *   - the result does not parse as YAML (js-yaml, which also rejects duplicate keys);
+ *   - a provenance-keyed value NEW in this write ends on a dangling connector. The delta is
+ *     judged, not the whole file, so a pre-existing truncated row never blocks an unrelated
+ *     write — the PostToolUse backstop (validate-state-yaml.sh) still reports it;
+ *   - the top-level `items:` row count would shrink versus the file on disk (or a top-level
+ *     sequence would get shorter), unless MAESTRO_ALLOW_ROW_SHRINK=1 is set for a deliberate
+ *     archive/prune. Other list keys (dashboard sections, index tables) are regenerated and
+ *     legitimately shrink, so they are not guarded.
+ * Everything else exits 0. Tooling gaps (no stdin, unparseable payload, js-yaml missing)
+ * fail OPEN with a note on stderr: a gate that strands every write on a missing dependency
+ * costs more than the clobber it prevents. Paths are resolved against $CLAUDE_PROJECT_DIR,
+ * else the working directory.
+ *
+ * The evaluation is a pure function (`evaluate`) so it is unit-tested without a harness;
+ * the CLI wrapper at the bottom only does stdin/stdout/exit.
+ *
+ * @module scripts/hooks/pre-write-yaml-validate
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, isAbsolute } from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/** Path segment test: any .yaml under one of the three state-bearing directories. */
+export const SCOPE_RE = /(^|\/)state\/(queues|dashboards|indexes)\/[^/]+\.ya?ml$/;
+
+/** Keys whose values name where a row came from or who owns it — short, so the connector test is close to exact. */
+export const PROVENANCE_KEYS = Object.freeze([
+  "origin", "source", "source_ref", "sourceRef", "raised_by", "counterparty", "channel", "via",
+  "provenance", "escalated_to", "reported_by", "requested_by", "decided_by", "decision_owner",
+  "owner", "reviewer", "notify",
+]);
+const PROV_SET = new Set(PROVENANCE_KEYS);
+
+/** A value ending on one of these is the signature of a comment-eaten scalar. */
+export const CONNECTOR_RE = /\s(in|to|at|on|from|with|the|and|of|for|by)$/i;
+
+/** Is this file_path one the gate cares about? */
+export function inScope(filePath) {
+  if (typeof filePath !== "string" || !filePath) return false;
+  return SCOPE_RE.test(filePath.replace(/\\/g, "/"));
+}
+
+/**
+ * Load js-yaml from wherever the agent has it: next to this script (the agent repo's own
+ * node_modules), the project dir, or the working directory. Returns null when none resolves.
+ */
+export function loadYaml(bases = []) {
+  const candidates = [
+    fileURLToPath(new URL("./", import.meta.url)),
+    ...bases.filter(Boolean),
+    process.cwd(),
+  ];
+  for (const base of candidates) {
+    try {
+      const req = createRequire(pathToFileURL(base.endsWith("/") ? base : `${base}/`));
+      return req("js-yaml");
+    } catch { /* try the next base */ }
+  }
+  return null;
+}
+
+/** Walk a parsed document and collect every provenance-keyed string ending on a connector. */
+export function provenanceHits(doc) {
+  const hits = [];
+  // A nested map (history entry, sub-object) reports the nearest enclosing row id.
+  const walk = (node, inherited) => {
+    if (Array.isArray(node)) { for (const it of node) walk(it, inherited); return; }
+    if (!node || typeof node !== "object") return;
+    const rid = typeof node.id === "string" ? node.id : inherited;
+    for (const [k, v] of Object.entries(node)) {
+      if (typeof v === "string") {
+        if (PROV_SET.has(k) && v.length < 300 && CONNECTOR_RE.test(v.trimEnd())) hits.push({ id: rid, key: k, value: v });
+      } else if (v && typeof v === "object") {
+        walk(v, rid);
+      }
+    }
+  };
+  walk(doc, "?");
+  return hits;
+}
+
+/** Row count the shrink guard protects: a top-level `items:` list, or a top-level sequence. */
+export function guardedRowCount(doc) {
+  if (Array.isArray(doc)) return doc.length;
+  if (doc && typeof doc === "object" && Array.isArray(doc.items)) return doc.items.length;
+  return null;
+}
+
+/** Count non-overlapping occurrences of `needle` in `hay`. */
+function countOccurrences(hay, needle) {
+  if (!needle) return 0;
+  let n = 0;
+  let i = 0;
+  for (;;) {
+    const at = hay.indexOf(needle, i);
+    if (at < 0) return n;
+    n += 1;
+    i = at + needle.length;
+  }
+}
+
+/**
+ * Compute the would-be content for the tool call. Returns { content } or { refuse }.
+ * @param {string} toolName
+ * @param {object} ti tool_input
+ * @param {string|null} current on-disk content (null when the file does not exist)
+ */
+export function wouldBeContent(toolName, ti, current) {
+  if (toolName === "Write") {
+    return { content: typeof ti.content === "string" ? ti.content : "" };
+  }
+  if (toolName === "Edit") {
+    if (current === null) return { refuse: "Edit on a file that does not exist" };
+    const oldStr = ti.old_string;
+    const newStr = typeof ti.new_string === "string" ? ti.new_string : "";
+    if (typeof oldStr !== "string" || oldStr === "") return { refuse: "Edit with an empty old_string" };
+    const n = countOccurrences(current, oldStr);
+    if (n === 0) return { refuse: "old_string is not present in the file on disk — the edit would not land where you looked" };
+    if (n > 1 && !ti.replace_all) return { refuse: `old_string matches ${n} places — anchor it to one row or pass replace_all` };
+    return { content: ti.replace_all ? current.split(oldStr).join(newStr) : current.replace(oldStr, () => newStr) };
+  }
+  if (toolName === "MultiEdit" && Array.isArray(ti.edits)) {
+    let content = current === null ? "" : current;
+    for (const e of ti.edits) {
+      const r = wouldBeContent("Edit", e || {}, content);
+      if (r.refuse) return r;
+      content = r.content;
+    }
+    return { content };
+  }
+  return { content: null };
+}
+
+/**
+ * Pure evaluation of one hook payload.
+ *
+ * @param {object} payload   the hook JSON ({tool_name, tool_input})
+ * @param {object} [o]
+ * @param {string} [o.projectDir]        base for relative file_path (default: cwd)
+ * @param {object} [o.env]               environment (default: process.env)
+ * @param {(p:string)=>string|null} [o.readFile]  test seam; returns null when absent
+ * @param {object} [o.yaml]              js-yaml module (test seam)
+ * @returns {{ decision:"allow"|"deny"|"skip", reason?:string }}
+ */
+export function evaluate(payload, o = {}) {
+  const env = o.env || process.env;
+  const projectDir = o.projectDir || env.CLAUDE_PROJECT_DIR || process.cwd();
+  if (!payload || typeof payload !== "object") return { decision: "skip", reason: "no payload" };
+  const toolName = String(payload.tool_name || "");
+  const ti = payload.tool_input && typeof payload.tool_input === "object" ? payload.tool_input : {};
+  if (!["Write", "Edit", "MultiEdit"].includes(toolName)) return { decision: "skip" };
+  const fp = typeof ti.file_path === "string" ? ti.file_path : "";
+  if (!inScope(fp)) return { decision: "skip" };
+  const abs = isAbsolute(fp) ? fp : resolve(projectDir, fp);
+
+  const readFile = o.readFile || ((p) => (existsSync(p) ? readFileSync(p, "utf-8") : null));
+  let current = null;
+  try { current = readFile(abs); } catch { current = null; }
+
+  const wb = wouldBeContent(toolName, ti, current);
+  if (wb.refuse) return { decision: "deny", reason: `${toolName} ${fp}: ${wb.refuse}` };
+  if (wb.content === null) return { decision: "skip" };
+
+  const yaml = o.yaml || loadYaml([projectDir]);
+  if (!yaml) return { decision: "skip", reason: "js-yaml not resolvable — gate skipped (fail-open)" };
+
+  let next;
+  try {
+    next = yaml.load(wb.content);
+  } catch (err) {
+    const msg = (err && err.message ? err.message : String(err)).split("\n")[0].slice(0, 300);
+    return { decision: "deny", reason: `${toolName} ${fp}: the result would not parse as YAML — ${msg}. Quote scalars carrying ':' or ' #', and never append a second copy of a key.` };
+  }
+
+  let prev;
+  let prevParsed = false;
+  if (current !== null) {
+    try { prev = yaml.load(current); prevParsed = true; } catch { prevParsed = false; }
+  }
+
+  // Provenance truncation — judged on the DELTA so pre-existing rows never block a new write.
+  const before = new Set(prevParsed ? provenanceHits(prev).map((h) => `${h.id}\u0000${h.key}\u0000${h.value}`) : []);
+  const fresh = provenanceHits(next).filter((h) => !before.has(`${h.id}\u0000${h.key}\u0000${h.value}`));
+  if (fresh.length) {
+    const shown = fresh.slice(0, 5).map((h) => `${h.id} ${h.key}: ...${h.value.slice(-60)}`).join("; ");
+    return {
+      decision: "deny",
+      reason: `${toolName} ${fp}: provenance field ends on a dangling connector (an unquoted ' #' silently truncates a plain scalar) — ${shown}. Quote the scalar and write the whole value.`,
+    };
+  }
+
+  // Row-count shrink guard.
+  if (prevParsed && env.MAESTRO_ALLOW_ROW_SHRINK !== "1") {
+    const was = guardedRowCount(prev);
+    const now = guardedRowCount(next);
+    if (was !== null && now !== null && now < was) {
+      return {
+        decision: "deny",
+        reason: `${toolName} ${fp}: top-level items would shrink from ${was} to ${now} rows — a write that drops rows is almost always a clobber of rows you did not have in view. Re-read the file and edit the one row, or set MAESTRO_ALLOW_ROW_SHRINK=1 for a deliberate archive.`,
+      };
+    }
+  }
+
+  return { decision: "allow" };
+}
+
+/** Claude Code hook output for a refusal (exit 2 + this JSON on stdout). */
+export function denyOutput(reason) {
+  return {
+    decision: "block",
+    reason,
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf-8");
+}
+
+async function main() {
+  let payload;
+  try {
+    const raw = await readStdin();
+    if (!raw.trim()) process.exit(0);
+    payload = JSON.parse(raw);
+  } catch (err) {
+    process.stderr.write(`pre-write-yaml-validate: unreadable hook payload (${err && err.message}) — gate skipped\n`);
+    process.exit(0);
+  }
+  let verdict;
+  try {
+    verdict = evaluate(payload);
+  } catch (err) {
+    process.stderr.write(`pre-write-yaml-validate: internal error (${err && err.message}) — gate skipped\n`);
+    process.exit(0);
+  }
+  if (verdict.decision === "deny") {
+    process.stdout.write(`${JSON.stringify(denyOutput(verdict.reason))}\n`);
+    process.stderr.write(`BLOCKED by pre-write-yaml-validate: ${verdict.reason}\n`);
+    process.exit(2);
+  }
+  if (verdict.decision === "skip" && verdict.reason) process.stderr.write(`pre-write-yaml-validate: ${verdict.reason}\n`);
+  process.exit(0);
+}
+
+const invokedDirectly = process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1]);
+if (invokedDirectly) main();