@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/engine/hooks.mjs

@@ -0,0 +1,713 @@
+/**
+ * lib/engine/hooks.mjs — lifecycle hooks and in-process gates.
+ *
+ * Command hooks (settings.json `hooks`, every settings layer):
+ *
+ *   "hooks": { "PreToolUse": [ { "matcher": "Bash|Write",
+ *                                "hooks": [ { "type": "command", "command": "…", "timeout": 30 } ] } ] }
+ *
+ * Events: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop,
+ * SubagentStop, PreCompact, Notification. The matcher is a regular expression
+ * that must match the WHOLE target (the tool name for tool events; the source
+ * for SessionStart, the trigger for PreCompact, the notification type for
+ * Notification); "" or "*" matches everything; a matcher that is not a valid
+ * expression matches only itself. Matching hooks run in parallel; identical
+ * commands run once.
+ *
+ * Each command runs through /bin/sh in the working directory, with the run's
+ * environment minus every credential-shaped variable, the org credential
+ * included (context/child-env.mjs, CF-22) — a hook object's own
+ * `"inheritEnv": ["NAME", …]` passes the names it lists (not from project or
+ * local settings, for a credential) — and a JSON object on stdin:
+ *   { session_id, transcript_path, cwd, hook_event_name, permission_mode,
+ *     tool_name, tool_input, tool_use_id, tool_response, prompt, source,
+ *     stop_hook_active, trigger, message, … }   (the fields the event has)
+ *
+ * Exit status:
+ *   0      continue. Stdout that is a JSON object may carry
+ *          { continue:false, stopReason } — end the run;
+ *          { decision:"block"|"approve", reason };
+ *          { hookSpecificOutput: { permissionDecision:"allow"|"deny"|"ask",
+ *            permissionDecisionReason, updatedInput, additionalContext } }.
+ *          Plain stdout from SessionStart / UserPromptSubmit is context.
+ *   2      BLOCK, with stderr as the reason: PreToolUse refuses the call and
+ *          the model reads why; UserPromptSubmit refuses the prompt;
+ *          Stop / SubagentStop make the run continue with the reason as the
+ *          next user message; PostToolUse shows the reason to the model;
+ *          PreCompact limits that compaction to clearing old tool results
+ *          (no summary). For SessionStart and Notification it is reported only.
+ *   other  a non-blocking error, logged; the run goes on.
+ * A hook that exceeds its timeout (default 60 s; `timeout` is in seconds) is
+ * killed — its process group and every process it started that the tracker
+ * recorded, setsid descendants included (CF-119, `runCommandHook`) — and
+ * treated as a non-blocking error. The environment scrub also withholds a
+ * variable whose value looks like a credential (CF-118). Anything a hook contributes to
+ * the model's context is capped at 10,000 characters.
+ *
+ * In-process gates run BEFORE any command hook, for every PreToolUse, in every
+ * permission mode, whether or not a settings file exists. A gate that throws
+ * denies (fail closed). A gate's verdict may carry a `commit` — a side effect
+ * (the send counter) the guard runs only once the call is finally allowed,
+ * just before the tool runs; a commit that fails refuses the call.
+ * `createDefaultGates` registers the outbound send gate (lib/comms/send-gate.mjs,
+ * the same verdict the pre-send-audit hook gives) for the five outbound tool
+ * names on ANY MCP server: which server is the org server is not something the
+ * config key or launcher reliably says, and a clean message costs nothing.
+ *
+ * The verdict logic (`matcherMatches`, `selectHooks`, `interpretHookRun`,
+ * `combinePreToolUse`) is pure; `runCommandHook` is the process edge.
+ *
+ * @module lib/engine/hooks
+ */
+
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { preparePreSendHook } from "../comms/send-gate.mjs";
+import { configuredCommandEnv, inheritEnvFor, PROJECT_SCOPES } from "./context/child-env.mjs";
+import { createProcessTracker, newProcessTag, PROCESS_TAG_ENV } from "./process-tree.mjs";
+
+export const HOOK_OUTPUT_CAP = 10_000;
+export const DEFAULT_HOOK_TIMEOUT_MS = 60_000;
+const RAW_OUTPUT_LIMIT = 1_000_000;
+
+/** Events that name a tool, so their matcher is tested against the tool name. */
+const TOOL_EVENTS = new Set(["PreToolUse", "PostToolUse"]);
+
+/** @param {string} s @param {number} [cap] */
+export function capText(s, cap = HOOK_OUTPUT_CAP) {
+  const t = String(s ?? "");
+  return t.length <= cap ? t : `${t.slice(0, cap)}\n… [hook output truncated at ${cap} characters]`;
+}
+
+/**
+ * @param {string|undefined} matcher
+ * @param {string} target
+ */
+export function matcherMatches(matcher, target) {
+  if (matcher === undefined || matcher === "" || matcher === "*") return true;
+  try {
+    return new RegExp(`^(?:${matcher})$`).test(target);
+  } catch {
+    return matcher === target;
+  }
+}
+
+/**
+ * @typedef {{command:string, timeoutMs:number, source:string, baseDir:string, scope?:string, inheritEnv?:unknown}} SelectedHook
+ *   `inheritEnv`: the hook object's own list, as configured (validated by the runner, CF-22)
+ */
+
+/**
+ * @param {Record<string, import('./context/settings.mjs').HookEntry[]>} config
+ * @param {string} event
+ * @param {string} target  tool name, source, trigger or notification type ("" when the event has none)
+ * @returns {SelectedHook[]}
+ */
+export function selectHooks(config, event, target) {
+  const seen = new Set();
+  /** @type {SelectedHook[]} */
+  const out = [];
+  for (const entry of config?.[event] ?? []) {
+    const applies = TOOL_EVENTS.has(event) || event === "SessionStart" || event === "PreCompact" || event === "Notification" ? matcherMatches(entry.matcher, target) : true;
+    if (!applies) continue;
+    for (const h of entry.hooks) {
+      if (!h || h.type !== "command" || typeof h.command !== "string" || h.command.trim() === "") continue;
+      if (seen.has(h.command)) continue;
+      seen.add(h.command);
+      const secs = Number(h.timeout);
+      /** @type {SelectedHook} */
+      const selected = { command: h.command, timeoutMs: Number.isFinite(secs) && secs > 0 ? secs * 1000 : DEFAULT_HOOK_TIMEOUT_MS, source: entry.source, baseDir: entry.baseDir };
+      if (entry.scope !== undefined) selected.scope = entry.scope;
+      if (/** @type {any} */ (h).inheritEnv !== undefined) selected.inheritEnv = /** @type {any} */ (h).inheritEnv;
+      out.push(selected);
+    }
+  }
+  return out;
+}
+
+/**
+ * @typedef {{kind:'exited', code:number|null, stdout:string, stderr:string}
+ *   | {kind:'timeout', stdout:string, stderr:string, timeoutMs:number}
+ *   | {kind:'spawn_error', message:string}} HookRun
+ *
+ * @typedef {Object} HookVerdict
+ * @property {'success'|'blocking'|'non_blocking_error'} outcome
+ * @property {string} [blockReason]        exit 2 or decision "block"
+ * @property {'allow'|'deny'|'ask'} [permissionDecision]
+ * @property {string} [permissionDecisionReason]
+ * @property {Record<string,unknown>} [updatedInput]
+ * @property {string} [additionalContext]
+ * @property {string} [stopReason]         continue:false
+ * @property {string} [error]
+ */
+
+/**
+ * @param {string} event
+ * @param {HookRun} run
+ * @returns {HookVerdict}
+ */
+export function interpretHookRun(event, run) {
+  if (run.kind === "spawn_error") return { outcome: "non_blocking_error", error: `could not run: ${run.message}` };
+  if (run.kind === "timeout") return { outcome: "non_blocking_error", error: `timed out after ${run.timeoutMs} ms` };
+  if (run.code === 2) {
+    const reason = capText(run.stderr.trim() || "blocked by a hook (no reason given)");
+    return { outcome: "blocking", blockReason: reason };
+  }
+  if (run.code !== 0) {
+    return { outcome: "non_blocking_error", error: `exited with code ${run.code}${run.stderr.trim() ? `: ${capText(run.stderr.trim(), 500)}` : ""}` };
+  }
+
+  const out = run.stdout.trim();
+  /** @type {any} */
+  let json = null;
+  if (out.startsWith("{")) {
+    try {
+      json = JSON.parse(out);
+    } catch {
+      json = null; // not JSON after all: treated as plain output below
+    }
+  }
+  if (!json || typeof json !== "object" || Array.isArray(json)) {
+    const plainIsContext = event === "SessionStart" || event === "UserPromptSubmit";
+    return plainIsContext && out !== "" ? { outcome: "success", additionalContext: capText(out) } : { outcome: "success" };
+  }
+
+  /** @type {HookVerdict} */
+  const v = { outcome: "success" };
+  if (json.continue === false) v.stopReason = capText(typeof json.stopReason === "string" ? json.stopReason : "a hook ended the run");
+  const hso = json.hookSpecificOutput && typeof json.hookSpecificOutput === "object" ? json.hookSpecificOutput : {};
+  if (typeof hso.additionalContext === "string" && hso.additionalContext !== "") v.additionalContext = capText(hso.additionalContext);
+  const reason = typeof json.reason === "string" ? json.reason : "";
+  if (event === "PreToolUse") {
+    const pd = hso.permissionDecision;
+    if (pd === "allow" || pd === "deny" || pd === "ask") {
+      v.permissionDecision = pd;
+      v.permissionDecisionReason = capText(typeof hso.permissionDecisionReason === "string" ? hso.permissionDecisionReason : reason);
+    } else if (json.decision === "block") {
+      v.permissionDecision = "deny";
+      v.permissionDecisionReason = capText(reason || "blocked by a hook");
+    } else if (json.decision === "approve") {
+      v.permissionDecision = "allow";
+      v.permissionDecisionReason = capText(reason);
+    }
+    if (hso.updatedInput && typeof hso.updatedInput === "object" && !Array.isArray(hso.updatedInput)) v.updatedInput = hso.updatedInput;
+    if (v.permissionDecision === "deny") {
+      v.outcome = "blocking";
+      v.blockReason = v.permissionDecisionReason || "blocked by a hook";
+    }
+  } else if (json.decision === "block") {
+    v.outcome = "blocking";
+    v.blockReason = capText(reason || "blocked by a hook (no reason given)");
+  }
+  return v;
+}
+
+/**
+ * Fold PreToolUse verdicts: any block wins, then ask, then allow.
+ * @param {HookVerdict[]} verdicts
+ * @returns {{decision:'block'|'ask'|'allow'|'none', reason:string, updatedInput:Record<string,unknown>|null, additionalContext:string|null, stopReason:string|null}}
+ */
+export function combinePreToolUse(verdicts) {
+  const blocks = verdicts.filter((v) => v.outcome === "blocking").map((v) => v.blockReason || "blocked");
+  const asks = verdicts.filter((v) => v.permissionDecision === "ask");
+  const allows = verdicts.filter((v) => v.permissionDecision === "allow");
+  const updated = verdicts.filter((v) => v.updatedInput).map((v) => v.updatedInput);
+  const context = verdicts.map((v) => v.additionalContext).filter(Boolean);
+  const stop = verdicts.find((v) => v.stopReason);
+  const decision = blocks.length ? "block" : asks.length ? "ask" : allows.length ? "allow" : "none";
+  const reason = blocks.length ? blocks.join("\n") : asks.length ? asks.map((v) => v.permissionDecisionReason || "").filter(Boolean).join("\n") : allows.map((v) => v.permissionDecisionReason || "").filter(Boolean).join("\n");
+  return {
+    decision,
+    reason: capText(reason),
+    updatedInput: updated.length ? /** @type any */ (updated[updated.length - 1]) : null,
+    additionalContext: context.length ? capText(context.join("\n\n")) : null,
+    stopReason: stop?.stopReason ?? null,
+  };
+}
+
+/** After a killed hook, how long its pipes may take to close before they are destroyed (CF-119). */
+export const HOOK_PIPE_SETTLE_MS = 500;
+
+/**
+ * Run one command hook. Never rejects.
+ *
+ * CF-119 (W5-B): a hook that times out or is aborted is stopped by process
+ * TREE, not only by process group — the same tracker as background shells
+ * (process-tree.mjs): its environment carries COHORT_ENGINE_PROCESS_TAG, its
+ * descendants are sampled (parent links and the tag) 100 ms and 500 ms after it
+ * starts and every 2 s while it runs, and again at the kill; every recorded
+ * process whose start identity still matches is SIGKILLed with the group. A
+ * process no walk found that still holds the hook's pipes cannot hold the run:
+ * the pipes are destroyed {@link HOOK_PIPE_SETTLE_MS} after the kill.
+ * @param {{command:string, input:object, timeoutMs:number, cwd:string, env:Record<string,string|undefined>, signal?:AbortSignal,
+ *          processTracker?:ReturnType<typeof createProcessTracker>}} p  `processTracker`: injected by tests
+ * @returns {Promise<HookRun>}
+ */
+export function runCommandHook({ command, input, timeoutMs, cwd, env, signal, processTracker }) {
+  return new Promise((resolve) => {
+    const tag = newProcessTag();
+    const rootId = `hook_${tag}`;
+    const tracker = processTracker ?? createProcessTracker();
+    let child;
+    try {
+      child = spawn("/bin/sh", ["-c", command], { cwd, env: { ...env, [PROCESS_TAG_ENV]: tag }, stdio: ["pipe", "pipe", "pipe"], detached: true });
+    } catch (e) {
+      if (!processTracker) tracker.dispose();
+      resolve({ kind: "spawn_error", message: e instanceof Error ? e.message : String(e) });
+      return;
+    }
+    if (child.pid) tracker.track({ id: rootId, pid: child.pid, tag });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let settled = false;
+    /** @type {NodeJS.Timeout|null} */
+    let settleTimer = null;
+    const kill = () => {
+      if (settleTimer !== null || settled) return;
+      // Record the tree (and tagged processes) while the parents still live, then signal group and tree.
+      try {
+        tracker.capture([rootId], { tags: true });
+      } catch {
+        /* the group signal still goes out */
+      }
+      try {
+        process.kill(-(/** @type number */ (child.pid)), "SIGKILL");
+      } catch {
+        /* the group already exited */
+      }
+      try {
+        tracker.signal([rootId], "SIGKILL");
+      } catch {
+        /* best effort: identity-checked pids only */
+      }
+      settleTimer = setTimeout(() => {
+        child.stdout?.destroy();
+        child.stderr?.destroy();
+        child.unref();
+        finish(timedOut ? { kind: "timeout", stdout, stderr, timeoutMs } : { kind: "exited", code: child.exitCode, stdout, stderr });
+      }, HOOK_PIPE_SETTLE_MS);
+    };
+    const timer = setTimeout(() => {
+      timedOut = true;
+      kill();
+    }, timeoutMs);
+    const onAbort = () => kill();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (d) => {
+      if (stdout.length < RAW_OUTPUT_LIMIT) stdout += d;
+    });
+    child.stderr.on("data", (d) => {
+      if (stderr.length < RAW_OUTPUT_LIMIT) stderr += d;
+    });
+    child.stdin.on("error", () => {
+      /* a hook that exits without reading stdin: EPIPE is not a failure */
+    });
+    const finish = (/** @type HookRun */ r) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (settleTimer !== null) clearTimeout(settleTimer);
+      signal?.removeEventListener("abort", onAbort);
+      tracker.rootExited(rootId);
+      tracker.forget(rootId);
+      if (!processTracker) tracker.dispose();
+      resolve(r);
+    };
+    child.on("error", (e) => finish({ kind: "spawn_error", message: e.message }));
+    child.on("close", (code) => finish(timedOut ? { kind: "timeout", stdout, stderr, timeoutMs } : { kind: "exited", code, stdout, stderr }));
+    child.stdin.end(JSON.stringify(input));
+  });
+}
+
+/* ────────────────────────────── in-process gates ─────────────────────────── */
+
+/**
+ * @typedef {{toolName:string, toolInput:Record<string,unknown>, toolUseId?:string, mcp?:{server:string, tool:string, command?:string|null, args?:string[]}|null}} GateCall
+ * @typedef {() => ({ok:true}|{ok:false, reason:string})} GateCommit
+ * @typedef {{allow:true, commit?:GateCommit}|{allow:false, reason:string}} GateVerdict
+ * @typedef {{name:string, applies:(call:GateCall)=>boolean, check:(call:GateCall)=>(GateVerdict|Promise<GateVerdict>)}} Gate
+ */
+
+export function createGateRegistry() {
+  /** @type {Gate[]} */
+  const gates = [];
+  return {
+    /** @param {Gate} gate */
+    register(gate) {
+      gates.push(gate);
+    },
+    list: () => gates.map((g) => g.name),
+    /**
+     * Every applicable gate, in registration order; the first refusal wins.
+     * An allow lists the commits of the gates that returned one.
+     * @param {GateCall} call
+     * @returns {Promise<{allow:true, commits?:Array<{gate:string, commit:GateCommit}>}|{allow:false, gate:string, reason:string}>}
+     */
+    async evaluate(call) {
+      /** @type {Array<{gate:string, commit:GateCommit}>} */
+      const commits = [];
+      for (const g of gates) {
+        let applies;
+        try {
+          applies = g.applies(call);
+        } catch (e) {
+          return { allow: false, gate: g.name, reason: `the ${g.name} gate failed to evaluate (${e instanceof Error ? e.message : e}); failing closed` };
+        }
+        if (!applies) continue;
+        try {
+          const v = await g.check(call);
+          if (!v || v.allow !== true) return { allow: false, gate: g.name, reason: (v && "reason" in v && v.reason) || "refused" };
+          if (typeof v.commit === "function") commits.push({ gate: g.name, commit: v.commit });
+        } catch (e) {
+          return { allow: false, gate: g.name, reason: `the ${g.name} gate failed (${e instanceof Error ? e.message : e}); failing closed` };
+        }
+      }
+      return commits.length ? { allow: true, commits } : { allow: true };
+    },
+  };
+}
+
+/** The outbound tool names the send gate screens, on any MCP server. */
+export const SEND_GATE_TOOLS = Object.freeze(["messaging_send", "messaging_send_voice_note", "email_send", "email_draft_send", "org_rpc"]);
+/** Any server, any case: `mcp__<server>__<one of SEND_GATE_TOOLS>`. */
+export const SEND_GATE_MATCHER = /^mcp__.+__(messaging_send|messaging_send_voice_note|email_send|email_draft_send|org_rpc)$/i;
+
+/**
+ * Is this MCP server the Cohort org server, whatever key the config gave it?
+ * Informational only (the send gate no longer depends on it): a config key,
+ * an HTTP endpoint or a launcher like `maestro mcp` can all hide it.
+ * @param {{server:string, command?:string|null, args?:string[]}} mcp
+ */
+export function isCohortOrgServer(mcp) {
+  const key = String(mcp.server).toLowerCase();
+  if (key === "cohort" || key === "neolith") return true;
+  const bin = mcp.command ? path.basename(mcp.command) : "";
+  if (bin === "cohort-mcp" || bin === "neolith-mcp") return true;
+  return (mcp.args ?? []).some((a) => /(^|\/)(cohort|neolith)-mcp(\.mjs)?$/.test(String(a)));
+}
+
+/** The send gate's registry name. */
+export const SEND_GATE_NAME = "outbound send";
+
+/** The seat's shell pre-send hook (lib/collective/global-config.mjs PRE_SEND_HOOK_MARKER). */
+export const PRE_SEND_AUDIT_SCRIPT = "scripts/hooks/pre-send-audit.sh";
+
+/** Shells whose `-c` script is looked into by {@link isPreSendAuditCommand}. */
+const SHELL_WORDS = new Set(["sh", "bash", "zsh", "dash", "ksh"]);
+const MAX_SHELL_NESTING = 3;
+
+/** Words that precede a command without being it. */
+const COMMAND_PREFIXES = new Set(["exec", "command", "nohup", "time", "!", "{", "(", "if", "then", "else", "elif", "do", "while", "until"]);
+/** Commands that run a script file named as their first operand. */
+const SOURCE_WORDS = new Set([".", "source"]);
+
+/**
+ * Split a command into simple commands, each a list of words. Quoted parts
+ * stay inside their word (and keep their quotes, so an unquoted word can be
+ * told from a quoted one); `;`, `&&`, `||`, `|`, `&`, `(`, `)` and newlines
+ * outside quotes separate commands. Not a shell parser — enough to find the
+ * command word of each simple command.
+ * @param {string} command
+ * @returns {string[][]}
+ */
+function simpleCommands(command) {
+  const re = /(&&|\|\||[;|&()\n])|((?:"(?:[^"\\]|\\.)*"?|'[^']*'?|[^\s;|&()"'])+)/g;
+  /** @type {string[][]} */
+  const out = [[]];
+  let m;
+  while ((m = re.exec(String(command ?? ""))) !== null) {
+    if (m[1] !== undefined) {
+      if (out[out.length - 1].length > 0) out.push([]);
+    } else out[out.length - 1].push(m[2]);
+  }
+  return out.filter((c) => c.length > 0);
+}
+
+/** A word with its quotes removed (`"a b"/c` → `a b/c`). @param {string} w */
+function unquote(w) {
+  return w.replace(/"((?:[^"\\]|\\.)*)"?|'([^']*)'?/g, (_, dq, sq) => (dq !== undefined ? dq.replace(/\\(["\\$`])/g, "$1") : sq));
+}
+
+/**
+ * Commands that can sit beside the script in one hook command without doing
+ * any screening or side work of their own (`cd /agent && …`, `test -f x; …`).
+ */
+const NEUTRAL_COMMANDS = new Set(["cd", "true", ":", "test", "[", "[[", "export", "set", "umask", "fi", "done", "}"]);
+
+/**
+ * Does this word, as the shell reads it, run a command of its own? True for a
+ * command substitution outside single quotes (`$(…)`, backticks, `<(…)`,
+ * `>(…)`) and for an assignment to BASH_ENV or ENV (a file the next shell
+ * sources). Conservative: a `$(` inside double quotes counts. Pure.
+ * @param {string} word
+ */
+function runsSomethingItself(word) {
+  if (/^(?:BASH_ENV|ENV)=/.test(unquote(word))) return true;
+  let single = false;
+  for (let i = 0; i < word.length; i++) {
+    const ch = word[i];
+    if (ch === "\\" && !single) {
+      i++;
+      continue;
+    }
+    if (ch === "'") single = !single;
+    else if (!single && (ch === "`" || ((ch === "$" || ch === "<" || ch === ">") && word[i + 1] === "("))) return true;
+  }
+  return false;
+}
+
+/**
+ * What one simple command does, for {@link isPreSendAuditCommand}:
+ * `audit` runs the script, `neutral` is a {@link NEUTRAL_COMMANDS} word (or only
+ * prefixes), `other` runs anything else.
+ * @param {string[]} words @param {number} depth
+ * @returns {'audit'|'neutral'|'other'}
+ */
+function classifySimpleCommand(words, depth) {
+  const isScript = (/** @type string */ p) => p === PRE_SEND_AUDIT_SCRIPT || p.endsWith(`/${PRE_SEND_AUDIT_SCRIPT}`);
+  const isOption = (/** @type string */ w) => /^-[A-Za-z-]*$/.test(w);
+  // CF-53: a word that runs something of its own — a command substitution (`"$(…)"`, backticks,
+  // `<(…)`) or a shell start-up file (BASH_ENV=…, ENV=…) — makes the whole command other work, even
+  // beside a neutral `cd`/`export` or as the script's own argument: skipping it would skip that work.
+  if (words.some((w) => runsSomethingItself(w))) return "other";
+  let k = 0;
+  // Assignments, prefixes and `env` (with its options) come before the command word.
+  while (k < words.length) {
+    const w = unquote(words[k]);
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[k]) || COMMAND_PREFIXES.has(w)) k++;
+    else if ((w.split("/").pop() ?? "") === "env") {
+      k++;
+      while (k < words.length && isOption(words[k])) k += words[k] === "-u" ? 2 : 1;
+    } else break;
+  }
+  if (k >= words.length) return "neutral";
+  const head = unquote(words[k]);
+  if (isScript(head)) return "audit";
+  if (NEUTRAL_COMMANDS.has(head)) return "neutral";
+  if (SOURCE_WORDS.has(head)) return k + 1 < words.length && isScript(unquote(words[k + 1])) ? "audit" : "other";
+  if (!SHELL_WORDS.has(head.split("/").pop() ?? "")) return "other";
+  // A shell: options up to one carrying `c` (-c, -lc, -ec) hand it a script; otherwise the first operand is a script file.
+  let j = k + 1;
+  while (j < words.length && isOption(words[j]) && !/^-[A-Za-z]*c[A-Za-z]*$/.test(words[j])) j++;
+  if (j >= words.length) return "other";
+  if (/^-[A-Za-z]*c[A-Za-z]*$/.test(words[j])) {
+    return depth < MAX_SHELL_NESTING && j + 1 < words.length && isPreSendAuditCommand(unquote(words[j + 1]), depth + 1) ? "audit" : "other";
+  }
+  return isScript(unquote(words[j])) ? "audit" : "other";
+}
+
+/**
+ * Does a hook command run the seat's pre-send-audit.sh — and nothing else that
+ * skipping it would also skip? True when some simple command of it runs the
+ * script's path — relative (`./scripts/hooks/pre-send-audit.sh gmail`) or
+ * absolute, quoted or not:
+ *   · as the command word itself, after assignments and wrappers
+ *     (`A=1 …`, `env -i A=1 …`, `exec …`, `nohup …`);
+ *   · as the script operand of a shell or `.`/`source`
+ *     (`'bash' '/agent/scripts/hooks/pre-send-audit.sh' cohort`, the form
+ *     `maestro setup` writes);
+ *   · inside the script a shell is handed with `-c` (`bash -c "…"`,
+ *     `sh -lc '…'`, `/usr/bin/env bash -c "…"`), by the same rules, to a
+ *     nesting depth of 3 (CF-46, W3-G2);
+ * and every other simple command beside it is neutral (`cd`, `test`, `true`,
+ * `export`, …). A command that also runs something else
+ * (`bash -c "…/pre-send-audit.sh cohort && ./other.sh"`, W3-G1) is NOT
+ * recognised: skipping it would skip the other script too, so it runs and the
+ * send is counted twice. The path as an argument to anything else
+ * (`echo …/pre-send-audit.sh`, `bash -c "echo …/pre-send-audit.sh"`) is not a
+ * run of it. A form this misses still runs: the miss costs a double count,
+ * never a skipped screen.
+ *
+ * CF-53 (W5-B): a word that runs a command of its own makes its simple command
+ * `other`, wherever it sits — `cd "$(./x.sh)" && …/pre-send-audit.sh`,
+ * `` cd `./x.sh`; … ``, `…/pre-send-audit.sh "$(./x.sh)"`,
+ * `BASH_ENV=./x.sh bash -c "…/pre-send-audit.sh"` all RUN. The double count
+ * is the accepted cost of every such chained hook: the in-process gate counts
+ * the send once, and the shell script, which runs too, counts it again — a
+ * seat that chains the audit script with its own commands should split them
+ * into two hook objects so the audit one alone is skipped.
+ * @param {string} command
+ * @param {number} [depth]
+ */
+export function isPreSendAuditCommand(command, depth = 0) {
+  let runs = false;
+  for (const words of simpleCommands(command)) {
+    const kind = classifySimpleCommand(words, depth);
+    if (kind === "other") return false;
+    if (kind === "audit") runs = true;
+  }
+  return runs;
+}
+
+/**
+ * CF-20: is this command hook superseded by the in-process send gate? The seat's
+ * global ~/.claude/settings.json mounts pre-send-audit.sh on the outbound
+ * `mcp__cohort__*` tools for the claude binary. The engine loads that file too,
+ * and its send gate already screens AND counts the same call, so running the
+ * shell hook as well would count one allowed send twice against the caps.
+ * Only a PreToolUse hook running pre-send-audit.sh on a tool the gate screens
+ * is superseded; the same script on any other tool (a gmail draft) still runs.
+ * @param {string} event @param {string} toolName @param {string} command
+ */
+export function supersededBySendGate(event, toolName, command) {
+  return event === "PreToolUse" && SEND_GATE_MATCHER.test(String(toolName)) && isPreSendAuditCommand(command);
+}
+
+/** @param {GateCall} call */
+export function sendGateApplies(call) {
+  if (SEND_GATE_MATCHER.test(call.toolName)) return true;
+  return Boolean(call.mcp && SEND_GATE_TOOLS.includes(String(call.mcp.tool).toLowerCase()));
+}
+
+/**
+ * The outbound send gate: the pre-send-audit verdict, in process. The screen
+ * and the cap check run at `check`; the counter is written by the verdict's
+ * `commit`, which the guard runs only for a call that is finally allowed.
+ * @param {{env:Record<string,string|undefined>, now?:()=>number, sessionId?:string, cwd?:string, prepareHook?:typeof preparePreSendHook}} deps
+ * @returns {Gate}
+ */
+export function createSendGate({ env, now = Date.now, sessionId = "", cwd = "", prepareHook = preparePreSendHook }) {
+  const unblock = (/** @type string */ stderr) => String(stderr ?? "").trim().replace(/^BLOCKED:\s*/, "") || "blocked by the outbound send gate";
+  return {
+    name: SEND_GATE_NAME,
+    applies: sendGateApplies,
+    check(call) {
+      const payload = { session_id: sessionId, cwd, hook_event_name: "PreToolUse", tool_name: call.toolName, tool_input: call.toolInput };
+      const prepared = prepareHook({ channel: "cohort", stdin: JSON.stringify(payload), env, now: new Date(now()) });
+      if (!prepared.ok) return { allow: false, reason: unblock(prepared.result.stderr) };
+      return {
+        allow: true,
+        commit: () => {
+          const res = prepared.commit();
+          return res.code === 0 ? { ok: true } : { ok: false, reason: unblock(res.stderr) };
+        },
+      };
+    },
+  };
+}
+
+/** @param {Parameters<typeof createSendGate>[0]} deps */
+export function createDefaultGates(deps) {
+  const registry = createGateRegistry();
+  registry.register(createSendGate(deps));
+  return registry;
+}
+
+/* ─────────────────────────────── the runner ──────────────────────────────── */
+
+/**
+ * @param {object} p
+ * @param {Record<string, import('./context/settings.mjs').HookEntry[]>} p.hooks
+ * @param {string} p.sessionId
+ * @param {string} p.transcriptPath
+ * @param {string} p.cwd
+ * @param {string} [p.permissionMode]
+ * @param {Record<string,string|undefined>} p.env
+ * @param {typeof runCommandHook} [p.runCommand]
+ * @param {(line:string)=>void} [p.log]  where non-blocking hook errors are reported
+ * @param {boolean} [p.sendGateInProcess] the run's gate registry holds the send
+ *   gate, so a pre-send-audit.sh PreToolUse hook on a gated tool is skipped
+ *   ({@link supersededBySendGate}). Off by default: a runner without the gate
+ *   must keep the shell screen.
+ */
+export function createHookRunner({ hooks, sessionId, transcriptPath, cwd, permissionMode = "default", env, runCommand = runCommandHook, log = () => {}, sendGateInProcess = false, envPassthrough = [] }) {
+  // CF-22: no credential reaches a hook command unless its own `inheritEnv` names it
+  // (a project-scoped hook may not name one), or `envPassthrough` names an extended-shape one.
+  const extra = { CLAUDE_PROJECT_DIR: cwd, COHORT_PROJECT_DIR: cwd };
+  /** @type {Map<string, Record<string,string>>} */
+  const envByInherit = new Map();
+  const hookEnvFor = (/** @type {string[]} */ inheritEnv) => {
+    const key = inheritEnv.join("\n");
+    if (!envByInherit.has(key)) envByInherit.set(key, { ...configuredCommandEnv(env, { inheritEnv, passthrough: envPassthrough }), ...extra });
+    return /** @type {Record<string,string>} */ (envByInherit.get(key));
+  };
+  /** Superseded commands and refused inheritEnv names already reported, so the log names each once. */
+  const reportedSkips = new Set();
+
+  /**
+   * @param {string} event @param {string} target @param {object} fields @param {AbortSignal} [signal]
+   * @returns {Promise<HookVerdict[]>}
+   */
+  async function fire(event, target, fields, signal) {
+    let selected = selectHooks(hooks, event, target);
+    if (sendGateInProcess) {
+      selected = selected.filter((h) => {
+        if (!supersededBySendGate(event, target, h.command)) return true;
+        if (!reportedSkips.has(h.command)) {
+          reportedSkips.add(h.command);
+          log(`${event} hook "${h.command}" (${h.source}) skipped for ${target}: the in-process send gate already screens and counts outbound sends`);
+        }
+        return false;
+      });
+    }
+    if (selected.length === 0) return [];
+    const input = { session_id: sessionId, transcript_path: transcriptPath, cwd, hook_event_name: event, permission_mode: permissionMode, ...fields };
+    const envs = selected.map((h) => {
+      const inherit = inheritEnvFor(h.inheritEnv, { projectScoped: PROJECT_SCOPES.has(String(h.scope ?? "")), env });
+      const note = inherit.error ?? (inherit.refused.length ? `inheritEnv ${inherit.refused.join(", ")} not passed: a ${h.scope} settings hook may not inherit a credential` : null);
+      if (note && !reportedSkips.has(`${h.command}\n${note}`)) {
+        reportedSkips.add(`${h.command}\n${note}`);
+        log(`${event} hook "${h.command}" (${h.source}): ${note}`);
+      }
+      return hookEnvFor(inherit.names);
+    });
+    const runs = await Promise.all(selected.map((h, i) => runCommand({ command: h.command, input, timeoutMs: h.timeoutMs, cwd, env: envs[i], signal })));
+    return runs.map((run, i) => {
+      const v = interpretHookRun(event, run);
+      if (v.outcome === "non_blocking_error") log(`${event} hook "${selected[i].command}" (${selected[i].source}): ${v.error}`);
+      else if (v.outcome === "blocking" && !BLOCKABLE.has(event)) log(`${event} hook "${selected[i].command}" reported: ${v.blockReason}`);
+      return v;
+    });
+  }
+
+  const contextOf = (/** @type HookVerdict[] */ vs) => {
+    const parts = vs.map((v) => v.additionalContext).filter(Boolean);
+    return parts.length ? capText(parts.join("\n\n")) : null;
+  };
+  const stopOf = (/** @type HookVerdict[] */ vs) => vs.find((v) => v.stopReason)?.stopReason ?? null;
+
+  return {
+    /** @param {{source:'startup'|'resume'|'clear'|'compact'}} p */
+    async sessionStart({ source }) {
+      const vs = await fire("SessionStart", source, { source });
+      return { additionalContext: contextOf(vs), stopReason: stopOf(vs) };
+    },
+    /** @param {{prompt:string}} p */
+    async userPromptSubmit({ prompt }) {
+      const vs = await fire("UserPromptSubmit", "", { prompt });
+      const blocked = vs.filter((v) => v.outcome === "blocking").map((v) => v.blockReason);
+      return { blockReason: blocked.length ? capText(blocked.join("\n")) : null, additionalContext: contextOf(vs), stopReason: stopOf(vs) };
+    },
+    /** @param {{toolName:string, toolInput:object, toolUseId:string, signal?:AbortSignal}} p */
+    async preToolUse({ toolName, toolInput, toolUseId, signal }) {
+      return combinePreToolUse(await fire("PreToolUse", toolName, { tool_name: toolName, tool_input: toolInput, tool_use_id: toolUseId }, signal));
+    },
+    /** @param {{toolName:string, toolInput:object, toolUseId:string, toolResponse:unknown, signal?:AbortSignal}} p */
+    async postToolUse({ toolName, toolInput, toolUseId, toolResponse, signal }) {
+      const vs = await fire("PostToolUse", toolName, { tool_name: toolName, tool_input: toolInput, tool_use_id: toolUseId, tool_response: toolResponse }, signal);
+      const feedback = vs.filter((v) => v.outcome === "blocking").map((v) => v.blockReason);
+      return { feedback: feedback.length ? capText(feedback.join("\n")) : null, additionalContext: contextOf(vs), stopReason: stopOf(vs) };
+    },
+    /** @param {{stopHookActive:boolean, event?:'Stop'|'SubagentStop', fields?:Record<string, unknown>}} p  `fields`: SubagentStop's agent_id, agent_type */
+    async stop({ stopHookActive, event = "Stop", fields = {} }) {
+      const vs = await fire(event, "", { stop_hook_active: stopHookActive, ...fields });
+      const cont = vs.filter((v) => v.outcome === "blocking").map((v) => v.blockReason);
+      return { continueWith: cont.length ? capText(cont.join("\n")) : null, stopReason: stopOf(vs) };
+    },
+    /** @param {{trigger:'manual'|'auto', customInstructions?:string}} p */
+    async preCompact({ trigger, customInstructions = "" }) {
+      const vs = await fire("PreCompact", trigger, { trigger, custom_instructions: customInstructions });
+      const blocked = vs.filter((v) => v.outcome === "blocking").map((v) => v.blockReason);
+      return { blockReason: blocked.length ? capText(blocked.join("\n")) : null, stopReason: stopOf(vs) };
+    },
+    /** @param {{message:string, notificationType:string}} p */
+    async notification({ message, notificationType }) {
+      await fire("Notification", notificationType, { message, notification_type: notificationType });
+    },
+  };
+}
+
+const BLOCKABLE = new Set(["UserPromptSubmit", "PreToolUse", "PostToolUse", "Stop", "SubagentStop", "PreCompact"]);