@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/lib/comms/send-gate.mjs

@@ -92,6 +92,31 @@ export const BANNED_OPENERS = Object.freeze([
   "Great question!",
 ]);
 
+/* ───────────────────────────── persona discipline ────────────────────────── */
+// Front-door session design (2026-09-08 §3.6): the agent is ONE persona to
+// every human; parallel sessions, sub-sessions, subagents and workflows are
+// internal workings and may never be named in outbound text, nor may "Claude
+// Code" or "a language model". Kept in sync with scripts/hooks/pre-send-audit.sh
+// PERSONA_PATTERNS so the PreToolUse hook and this in-process gate reject the
+// same set. "subagent"/"sub-agent" is blocked only when followed by
+// said|reported|session — the bare noun in an internal-process sentence is
+// tolerated; attributing speech to a machine part is not.
+export const PERSONA_PATTERNS = Object.freeze([
+  /claude\s+code/i,
+  /claude\s+sessions?/i,
+  /sub-sessions?/i,
+  /sub-?agents?\s+(?:said|reported|sessions?)/i,
+  /workflow\s+agents?/i,
+  /as\s+an\s+ai\b/i,
+  /language\s+model/i,
+]);
+
+/** Where the persona screen reads the agent's identity + peer registry from. */
+const PERSONA_FILES = Object.freeze({
+  agent: "config/agent.json",
+  peers: "state/session/peers.json",
+});
+
 /* ────────────────────────── recipient classification ─────────────────────── */
 
 /**
@@ -262,6 +287,84 @@ export function screenBannedPhrases(text) {
   return null;
 }
 
+function escapeRe(str) {
+  return String(str).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * (a2) Persona-leak screen. Pure; no IO. Returns a block reason (naming the
+ * offending phrase so the caller can rewrite in its own voice) or null.
+ *
+ * Session names are BOUNDED, not guessed: `<first>-main` is always internal,
+ * and any other name is internal only when it is in `sessionNames` (the
+ * registry `maestro session spawn` keeps in state/session/peers.json). A
+ * colleague called Marc-Antoine, the URL slug james-kirkland or the mailbox
+ * ethan-miller@ therefore pass, while `alex-main` / a registered `alex-deck`
+ * do not. Matching is word-bounded on [A-Za-z0-9_-] and case-insensitive.
+ *
+ * @param {string} text
+ * @param {{first?:string, sessionNames?:string[]}} [o]
+ * @returns {string|null}
+ */
+export function screenPersona(text, o = {}) {
+  const t = typeof text === "string" ? text : "";
+  if (!t) return null;
+  for (const re of PERSONA_PATTERNS) {
+    const m = re.exec(t);
+    if (m) {
+      return `persona leak "${m[0]}" — rewrite in your own voice (my team / a colleague); never name the machinery`;
+    }
+  }
+  const first = String(o.first || "").trim().toLowerCase().replace(/[^a-z0-9-]+/g, "");
+  const names = new Set();
+  if (first) names.add(`${first}-main`);
+  for (const n of Array.isArray(o.sessionNames) ? o.sessionNames : []) {
+    const v = String(n || "").trim().toLowerCase();
+    if (v) names.add(v);
+  }
+  for (const name of names) {
+    const re = new RegExp(`(^|[^A-Za-z0-9_-])(${escapeRe(name)})(?![A-Za-z0-9_-])`, "i");
+    const m = re.exec(t);
+    if (m) {
+      return `persona leak "${m[2]}" is an internal session name — say "my team" or "a colleague" instead`;
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the persona inputs from disk (fail-open: anything unreadable is
+ * simply absent, and the name check is then skipped while the phrase check
+ * still runs). Explicit values win over the files.
+ */
+function personaContext(fs, agentRoot, { agentFirst, sessionNames }) {
+  let first = typeof agentFirst === "string" ? agentFirst : "";
+  if (!first) {
+    const a = readPolicy(fs, agentRoot, PERSONA_FILES.agent);
+    if (a.ok) {
+      try {
+        const doc = JSON.parse(a.text) || {};
+        first = String(doc.firstName || String(doc.fullName || "").split(/\s+/)[0] || "");
+      } catch { first = ""; }
+    }
+  }
+  let names = Array.isArray(sessionNames) ? sessionNames : null;
+  if (!names) {
+    names = [];
+    const p = readPolicy(fs, agentRoot, PERSONA_FILES.peers);
+    if (p.ok) {
+      try {
+        const doc = JSON.parse(p.text);
+        const list = Array.isArray(doc) ? doc : doc && Array.isArray(doc.peers) ? doc.peers : [];
+        for (const peer of list) {
+          if (peer && typeof peer === "object" && typeof peer.name === "string" && peer.name) names.push(peer.name);
+        }
+      } catch { /* a corrupt registry is an empty one */ }
+    }
+  }
+  return { first, sessionNames: names };
+}
+
 /**
  * (b) AI-disclosure screen. Resolves the active posture for the recipient's
  * jurisdiction from ai-disclosure.yaml and enforces two things:
@@ -431,6 +534,8 @@ export function screenAllowlist(recipient, allowlist) {
  * @param {boolean} [args.firstContact=true] is this the first message in the convo
  * @param {string[]} [args.internalDomains] email domains treated as internal
  * @param {string[]} [args.allowlist] recipient allowlist (opt-in)
+ * @param {string} [args.agentFirst] agent first name for the session-name check (default: agentRoot/config/agent.json)
+ * @param {string[]} [args.sessionNames] internal session names (default: agentRoot/state/session/peers.json)
  * @param {object} [args.fs] injected { readFileSync, existsSync } for tests
  * @returns {Promise<{allow:boolean, reason:string, redactedText?:string}>}
  */
@@ -443,6 +548,8 @@ export async function screenOutbound({
   firstContact = true,
   internalDomains = [],
   allowlist = undefined,
+  agentFirst = undefined,
+  sessionNames = undefined,
   fs: injectedFs = undefined,
 } = {}) {
   const fs = makeFs(injectedFs);
@@ -482,6 +589,14 @@ export async function screenOutbound({
     const bannedReason = screenBannedPhrases(text);
     if (bannedReason) return blocked(bannedReason);
 
+    // (a2) Persona discipline — pure over the identity + peer registry read
+    //      here (fail-open: no identity → the name check is skipped, the
+    //      phrase check still runs). This is what makes `maestro inbox reply`,
+    //      the daemon's delivery and the org MCP tools persona-safe without a
+    //      shell hook in the loop.
+    const personaReason = screenPersona(text, personaContext(fs, agentRoot, { agentFirst, sessionNames }));
+    if (personaReason) return blocked(personaReason);
+
     // (b) AI-disclosure. The truthfulness invariant is enforced from the
     //     embedded denial list even without the file; posture resolution needs
     //     the file. Missing file → invariant still runs; posture defaults apply.

package/lib/comms/send-gate.test.mjs

@@ -24,6 +24,7 @@ import { tmpdir } from "node:os";
 import {
   screenOutbound,
   screenBannedPhrases,
+  screenPersona,
   screenDisclosure,
   screenBarriers,
   screenAllowlist,
@@ -655,3 +656,115 @@ describe("screenOutbound — real-disk read path", () => {
     }
   });
 });
+
+/* ─── persona discipline (front-door session §3.6) ─────────────────────────
+ * The agent is one persona to every human. The machinery — Claude Code, a
+ * session, a sub-session, a subagent that "said", a workflow agent, the model,
+ * an internal session name — never appears in outbound text. This screen runs
+ * inside screenOutbound so EVERY lane gets it: the daemon's delivery
+ * (`maestro inbox reply`), lib/org/messaging.sendMessage, the org MCP tools
+ * (messaging_send, email_send, email_draft_send, org_rpc) and the adapters —
+ * not only the PreToolUse shell hook.
+ */
+
+describe("screenPersona (unit)", () => {
+  for (const [label, text] of [
+    ["Claude Code", "I'll have Claude Code pick that up this afternoon."],
+    ["Claude session", "A separate claude session is running the numbers."],
+    ["sub-session", "I kicked off a sub-session for the deck."],
+    ["subagent said", "The subagent said the deploy finished."],
+    ["sub-agent reported", "My sub-agent reported two blockers."],
+    ["subagent session", "The subagent session is still going."],
+    ["workflow agent", "The workflow agent will file the summary."],
+    ["language model", "Every language model has limits, mine included."],
+  ]) {
+    it(`blocks "${label}" and names the phrase`, () => {
+      const reason = screenPersona(text);
+      assert.ok(reason, `expected a block for "${label}"`);
+      assert.match(reason, /persona leak/i);
+      assert.match(reason.toLowerCase(), new RegExp(label.toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\s+/g, "\\s+")));
+    });
+  }
+
+  it("session names are BOUNDED: <first>-main always, other <first>-<x> only when registered as a peer", () => {
+    assert.ok(screenPersona("Check with alex-main for the latest.", { first: "alex" }));
+    assert.ok(screenPersona("Ask ALEX-MAIN.", { first: "alex" }), "case-insensitive");
+    assert.equal(screenPersona("alex-research has the draft ready.", { first: "alex" }), null, "unregistered peer name: not a session name");
+    assert.ok(screenPersona("alex-research has the draft ready.", { first: "alex", sessionNames: ["alex-research"] }));
+    assert.ok(screenPersona("alex-research has the draft ready.", { sessionNames: ["alex-research"] }), "names work without a first name");
+  });
+
+  it("does not block a colleague's hyphenated name, a URL slug or an email local part that starts with the first name", () => {
+    for (const [first, text] of [
+      ["marc", "Marc-Antoine confirmed the numbers."],
+      ["james", "See https://os.cohortapp.com/spaces/james-kirkland for the thread."],
+      ["ethan", "Loop in ethan-miller@example.com on the invoice."],
+      ["alex", "Alexandra-Maine sent the invoice."],
+      ["alex", "alex-mainland is the venue."],
+    ]) {
+      assert.equal(screenPersona(text, { first }), null, `"${text}" must pass for first=${first}`);
+    }
+  });
+
+  it("colleague phrasing, the bare noun 'subagents', and the calendar sense of 'session' all pass", () => {
+    for (const text of [
+      "One of my analysts is on it; I'll have the numbers by 3.",
+      "My team has the deck in review — sending the draft after lunch.",
+      "We use subagents internally for the heavy lifting.",
+      "The session on Thursday (the board session) starts at 9.",
+      "",
+    ]) {
+      assert.equal(screenPersona(text, { first: "alex" }), null, `"${text}" must pass`);
+    }
+    assert.equal(screenPersona(null), null);
+  });
+});
+
+describe("screenOutbound — persona", () => {
+  const PERSONA_FILES = {
+    ...GOOD_FILES,
+    "config/agent.json": JSON.stringify({ firstName: "Alex", fullName: "Alex Rivera" }),
+    "state/session/peers.json": JSON.stringify([{ name: "alex-deck", muxName: "maestro-alex-deck", purpose: "deck" }]),
+  };
+
+  it("blocks a persona leak for an internal Cohort recipient (the `maestro inbox reply` lane)", async () => {
+    const res = await screenOutbound({
+      channel: "cohort",
+      recipient: "clx0123456789abcdefghij",
+      text: "My sub-session is on it, check with alex-main.",
+      agentRoot: ROOT,
+      firstContact: false,
+      fs: memFs(PERSONA_FILES),
+    });
+    assert.equal(res.allow, false);
+    assert.match(res.reason, /persona leak/i);
+    assert.match(res.reason, /sub-session/i);
+  });
+
+  it("reads the first name from config/agent.json and the peer names from state/session/peers.json under agentRoot", async () => {
+    const fs = memFs(PERSONA_FILES);
+    const main = await screenOutbound({ channel: "cohort", recipient: "clx0123456789abcdefghij", text: "alex-main will chase it.", agentRoot: ROOT, firstContact: false, fs });
+    assert.equal(main.allow, false);
+    assert.match(main.reason, /alex-main/);
+    const peer = await screenOutbound({ channel: "cohort", recipient: "clx0123456789abcdefghij", text: "alex-deck has the slides.", agentRoot: ROOT, firstContact: false, fs });
+    assert.equal(peer.allow, false, "a registered peer name is a session name");
+    const other = await screenOutbound({ channel: "cohort", recipient: "clx0123456789abcdefghij", text: "alex-research is not a peer here.", agentRoot: ROOT, firstContact: false, fs });
+    assert.equal(other.allow, true, "an unregistered <first>-x is ordinary text");
+  });
+
+  it("explicit agentFirst / sessionNames override the disk read; no identity on disk → phrase gate still applies, name gate skipped", async () => {
+    const fs = memFs(GOOD_FILES);
+    const named = await screenOutbound({ channel: "cohort", recipient: "clx0123456789abcdefghij", text: "robin-main will chase it.", agentRoot: ROOT, firstContact: false, fs, agentFirst: "Robin" });
+    assert.equal(named.allow, false);
+    const none = await screenOutbound({ channel: "cohort", recipient: "clx0123456789abcdefghij", text: "robin-main will chase it.", agentRoot: ROOT, firstContact: false, fs });
+    assert.equal(none.allow, true, "no first name resolvable → the name check is skipped (fail-open on that one check)");
+    const phrase = await screenOutbound({ channel: "cohort", recipient: "clx0123456789abcdefghij", text: "Claude Code is on it.", agentRoot: ROOT, firstContact: false, fs });
+    assert.equal(phrase.allow, false, "the phrase gate needs no identity");
+  });
+
+  it("applies to external email too", async () => {
+    const res = await screenOutbound({ channel: "email", recipient: "graham@kpm.com", text: "Our workflow agent will send the summary. I am an AI assistant, for the record.", agentRoot: ROOT, fs: memFs(PERSONA_FILES) });
+    assert.equal(res.allow, false);
+    assert.match(res.reason, /persona leak/i);
+  });
+});