@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/comms/send-gate.mjs

@@ -47,6 +47,12 @@
  *   any) on stdout. Any unexpected internal error for an EXTERNAL recipient also
  *   exits 1 (fail closed); for an internal recipient it exits 0 (fail open).
  *
+ * Hook form (the Claude Code PreToolUse gate, via scripts/hooks/pre-send-audit.sh)
+ * ---------------------------------------------------------------------------
+ *   <PreToolUse JSON> | node lib/comms/send-gate.mjs --pre-send-hook <channel>
+ *   exit 0 → allow (audit line on stdout);  exit 2 → BLOCK (reason on stderr).
+ *   Never exit 1: Claude Code does not block on it. See runPreSendHook.
+ *
  * @module lib/comms/send-gate
  */
 
@@ -55,8 +61,12 @@
 import {
   readFileSync as nodeReadFileSync,
   existsSync as nodeExistsSync,
+  statSync as nodeStatSync,
+  mkdirSync as nodeMkdirSync,
+  writeSync as nodeWriteSync,
 } from "node:fs";
 import { join } from "node:path";
+import { writeFileAtomic, appendJsonl } from "../fs-atomic.mjs";
 
 /* ─────────────────────────── policy file locations ───────────────────────── */
 
@@ -117,6 +127,51 @@ const PERSONA_FILES = Object.freeze({
   peers: "state/session/peers.json",
 });
 
+/* ──────────────────────── session-scaffold markers ───────────────────────── */
+// A raw model turn must never reach a person. On 5 and 20 September 2026, bodies
+// carrying `<user_message>`, a closing `</thinking>` and the responder's
+// `[auto-reply: "…"]` preamble were posted verbatim into live Cohort channels —
+// in the worst instance a triage conclusion that no reply was warranted,
+// published AS the reply. Root cause was scripts/daemon/responder.mjs: BOTH the
+// success path and the JSON-parse fallback resolve `cliResult.text`, and nothing
+// sat between that and the wire (#64 closes the fallback). Patching the fallback
+// closes one mouth; this closes the throat.
+//
+// Scope: the SCAFFOLD ONLY — wrappers a harness emits around a turn. Deliberately
+// not a general "looks like XML" test, because org bodies legitimately carry angle
+// brackets (diffs, HTML fragments, Slack's `<@U…>` mention syntax, `NAV < 1bp`).
+//
+// Matching is case-insensitive over the body with INLINE code spans REMOVED
+// (see stripCodeSpans). A marker inside inline backticks is a citation, not a
+// leak, and the incident thread that diagnosed this defect quoted every one of
+// these in backticks. Without that carve-out the first thing this rule blocks
+// is its own post-mortem, and the second is somebody switching the gate off to
+// send it. Fenced (```) blocks are NOT exempt — a fenced block is also how a
+// seat pastes a templated message or quotes a draft for review, so carving it
+// out would reopen the exact leak this rule exists to stop.
+//
+// ONE list, shared by both screening paths in this module (`screenOutbound` for
+// the in-process lanes, `screenHookPayload` for the PreToolUse hook). The ported
+// hook rules are duplicated as HOOK_* constants because they owe shell parity;
+// this rule is new, owes no parity, and must not be duplicated.
+export const SCAFFOLD_MARKERS = Object.freeze([
+  "<user_message>",
+  "</user_message>",
+  "<thinking>",
+  "</thinking>",
+  "<system-reminder>",
+  "</system-reminder>",
+  "<function_calls>",
+  "</function_calls>",
+  "<function_results>",
+  "</function_results>",
+  "<invoke name=",
+  "</invoke>",
+  "[auto-reply:",
+  "<<<UNTRUSTED_",
+  "<END_UNTRUSTED_",
+]);
+
 /* ────────────────────────── recipient classification ─────────────────────── */
 
 /**
@@ -365,6 +420,62 @@ function personaContext(fs, agentRoot, { agentFirst, sessionNames }) {
   return { first, sessionNames: names };
 }
 
+/**
+ * Remove INLINE code spans only, so a deliberately quoted marker (`` `<thinking>` ``)
+ * is not read as a leaked one. Replaced with a space rather than deleted, so
+ * stripping can never splice two halves of a marker together across the removed
+ * span (`` `<user_` `` followed by `` `message>` `` must not become
+ * `<user_message>`).
+ *
+ * Deliberately does NOT strip fenced (```) blocks: a fenced block isn't
+ * obviously a citation of the leak bug — it's also how a seat pastes a
+ * templated message or quotes a draft for review — so exempting it from the
+ * screen would carve out exactly the failure this rule exists to stop. Quote a
+ * marker deliberately with inline backticks; a marker inside a fenced block
+ * still blocks (pre-merge review on #66, Ravi Patel).
+ *
+ * Bounded to a 1-2 backtick run (single line, no fence). The run must not be
+ * adjacent to a further backtick on either side, so this can never partially
+ * consume a ``` fence delimiter (matching 2 of its 3 backticks and leaving a
+ * dangling one) — inside a fence, no width starts or closes a match, so the
+ * fence content is left untouched for screenScaffold to see.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function stripCodeSpans(text) {
+  return String(text || "").replace(/(?<!`)(`{1,2})(?!`)[^\n`]*?(?<!`)\1(?!`)/g, " ");
+}
+
+/**
+ * (a0) Session-scaffold screen. Pure; no IO. Returns a block reason naming the
+ * marker, or null.
+ *
+ * This blocks for INTERNAL recipients too, and that is the point: every recorded
+ * leak went to an internal Cohort channel, and those channels have human members.
+ * There is no recipient class for which publishing a raw model turn is
+ * acceptable — so unlike the policy-file layers this screen has no fail posture
+ * to resolve. It reads no file, so it cannot fail open.
+ *
+ * @param {string} text
+ * @returns {string|null}
+ */
+export function screenScaffold(text) {
+  const t = typeof text === "string" ? text : "";
+  if (!t) return null;
+  const lc = stripCodeSpans(t).toLowerCase();
+  for (const marker of SCAFFOLD_MARKERS) {
+    if (lc.includes(marker.toLowerCase())) {
+      return (
+        `session-scaffold marker "${marker}" in the outbound body — a raw model turn ` +
+        `must never reach a person; send the reply you meant to write. ` +
+        `(To quote a marker deliberately, put it in backticks.)`
+      );
+    }
+  }
+  return null;
+}
+
 /**
  * (b) AI-disclosure screen. Resolves the active posture for the recipient's
  * jurisdiction from ai-disclosure.yaml and enforces two things:
@@ -586,6 +697,14 @@ export async function screenOutbound({
     //     file is unreadable we still apply the embedded constant list (the SoT
     //     is mirrored here), so a missing style file does NOT open the AI-tell
     //     gate; it only loses the ability to refresh the list.
+    // (a0) Session scaffold — FIRST, ahead of every other layer. A dumped model
+    //      turn very often also trips the banned-phrase list, and if that fires
+    //      first the operator reads "banned AI-tell phrase" and goes off to fix
+    //      the wording of a message that should never have had a body at all.
+    //      The most severe diagnosis has to be the one that gets reported.
+    const scaffoldReason = screenScaffold(text);
+    if (scaffoldReason) return blocked(scaffoldReason);
+
     const bannedReason = screenBannedPhrases(text);
     if (bannedReason) return blocked(bannedReason);
 
@@ -660,6 +779,443 @@ export async function screenOutbound({
   }
 }
 
+/* ──────────────────── pre-send audit hook (ported from shell) ─────────────── */
+//
+// scripts/hooks/pre-send-audit.sh used to carry these rules in bash + jq + grep;
+// it is now a thin wrapper that runs `node lib/comms/send-gate.mjs
+// --pre-send-hook <channel>`. The rules live here so the Claude Code PreToolUse
+// hook and a native engine gate (lib/engine, W2) share one implementation — no
+// window in which outbound sends are gated by a copy that drifted.
+//
+// The port reproduces the shell verdicts, reasons and side effects exactly
+// over the hook's test corpus (scripts/hooks/pre-send-audit.parity.test.mjs
+// runs every case against the frozen shell copy and this module). Where bash/jq
+// semantics were an accident rather than a rule, the port is deliberately no
+// LESS strict, and says so inline: a multi-document JSON payload is malformed,
+// whitespace inside a phrase includes non-ASCII spaces, a recipient with an
+// embedded newline can never match an allowlist line.
+//
+// Split into pure verdict functions (screenHookPayload, applyHookRateCaps, and
+// the extract/resolve helpers under them) and one effect edge (runPreSendHook)
+// that reads identity/allowlist/counter files, writes the counter and the send
+// log, and takes `now` as a parameter.
+
+/** Banned substrings in the hook's order: the in-process list plus "Great question!" anywhere. */
+export const HOOK_BANNED_SUBSTRINGS = Object.freeze([
+  ...BANNED_SUBSTRINGS.slice(0, 8),
+  "Great question!",
+  ...BANNED_SUBSTRINGS.slice(8),
+]);
+
+/**
+ * The persona patterns, compiled the way the hook matched them: grep is
+ * line-bounded, so whitespace inside a phrase never spans a newline.
+ */
+export const HOOK_PERSONA_PATTERNS = Object.freeze(
+  PERSONA_PATTERNS.map((re) => new RegExp(re.source.replace(/\\s/g, "[^\\S\\n]"), re.flags)),
+);
+
+/** Filler openers at the start of any line, or after a control char (grep's [[:cntrl:]]). */
+const HOOK_OPENER_RE = /(^|[\x00-\x1f\x7f])[^\S\n]*(certainly!|absolutely!|great question!)/im;
+
+const HOOK_CHANNEL_REQUIRED = "Channel type required (slack|slack-draft|gmail|whatsapp|cohort)";
+
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+/** jq's `//`: only null and false (and a missing key) are "absent". */
+function jqPresent(v) {
+  return v !== undefined && v !== null && v !== false;
+}
+
+/** jq `tostring` / `tojson` for the values a payload can carry. */
+function jqString(v) {
+  return typeof v === "string" ? v : JSON.stringify(v);
+}
+
+/** `tr '[:upper:]' '[:lower:]'` / jq `ascii_downcase`: ASCII letters only. */
+function asciiLower(s) {
+  return String(s).replace(/[A-Z]/g, (c) => c.toLowerCase());
+}
+
+/** Command substitution drops NUL bytes and strips trailing newlines. */
+function shellCaptured(s) {
+  return String(s).replace(/\0/g, "").replace(/\n+$/, "");
+}
+
+/**
+ * The outbound text of a PreToolUse payload, as the hook concatenated it: from
+ * `tool_input`, then `tool_input.params` (org_rpc), then the top level, the
+ * fields text/message/body/bodyText/subject/content (non-strings as JSON) and
+ * `blocks` as JSON, empties dropped, joined by newlines. Pure.
+ *
+ * @param {unknown} payload parsed JSON
+ * @returns {{ok:true, text:string}|{ok:false}} ok:false where jq errored (a non-object payload)
+ */
+export function extractHookContent(payload) {
+  if (!isPlainObject(payload)) return { ok: false };
+  const ti = payload.tool_input;
+  const sources = [jqPresent(ti) ? ti : {}, isPlainObject(ti) && isPlainObject(ti.params) ? ti.params : {}, payload];
+  const parts = [];
+  for (const src of sources) {
+    if (!isPlainObject(src)) continue; // `.text?` on a non-object yields nothing
+    for (const k of ["text", "message", "body", "bodyText", "subject", "content"]) {
+      if (jqPresent(src[k])) parts.push(jqString(src[k]));
+    }
+    const b = src.blocks;
+    if (b !== null && typeof b === "object") parts.push(JSON.stringify(b));
+  }
+  return { ok: true, text: shellCaptured(parts.filter((p) => p !== "").join("\n")) };
+}
+
+/**
+ * The recipient the allowlist is checked against: tool_input.to / recipient /
+ * channel / email / thread_ts, then top-level to / recipient; non-strings as
+ * JSON; "" when none. Pure.
+ * @param {object} payload parsed JSON object
+ * @returns {string}
+ */
+export function extractHookRecipient(payload) {
+  const ti = payload && payload.tool_input;
+  const t = jqPresent(ti) ? ti : {};
+  const pick = (o, k) => (isPlainObject(o) ? o[k] : undefined);
+  const chain = [pick(t, "to"), pick(t, "recipient"), pick(t, "channel"), pick(t, "email"), pick(t, "thread_ts"), pick(payload, "to"), pick(payload, "recipient")];
+  const v = chain.find(jqPresent);
+  return v === undefined ? "" : shellCaptured(jqString(v));
+}
+
+/**
+ * The agent's first name for the `<first>-main` check, resolved as the hook
+ * did: MAESTRO_AGENT_FIRST, else the first candidate file (AGENT_ROOT and
+ * AGENT_DIR config/agent.json, ~/.claude/maestro-agent.json) whose
+ * firstName / agentName / fullName yields a first word; lower-cased and
+ * reduced to [a-z0-9-]. Pure over the file TEXTS (null = not a readable file).
+ *
+ * @param {{envFirst?:string, candidates:Array<string|null>}} o
+ * @returns {string} "" when none resolves (the name check is then skipped)
+ */
+export function hookFirstName({ envFirst, candidates = [] }) {
+  let first = typeof envFirst === "string" ? envFirst : "";
+  if (!first) {
+    for (const text of candidates) {
+      if (text == null) continue;
+      let raw = "";
+      try {
+        const doc = JSON.parse(text);
+        if (isPlainObject(doc)) {
+          const v = [doc.firstName, doc.agentName, doc.fullName].find(jqPresent);
+          const s = v === undefined ? "" : jqString(v);
+          // jq: `"" | split(" ")[0]` is null and ascii_downcase then errors → "".
+          raw = s === "" ? "" : asciiLower(s.split(" ")[0]);
+        }
+      } catch { raw = ""; /* unparseable agent file: jq failed, try the next candidate */ }
+      raw = shellCaptured(raw);
+      if (raw && raw !== "null") { first = raw; break; }
+    }
+  }
+  return asciiLower(first).replace(/[^a-z0-9-]/g, "");
+}
+
+/**
+ * Internal session names: `<first>-main`, the registered peers (peers.json as
+ * an array or {peers:[…]}), then MAESTRO_SESSION_NAMES (comma-separated, first
+ * line). A corrupt registry is an empty one. Pure over the registry TEXT.
+ *
+ * @param {{first?:string, peersText?:string|null, envNames?:string}} o
+ * @returns {string[]}
+ */
+export function hookSessionNames({ first, peersText, envNames }) {
+  const names = [];
+  if (first) names.push(`${first}-main`);
+  if (peersText != null) {
+    let doc;
+    try { doc = JSON.parse(peersText); } catch { doc = undefined; /* corrupt registry = empty */ }
+    let list = [];
+    if (Array.isArray(doc)) list = doc;
+    else if (isPlainObject(doc)) list = jqPresent(doc.peers) ? doc.peers : [];
+    const items = Array.isArray(list) ? list : isPlainObject(list) ? Object.values(list) : [];
+    for (const it of items) {
+      if (!isPlainObject(it) || !jqPresent(it.name)) continue;
+      // `while IFS= read -r pn`: one name per output line, whitespace KEPT
+      // (IFS is empty, so read trims nothing); empty lines are skipped.
+      for (const line of asciiLower(jqString(it.name)).split("\n")) {
+        if (line) names.push(line);
+      }
+    }
+  }
+  if (typeof envNames === "string" && envNames) {
+    for (const part of envNames.split("\n")[0].split(",")) {
+      const n = asciiLower(part.replace(/[ \t\n\v\f\r]/g, ""));
+      if (n) names.push(n);
+    }
+  }
+  return names;
+}
+
+/** Word-bounded (on [A-Za-z0-9_-]) session-name hit, trimmed of its boundary chars. */
+function hookSessionNameHit(text, name) {
+  const re = new RegExp(`(^|[^A-Za-z0-9_\\n-])${escapeRe(name)}([^A-Za-z0-9_\\n-]|$)`, "im");
+  const m = re.exec(text);
+  if (!m) return null;
+  return m[0].replace(/^[^A-Za-z0-9_-]/, "").replace(/[^A-Za-z0-9_-]$/, "");
+}
+
+/**
+ * Is `recipient` a line of the allowlist (surrounding whitespace and a
+ * trailing `# comment` allowed, case-sensitive)? Pure.
+ * @param {string} recipient non-empty
+ * @param {string} allowlistText
+ */
+export function hookAllowlistMatch(recipient, allowlistText) {
+  const re = new RegExp(`^[ \\t\\v\\f\\r]*${escapeRe(recipient)}[ \\t\\v\\f\\r]*(#[^\\n]*)?$`);
+  return String(allowlistText).split("\n").some((line) => re.test(line));
+}
+
+/**
+ * Phase 1 of the hook verdict: payload shape, banned phrases, openers, persona
+ * patterns, internal session names, recipient allowlist. Pure.
+ *
+ * @param {object} o
+ * @param {string} o.channel   the hook's channel argument
+ * @param {string} o.stdin     the raw PreToolUse payload
+ * @param {string[]} [o.sessionNames] from hookSessionNames
+ * @param {null|{path:string, text:string|null}} [o.allowlist] null = not enforced; text null = unreadable
+ * @returns {{allow:true, recipient:string}|{allow:false, reason:string}}
+ */
+export function screenHookPayload({ channel, stdin, sessionNames = [], allowlist = null }) {
+  const deny = (reason) => ({ allow: false, reason });
+  if (!channel) return deny(HOOK_CHANNEL_REQUIRED);
+  const raw = shellCaptured(stdin == null ? "" : stdin);
+  if (!raw) return deny("Empty hook payload — nothing to audit (fail closed)");
+  let payload;
+  // Stricter than `jq -e .`: a stream of several JSON documents is malformed.
+  try { payload = JSON.parse(raw); } catch { return deny("Malformed hook payload (not valid JSON) — fail closed"); }
+  if (payload === null || payload === false) return deny("Malformed hook payload (not valid JSON) — fail closed");
+  const content = extractHookContent(payload);
+  if (!content.ok) return deny("Failed to parse outbound content (fail closed)");
+  const text = content.text;
+  const recipient = extractHookRecipient(payload);
+
+  // (a0) Session scaffold — the same shared rule the in-process gate applies,
+  // ahead of the ported rules for the same reason it runs first there. This is
+  // NOT a ported rule: the frozen shell had no counterpart, so it is outside the
+  // parity contract by construction (pre-send-audit.parity.test.mjs says so).
+  const scaffoldReason = screenScaffold(text);
+  if (scaffoldReason) return deny(`Session-scaffold marker in outbound message: ${scaffoldReason}`);
+
+  const lc = text.toLowerCase();
+  for (const phrase of HOOK_BANNED_SUBSTRINGS) {
+    if (lc.includes(phrase.toLowerCase())) {
+      return deny(`Banned AI-tell phrase in outbound message: "${phrase}" (see policies/communication-style.md)`);
+    }
+  }
+  if (HOOK_OPENER_RE.test(text)) {
+    return deny("Banned filler opener (Certainly!/Absolutely!/Great question!) — see policies/communication-style.md");
+  }
+  for (const re of HOOK_PERSONA_PATTERNS) {
+    const m = re.exec(text);
+    if (m) return deny(`Persona leak in outbound message: "${m[0]}" — rewrite in your own voice (my team / a colleague), never name the machinery`);
+  }
+  for (const name of sessionNames) {
+    const hit = hookSessionNameHit(text, name);
+    if (hit) return deny(`Persona leak in outbound message: "${hit}" is an internal session name — say "my team" or "a colleague" instead`);
+  }
+  if (recipient && allowlist) {
+    if (allowlist.text == null || !hookAllowlistMatch(recipient, allowlist.text)) {
+      return deny(`Recipient "${recipient}" not on send allowlist (${allowlist.path})`);
+    }
+  }
+  return { allow: true, recipient };
+}
+
+/** bash `[ n -ge cap ]` integer syntax; anything else makes the test fail (no cap). */
+function bashInt(v) {
+  const s = String(v);
+  return /^[ \t\n\v\f\r]*[+-]?[0-9]+[ \t\n\v\f\r]*$/.test(s) ? parseInt(s.trim(), 10) : null;
+}
+
+/**
+ * Phase 2: the hourly + daily send caps over the counter file
+ * (`date<TAB>hour<TAB>hour_count<TAB>day_count`). Pure: `today`/`hour` are the
+ * caller's local-clock strings.
+ *
+ * @param {object} o
+ * @param {string|null} o.counterText  counter file contents, null when absent
+ * @param {string} o.today  YYYY-MM-DD (local)
+ * @param {string} o.hour   HH (local)
+ * @param {string} o.perHourCap raw cap (MAESTRO_SEND_PER_HOUR, default "3000")
+ * @param {string} o.perDayCap  raw cap (MAESTRO_SEND_PER_DAY, default "20000")
+ * @returns {{allow:false, reason:string}|{allow:true, counterLine:string, hourCount:number, dayCount:number}}
+ */
+export function applyHookRateCaps({ counterText, today, hour, perHourCap, perDayCap }) {
+  let prevDate = "";
+  let prevHour = "";
+  let hourCount = "0";
+  let dayCount = "0";
+  if (counterText != null) {
+    // `IFS=$'\t' read -r a b c d`: first line, runs of tabs are one separator,
+    // the last variable takes the rest of the line.
+    let rest = String(counterText).split("\n")[0].replace(/^\t+/, "").replace(/\t+$/, "");
+    const take = () => {
+      const i = rest.indexOf("\t");
+      if (i < 0) { const v = rest; rest = ""; return v; }
+      const v = rest.slice(0, i);
+      rest = rest.slice(i).replace(/^\t+/, "");
+      return v;
+    };
+    prevDate = take();
+    prevHour = take();
+    hourCount = take();
+    dayCount = rest;
+  }
+  let hc = /^[0-9]+$/.test(hourCount) ? parseInt(hourCount, 10) : 0;
+  let dc = /^[0-9]+$/.test(dayCount) ? parseInt(dayCount, 10) : 0;
+  if (prevDate !== today) { dc = 0; hc = 0; } else if (prevHour !== hour) { hc = 0; }
+
+  const dayCap = bashInt(perDayCap);
+  const hourCap = bashInt(perHourCap);
+  if (dayCap !== null && dc >= dayCap) return { allow: false, reason: `Daily send limit (${perDayCap}) reached. Sends resume tomorrow.` };
+  if (hourCap !== null && hc >= hourCap) return { allow: false, reason: `Hourly send limit (${perHourCap}) reached. Sends resume next hour.` };
+  hc += 1;
+  dc += 1;
+  return { allow: true, counterLine: `${today}\t${hour}\t${hc}\t${dc}\n`, hourCount: hc, dayCount: dc };
+}
+
+const pad2 = (n) => String(n).padStart(2, "0");
+
+/**
+ * The effect edge of the pre-send hook: resolve identity, peers, allowlist and
+ * counter from disk and env, run the two pure phases, commit the counter and
+ * append the send log. Synchronous; never throws for an expected failure —
+ * every denial is `{code:2}` with the reason on stderr, exactly as the shell.
+ *
+ * @param {object} o
+ * @param {string} o.channel
+ * @param {string} o.stdin
+ * @param {object} [o.env=process.env]
+ * @param {Date} [o.now=new Date()]
+ * @param {object} [o.fs] injectable {readFileSync, statSync, mkdirSync, writeFileAtomic, appendJsonl}
+ * @returns {{code:0|2, stdout:string, stderr:string}}
+ */
+export function runPreSendHook(o = {}) {
+  const prepared = preparePreSendHook(o);
+  return prepared.ok ? prepared.commit() : prepared.result;
+}
+
+/**
+ * The pre-send hook in two steps, for a caller that must settle other checks
+ * between the verdict and the send (the Cohort Engine's tool guard): `prepare`
+ * screens the payload and checks the caps WITHOUT writing anything; `commit`
+ * re-reads the counter, re-applies the caps, writes the counter and appends
+ * the send log — exactly what `runPreSendHook` does after the screen. Calling
+ * `commit` only for the send that actually goes out keeps refused calls off
+ * the hourly and daily caps.
+ *
+ * @param {Parameters<typeof runPreSendHook>[0]} o
+ * @returns {{ok:false, result:{code:2, stdout:string, stderr:string}} | {ok:true, commit:() => {code:0|2, stdout:string, stderr:string}}}
+ */
+export function preparePreSendHook({ channel, stdin, env = process.env, now = new Date(), fs: injected = {} } = {}) {
+  const fsx = {
+    readFileSync: injected.readFileSync || nodeReadFileSync,
+    statSync: injected.statSync || nodeStatSync,
+    mkdirSync: injected.mkdirSync || nodeMkdirSync,
+    writeFileAtomic: injected.writeFileAtomic || writeFileAtomic,
+    appendJsonl: injected.appendJsonl || appendJsonl,
+  };
+  const deny = (reason) => ({ code: 2, stdout: "", stderr: `BLOCKED: ${reason}\n` });
+  const e = env || {};
+  const isFile = (p) => { try { return fsx.statSync(p).isFile(); } catch { return false; } };
+  const readIfFile = (p) => {
+    if (!isFile(p)) return null;
+    try { return fsx.readFileSync(p, "utf-8"); } catch { return null; /* unreadable: jq/grep would have failed on it */ }
+  };
+  // `${VAR:-}`: an unset or empty variable is the empty string, so the path is
+  // built as the shell built it (e.g. "/config/agent.json" when AGENT_ROOT is unset).
+  const v = (k) => (typeof e[k] === "string" ? e[k] : "");
+
+  const refuse = (reason) => ({ ok: false, result: deny(reason) });
+  if (!channel) return refuse(HOOK_CHANNEL_REQUIRED);
+
+  const first = hookFirstName({
+    envFirst: v("MAESTRO_AGENT_FIRST"),
+    candidates: [`${v("AGENT_ROOT")}/config/agent.json`, `${v("AGENT_DIR")}/config/agent.json`, `${v("HOME")}/.claude/maestro-agent.json`].map(readIfFile),
+  });
+  let peersText = null;
+  for (const p of [`${v("AGENT_ROOT")}/state/session/peers.json`, `${v("AGENT_DIR")}/state/session/peers.json`]) {
+    if (!isFile(p)) continue;
+    peersText = readIfFile(p);
+    break;
+  }
+  const sessionNames = hookSessionNames({ first, peersText, envNames: v("MAESTRO_SESSION_NAMES") });
+  const allowPath = v("MAESTRO_SEND_ALLOWLIST");
+  const allowlist = allowPath && isFile(allowPath) ? { path: allowPath, text: readIfFile(allowPath) } : null;
+
+  const screened = screenHookPayload({ channel, stdin, sessionNames, allowlist });
+  if (!screened.allow) return refuse(screened.reason);
+
+  const runtimeDir = `${v("MAESTRO_RUNTIME_DIR") || `${v("HOME")}/.maestro/runtime`}/audit`;
+  const counterFile = `${runtimeDir}/send-counter.tsv`;
+  const today = `${now.getFullYear()}-${pad2(now.getMonth() + 1)}-${pad2(now.getDate())}`;
+  const hour = pad2(now.getHours());
+  const timestamp = now.toISOString().replace(/\.\d{3}Z$/, "Z");
+  const perHourCap = v("MAESTRO_SEND_PER_HOUR") || "3000";
+  const perDayCap = v("MAESTRO_SEND_PER_DAY") || "20000";
+
+  // A send the caps already refuse is refused here, before anything is written.
+  const preview = applyHookRateCaps({ counterText: readIfFile(counterFile), today, hour, perHourCap, perDayCap });
+  if (!preview.allow) return refuse(preview.reason);
+
+  return {
+    ok: true,
+    commit() {
+      try {
+        fsx.mkdirSync(runtimeDir, { recursive: true });
+      } catch {
+        return deny(`Cannot create audit runtime dir ${runtimeDir} (fail closed)`);
+      }
+      const caps = applyHookRateCaps({ counterText: readIfFile(counterFile), today, hour, perHourCap, perDayCap });
+      if (!caps.allow) return deny(caps.reason);
+      try {
+        fsx.writeFileAtomic(counterFile, caps.counterLine);
+      } catch {
+        return deny("Cannot write send counter (fail closed)");
+      }
+      // Best effort, as before: the send is already counted.
+      fsx.appendJsonl(`${runtimeDir}/${today}-sends.jsonl`, { timestamp, channel, recipient: screened.recipient, status: "allowed" });
+
+      return {
+        code: 0,
+        stdout: `Audit: ${channel} send screened and logged at ${timestamp} (hour: ${caps.hourCount}/${perHourCap}, day: ${caps.dayCount}/${perDayCap})\n`,
+        stderr: "",
+      };
+    },
+  };
+}
+
+/**
+ * CLI form of the hook (`--pre-send-hook <channel>`, payload on stdin). Every
+ * outcome is exit 0 or 2: Claude Code does not block on exit 1, so an internal
+ * error here is a denial, never a pass. Output goes through writeSync so a
+ * piped stdout/stderr is flushed before the process ends.
+ */
+function mainPreSendHook(argv) {
+  let res;
+  try {
+    const channel = argv[1] || "";
+    res = channel
+      ? runPreSendHook({ channel, stdin: readStdin(), env: process.env, now: new Date() })
+      : { code: 2, stdout: "", stderr: `BLOCKED: ${HOOK_CHANNEL_REQUIRED}\n` };
+  } catch (err) {
+    res = { code: 2, stdout: "", stderr: `BLOCKED: pre-send gate internal error — ${err && err.message ? err.message : String(err)} (fail closed)\n` };
+  }
+  try {
+    if (res.stdout) nodeWriteSync(1, res.stdout);
+    if (res.stderr) nodeWriteSync(2, res.stderr);
+  } catch { /* an unwritable stdio cannot change the verdict carried by the exit code */ }
+  process.exitCode = res.code;
+}
+
 /* ─────────────────────────────────── CLI ─────────────────────────────────── */
 
 /**
@@ -742,5 +1298,7 @@ async function main(argv) {
 const invokedDirectly =
   process.argv[1] && process.argv[1].endsWith("send-gate.mjs");
 if (invokedDirectly) {
-  main(process.argv.slice(2));
+  const cliArgs = process.argv.slice(2);
+  if (cliArgs[0] === "--pre-send-hook") mainPreSendHook(cliArgs);
+  else main(cliArgs);
 }