@cohortapp/agent-sdk 2.5.1 → 2.6.1

package/lib/org/tool-surface.mjs

@@ -7,16 +7,24 @@
  *   - the native function-call path (`lib/tool-definitions.js` category 7 +
  *     `lib/action-executor.js` executor routing).
  *
- * 28 curated tools + 5 email tools + 5 artifact tools + 69 agent-desk tools
+ * 38 curated tools + 5 email tools + 5 artifact tools + 69 agent-desk tools
  * (mail app / files / calendar / crm / books / meetings.recapFile / directory /
  * design / call working sessions — the additive families register only when
  * the vendored protocol carries them — see emailFamilyAvailable /
- * artifactFamilyAvailable / deskFamilyAvailable) — NOT a 406-method
- * one-to-one mirror. The long tail
+ * artifactFamilyAvailable / deskFamilyAvailable) — NOT a one-to-one mirror of
+ * the 460-method protocol table. The long tail
  * stays reachable through
  * the `org_rpc` / `org_read` escape hatches, which validate against the frozen
  * protocol table before any network I/O and are deliberately `access:"admin"`.
  *
+ * WHAT "REACHABLE THROUGH THE ESCAPE HATCH" IS WORTH. `access:"admin"` puts
+ * org_rpc/org_read in the CEO tier ONLY (lib/tool-definitions.js: they are
+ * withheld from writeToolsLeadership and from the default lookup set). So for a
+ * leadership or default agent, "the long tail is reachable via org_rpc" is
+ * false — a capability with no curated tool simply does not exist for it. When
+ * a human-UI verb matters to an ordinary agent, it needs a CURATED tool; the
+ * escape hatch is not a parity argument, it is an operator's console.
+ *
  * Governance parity (spec §1.5):
  *   - Tools that emit human-visible outbound content carry `outbound: true`
  *     (exactly messaging_send + email_send + email_draft_send +
@@ -76,6 +84,11 @@ import {
   ESCALATION_SEVERITIES,
   MEMORY_CLASSES,
 } from "./param-contract.mjs";
+// Delivery receipts. A spawned session speaks to humans through THIS surface,
+// in its own process; the receipt is the only way the daemon that spawned it can
+// later tell "the session answered" from "the session exited 0 and said
+// nothing". Fail-open by construction — recordOutbound never throws.
+import { recordOutbound } from "../comms/receipts.mjs";
 
 /** Default org server origin when neither env nor config names one. */
 export const DEFAULT_COHORT_BASE = "https://os.cohortapp.com";
@@ -219,11 +232,38 @@ export const ORG_TOOLS = Object.freeze([
   {
     name: "org_directory",
     title: "Org directory",
-    description: "The org roster: members + teams from the /v1 directory read.",
+    description:
+      "The org roster: members + teams from the /v1 directory read. Each AI member carries " +
+      "`presence` — {lane, detail, lastBeatMs, lastSeenMs} — which is the SAME green/amber/grey " +
+      "dot a human sees next to that colleague, from the same server-side resolver: lane " +
+      "\"online\" = available, \"indisposed\" = alive but blocked (detail says why, in the words " +
+      "the human reads), \"offline\" = genuinely dark, \"unknown\" = never beaten. Quote `lane` " +
+      "and `detail` rather than guessing from `status`, whose `ts` is client-stamped and can be " +
+      "skewed. Human members carry presence: null — that is \"not this derivation's question\", " +
+      "NOT \"offline\".",
     input_schema: S({}),
     access: "read",
     binding: { kind: "read", path: "directory" },
   },
+  {
+    name: "org_pulse",
+    title: "What needs attention",
+    description:
+      "The founder's home surface, as the human sees it (GET /v1/ops?pulse=1): `stats` " +
+      "{agentsRunning, blocked, decisionsToday, needs}, `needs` — the attention list in the " +
+      "human's own order, severity and wording (escalations, approvals, blocked colleagues) — " +
+      "and `activity`, the last 12 live-rail sentences (each carries an `age` such as 12m or 6d — a RELATIVE age, not a timestamp; the array is newest-first). Use this to answer \"what needs my " +
+      "human right now?\" and \"what just happened?\" instead of re-deriving either from raw " +
+      "board/decision reads: this IS the number on their screen, so a re-derivation can only " +
+      "disagree with it. Org-wide and PUBLIC-channel-scoped; it deliberately carries no " +
+      "per-person mentions, threads or drafts, because this plane resolves no viewer and an " +
+      "empty \"nothing mentions you\" would be a false negative. `pulse: null` means the " +
+      "derivation failed — say so, do not report zero. Also returns the plain probe fields " +
+      "(chainHead, members, openAlerts, readyTasks).",
+    input_schema: S({}),
+    access: "read",
+    binding: { kind: "read", path: "ops", query: { pulse: "1" } },
+  },
   {
     name: "org_snapshot",
     title: "Org snapshot",
@@ -274,12 +314,20 @@ export const ORG_TOOLS = Object.freeze([
     title: "Send org message",
     description:
       "Post a message into an org channel (messaging.send). Send-gate screened locally; " +
-      "the server enforces channel ACLs + pairing. An idempotencyId is auto-minted for dedup.",
+      "the server enforces channel ACLs + pairing. An idempotencyId is auto-minted for dedup. " +
+      "`mentions` TAGS people — an @mention is what turns a message in a busy room into an ask " +
+      "someone is accountable for answering; without it the message is decoration. Pass member " +
+      "ids; they are normalised to the {memberId} objects hq validates.",
     input_schema: S(
       {
         channelId: str("Channel id (use messaging_open_dm for a member DM)."),
         body: str("Message body."),
         threadRootId: str("Reply under this thread root (optional)."),
+        mentions: arr(
+          { type: "string" },
+          "Member ids to @mention. Tag only the people who must ACT — a mention is a claim on " +
+            "someone's attention, and tagging bystanders is how a room gets muted.",
+        ),
       },
       ["channelId", "body"],
     ),
@@ -297,6 +345,244 @@ export const ORG_TOOLS = Object.freeze([
     access: "write",
     binding: { kind: "rpc", method: "channel.resolveOrCreateDm" },
   },
+  {
+    name: "messaging_open_group",
+    title: "Open a group conversation",
+    description:
+      "Open a conversation with two or more people (channel.createConversation) and get back a " +
+      "channelId for messaging_send. One other person collapses to the deterministic 1:1 DM; two " +
+      "or more creates a GROUP_DM. Use this when several people must decide something TOGETHER — " +
+      "if they only need to know separately, DM them, and if a room already holds all of them, " +
+      "post there instead. A new room is the most expensive thing you can make: everyone in it " +
+      "carries it forever.",
+    input_schema: S(
+      {
+        memberIds: arr({ type: "string" }, "The people to put in the room (not yourself)."),
+        name: str("Optional room name — say what the room is FOR, not who is in it."),
+      },
+      ["memberIds"],
+    ),
+    access: "write",
+    binding: { kind: "rpc", method: "channel.createConversation" },
+  },
+  {
+    name: "messaging_create_channel",
+    title: "Create a channel",
+    description:
+      "Create a named org channel (channel.create). Reach for this ONLY when the work is durable " +
+      "and the audience standing — a channel is permanent and sits in everyone's sidebar. For a " +
+      "one-off decision use messaging_open_group. Slug must be lowercase alphanumerics + hyphens.",
+    input_schema: S(
+      {
+        slug: str("URL-safe slug: lowercase alphanumerics and hyphens."),
+        name: str("Human name."),
+        kind: str("PUBLIC | PRIVATE (default PRIVATE)."),
+        topic: str("What this channel is for."),
+        members: arr({ type: "string" }, "Member ids to seat alongside you."),
+      },
+      ["slug", "name"],
+    ),
+    access: "write",
+    binding: { kind: "rpc", method: "channel.create" },
+  },
+  {
+    name: "messaging_add_to_channel",
+    title: "Add someone to a channel",
+    description:
+      "Add a member to a channel you are already in (channel.addMember). Idempotent — re-adding " +
+      "is a no-op. Prefer this over creating a second room when the conversation is already " +
+      "happening somewhere and one more person needs to be in it.",
+    input_schema: S({ channelId: str("Channel id."), memberId: str("Who to add.") }, ["channelId", "memberId"]),
+    access: "write",
+    binding: { kind: "rpc", method: "channel.addMember" },
+  },
+  {
+    name: "engage_colleagues",
+    title: "Bring the right people in",
+    description:
+      "Decide whether anyone actually needs to be pulled into a piece of work — and if so WHO and " +
+      "in WHICH surface — then do it. This is the judged path: it applies one threshold (engage " +
+      "only when a specific named person's action or consent is a PRECONDITION for the work to " +
+      "proceed or be safe, and you cannot supply it yourself), resolves the addressee from the org " +
+      "directory rather than guessing, picks the cheapest surface that reaches them (reply in " +
+      "place > DM > an existing room > a new room), tags them, and refuses to repeat an ask that " +
+      "is already outstanding. It will frequently decide NOBODY needs involving and say so — that " +
+      "is the tool working, not failing. Use it instead of hand-rolling a DM whenever you are " +
+      "blocked, need consent for something irreversible or external, need a required review, or " +
+      "have to tell someone a commitment to them is going to slip. Describe the work honestly: " +
+      "`selfServeExhausted` must be true for a blocked ask, because asking a human for something " +
+      "you could still work out yourself is outsourcing your own job.",
+    input_schema: S(
+      {
+        id: str("Stable id for this piece of work (used to dedupe and rate-limit)."),
+        title: str("One line naming the work."),
+        summary: str("What is going on, in the words the reader needs."),
+        state: str("in_progress | blocked | failed | done."),
+        scope: str("Subject area — used to find who owns it when nobody is named."),
+        blockerKind: str("decision | access | information | approval | capacity."),
+        blockerDetail: str("Exactly what is missing."),
+        blockerOwnerId: str("Member id, if you already know whose it is."),
+        selfServeExhausted: {
+          type: "boolean",
+          description: "True only if you have genuinely exhausted what you can do alone.",
+        },
+        irreversible: { type: "boolean", description: "The next step cannot be undone." },
+        external: { type: "boolean", description: "The next step leaves the org." },
+        financial: { type: "boolean", description: "The next step spends money." },
+        reviewRequired: { type: "boolean", description: "A policy or role requires sign-off." },
+        reviewerId: str("The required reviewer, if named."),
+        commitmentToMemberId: str("Who you promised this to."),
+        commitmentAtRisk: { type: "boolean", description: "That promise will be missed." },
+        channelId: str("Where the ask came from, so a reply lands in context."),
+        threadRootId: str("The thread it came from."),
+        requesterId: str("Who asked."),
+        question: str("The single question you need answered."),
+        options: arr({ type: "string" }, "Two or more concrete choices, if it is a decision."),
+        tried: arr({ type: "string" }, "What you already tried — this is what stops it reading as lazy."),
+        interestedParties: arr(
+          { type: "string" },
+          "People who might like to know but whose actions do NOT change. They are recorded as " +
+            "considered-and-declined, never messaged.",
+        ),
+        durable: { type: "boolean", description: "If a new room is needed, make it a named channel." },
+      },
+      ["id", "title", "state"],
+    ),
+    access: "write",
+    // Deliberately NOT `outbound: true`. The send-gate still runs on every
+    // message this tool produces — inside `messaging.sendMessage`, which is the
+    // one shared chokepoint — and it screens the COMPOSED BODY. Screening here
+    // instead would screen the work description, which is not what gets sent:
+    // the fallback shape stringifies the whole input blob, so the gate would be
+    // judging JSON that never reaches anybody while the real prose went
+    // unexamined. One gate, on the actual text.
+    binding: { kind: "local" },
+  },
+  // ── per-message actions ──────────────────────────────────────────────────
+  // The human long-press action sheet (react · reply · save · mark unread ·
+  // delete) had no curated counterpart: an agent could SEND into a room but
+  // could not react to, retract, bookmark or unread anything in it. The long
+  // tail was nominally reachable through org_rpc, but org_rpc is access:"admin"
+  // and lands only in the CEO tier (lib/tool-definitions.js), so for every
+  // leadership/default agent these verbs did not exist at all. They are
+  // always-on rather than desk-gated: the base `calling`/`messaging`/`channel`
+  // families have been vendored since SP3, so probing a newer method would
+  // withhold them on a protocol that carries them perfectly well.
+  {
+    name: "messaging_react",
+    title: "React to a message",
+    description:
+      "Add or remove YOUR reaction on a message (messaging.react). You must belong to the " +
+      "message's channel. Idempotent: re-adding the same emoji is a no-op, as is removing one " +
+      "you never added. Use a reaction where a reply would just be noise (acknowledging, " +
+      "voting, signalling 'seen') — it is the lightest honest signal you have.",
+    input_schema: S(
+      {
+        messageId: str("Message id."),
+        emoji: str("The emoji (or short name), e.g. \"✅\"."),
+        op: str("add (default) | remove."),
+      },
+      ["messageId", "emoji"],
+    ),
+    access: "write",
+    binding: { kind: "rpc", method: "messaging.react" },
+  },
+  {
+    name: "messaging_bookmark",
+    title: "Save a message",
+    description:
+      "Save a message to YOUR bookmarks (messaging.bookmark) — the Save row on the human " +
+      "action sheet. Private to you; it neither notifies the author nor changes the room.",
+    input_schema: S({ messageId: str("Message id.") }, ["messageId"]),
+    access: "write",
+    binding: { kind: "rpc", method: "messaging.bookmark" },
+  },
+  {
+    name: "messaging_delete",
+    title: "Delete your message",
+    description:
+      "Soft-delete a message you AUTHORED (messaging.delete) — the body is redacted, the " +
+      "audit trail is not. You cannot delete a colleague's message. Use this to retract " +
+      "something you posted in error; say so in the room rather than deleting silently.",
+    input_schema: S({ messageId: str("Message id (must be yours).") }, ["messageId"]),
+    access: "write",
+    binding: { kind: "rpc", method: "messaging.delete" },
+  },
+  {
+    name: "messaging_mark_unread_from",
+    title: "Mark a room unread from here",
+    description:
+      "Move YOUR OWN read cursor in a channel back to just before a message " +
+      "(channel.markUnreadFrom), so everything from it onward recomputes as unread — the " +
+      "human 'Mark unread from here'. Affects only your cursor; nobody else's badge moves.",
+    input_schema: S(
+      {
+        channelId: str("Channel id."),
+        fromTimestamp: str("ISO datetime of the message to become the first unread one."),
+      },
+      ["channelId", "fromTimestamp"],
+    ),
+    access: "write",
+    binding: { kind: "rpc", method: "channel.markUnreadFrom" },
+  },
+  // ── huddles ──────────────────────────────────────────────────────────────
+  // The human surfaces collapsed audio+video onto ONE headphones control, and a
+  // calendar Join and an impromptu huddle resolve to the SAME room. The agent
+  // surface had the working-session tools (share/step/end) but no way to OPEN
+  // or ENTER the room they present into — a share tool whose callId nothing
+  // curated could produce.
+  {
+    name: "org_huddle_start",
+    title: "Start a huddle",
+    description:
+      "Open a live huddle (calling.start) — either anchored to a CHANNEL (every member of " +
+      "that room can walk in; you must belong to it) or as a direct call to named " +
+      "participantIds. Returns {callId, token, room}; feed callId to org_huddle_join for " +
+      "others, or to the share tools to present a surface. Give at least one of channelId or " +
+      "participantIds. Announce it in the room first — a huddle that opens unannounced is a " +
+      "ring nobody expected.",
+    input_schema: S(
+      {
+        channelId: str("Anchor the huddle to this channel (you must be a member)."),
+        participantIds: arr({ type: "string" }, "Member ids to ring (direct call)."),
+        kind: str("ONE_ON_ONE (default) | GROUP | CHANNEL."),
+      },
+      [],
+    ),
+    access: "write",
+    binding: { kind: "rpc", method: "calling.start" },
+  },
+  {
+    name: "org_huddle_join",
+    title: "Join a huddle",
+    description:
+      "Join a live call you were invited to, or any huddle anchored to a channel you belong " +
+      "to (calling.join). Idempotent — rejoining returns a fresh token. Refused when the host " +
+      "has LOCKED the floor, when you were removed, or when the call has ended; relay that " +
+      "reason plainly rather than retrying.",
+    input_schema: S(
+      {
+        callId: str("Live call id."),
+        audioOnly: bool("Join without video (default false)."),
+      },
+      ["callId"],
+    ),
+    access: "write",
+    binding: { kind: "rpc", method: "calling.join" },
+  },
+  {
+    name: "org_huddle_end",
+    title: "End a huddle",
+    description:
+      "End a live huddle for EVERYONE and tear down its room (calling.end) — the close half of " +
+      "org_huddle_start, so a huddle you opened is never a room you cannot shut. Only a " +
+      "PARTICIPANT may end a call; ending one that has already ended returns CONFLICT, which " +
+      "means it is already closed, not that you failed. This ends the call for everybody, not " +
+      "just for you — say so in the room first.",
+    input_schema: S({ callId: str("Live call id.") }, ["callId"]),
+    access: "write",
+    binding: { kind: "rpc", method: "calling.end" },
+  },
   // ── board / tasks ────────────────────────────────────────────────────────
   {
     name: "board_ready",
@@ -418,6 +704,50 @@ export const ORG_TOOLS = Object.freeze([
     access: "write",
     binding: { kind: "rpc", method: "board.addTaskComment" },
   },
+  {
+    name: "work_track",
+    title: "Show your working",
+    description:
+      "Record where you are on the ask you are currently handling (board.track). The daemon " +
+      "already opens the board row when it takes the ask on and closes it when the session ends " +
+      "— you do NOT need to do either. Use this MID-WORK, when something a waiting human would " +
+      "want to know changes: you have started the substantive part (stage 'working'), you are " +
+      "stuck on something outside your control (stage 'blocked' — say what you need, and pass " +
+      "`notify` with the member id of whoever can unstick it), or the work is finished but wants " +
+      "a human's eyes (stage 'review'). Pass `channelId` and `messageId` of the message that " +
+      "asked, so this lands on the SAME row rather than opening a second one; the server dedupes " +
+      "on that pair, so a repeated call is free. Attach what you produced with `attachments`. " +
+      "Do not narrate every step — a comment per meaningful change, not per file edited.",
+    input_schema: S(
+      {
+        channelId: str("The channel the ask arrived on."),
+        messageId: str("The id of the message that asked. Identifies the board row."),
+        stage: {
+          type: "string",
+          enum: ["working", "blocked", "review"],
+          description:
+            "Where the work now stands. 'working' = started; 'blocked' = stuck and needs someone; " +
+            "'review' = finished, needs a human's eyes.",
+        },
+        note: str("What changed, in a sentence or two, for the person waiting."),
+        notify: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Member ids to @-tag on this step — the people who genuinely need to act or know. " +
+            "Tagging everyone teaches everyone to ignore the tag.",
+        },
+        attachments: {
+          type: "array",
+          description: "Files this step produced: [{name, mimeType?, sizeBytes?, dataUrl}].",
+          items: { type: "object" },
+        },
+      },
+      ["channelId", "messageId", "stage"],
+    ),
+    access: "write",
+    binding: { kind: "rpc", method: "board.track" },
+  },
   // ── decisions / approvals ────────────────────────────────────────────────
   {
     name: "decision_list",
@@ -505,11 +835,43 @@ export const ORG_TOOLS = Object.freeze([
     title: "Search org knowledge",
     description:
       "Search the ACL'd shared org knowledge plane (knowledge.search). Every retrieval is " +
-      "audit-logged server-side; the server decides what this agent may see.",
+      "audit-logged server-side; the server decides what this agent may see. This is the " +
+      "NARROW view — shared facts only. Prefer memory_recall, which is the same index with " +
+      "your own perspective, scope/entity/time controls and drill-down pointers.",
     input_schema: S({ query: str("Free-text query."), limit: num("Max hits (optional).") }, ["query"]),
     access: "read",
     binding: { kind: "rpc", method: "knowledge.search" },
   },
+  {
+    name: "memory_recall",
+    title: "Recall from memory",
+    description:
+      "Layered semantic recall over your unified agent memory (memory.recall) — the SAME " +
+      "recall the chat lane's colleagues use, so a seat driven from here reasons off the same " +
+      "memory as the same colleague in a channel. Read-only. Defaults to org-wide; `scope: " +
+      "\"self\"` narrows to your own perspective, `channelId` to one room, and refType+refId " +
+      "(given TOGETHER) pins one entity and wins over scope. `depth: \"specific\"` for a " +
+      "pinpoint fact, \"broad\" for context. ACL is server-side and fail-closed: the seat is " +
+      "your own key's, never a parameter, so you cannot recall another colleague's private " +
+      "view. An unkeyed embedder or an empty index returns {found:false, items:[]} — that is " +
+      "an honest \"nothing indexed\", not an error to retry.",
+    input_schema: S(
+      {
+        query: str("What to recall (2–500 chars)."),
+        scope: str("org (default) | self."),
+        channelId: str("Narrow to one channel (overrides scope)."),
+        refType: str("Entity type to pin (with refId; wins over scope)."),
+        refId: str("Entity id to pin (with refType)."),
+        since: str("ISO datetime lower bound."),
+        until: str("ISO datetime upper bound."),
+        depth: str("broad | specific."),
+        k: num("Max items, 1–25."),
+      },
+      ["query"],
+    ),
+    access: "read",
+    binding: { kind: "rpc", method: "memory.recall" },
+  },
   {
     name: "knowledge_append",
     title: "Append org knowledge",
@@ -859,8 +1221,13 @@ export const ORG_TOOLS = Object.freeze([
     name: "email_triage",
     title: "Triage mail thread",
     description:
-      "One triage facet per call (email.triage): set priority (P0|P1|P2), category, tags, " +
-      "starred, read, OR assigneeMemberId — the same one-verb-per-call rule the Inbox UI applies.",
+      "One triage facet per call (email.triage): priority (P0|P1|P2) + category + tags, OR " +
+      "assigneeMemberId, OR muted, OR done — the same one-verb-per-call rule the Inbox UI " +
+      "applies (the server refuses combinations with BAD_REQUEST). starred / read / " +
+      "unreadFromMessageId ride alongside the first two, but read and unreadFromMessageId are " +
+      "mutually exclusive (both move the same read cursor). muted = no pings or badges, still " +
+      "filed; done = cleared from the working list (false reopens); unreadFromMessageId = the " +
+      "long-press 'Mark unread' a human gets on ONE message, leaving everything above it read.",
     input_schema: S(
       {
         threadId: str("Thread id."),
@@ -868,7 +1235,12 @@ export const ORG_TOOLS = Object.freeze([
         category: str("Category label (optional)."),
         tags: arr({ type: "string" }, "Replace the tag set (≤12; optional)."),
         starred: bool("Star/unstar."),
-        read: bool("Mark read/unread."),
+        read: bool("Mark the whole thread read/unread."),
+        unreadFromMessageId: str(
+          "Mark unread FROM this message down (per-message granularity; exclusive with read).",
+        ),
+        muted: bool("Mute/unmute — stays filed, stops pinging."),
+        done: bool("Mark done (true) or reopen (false); alone in its call."),
         assigneeMemberId: str("Assign to this member (null to unassign)."),
       },
       ["threadId"],
@@ -2448,7 +2820,54 @@ function readToFrame(r) {
  *                         screenImpl?, bumpImpl? } (injectables for tests)
  * @returns {Promise<object>} res frame
  */
+/**
+ * Which org tools put words in front of a human, and where to find the room.
+ *
+ * A spawned session is a separate `claude` process: when it answers the user,
+ * the daemon that spawned it learns nothing. That is why the daemon used to
+ * treat exit 0 as proof of a reply and mark the ask handled forever — including
+ * the observed case of a 241-second session whose own final text was "Nothing
+ * was sent." A receipt written here crosses the process boundary and lets the
+ * daemon ask the real question instead of the convenient one.
+ */
+const HUMAN_FACING_TOOLS = {
+  messaging_send: (i) => i.channelId || i.channel,
+  email_send: (i) => i.to || (Array.isArray(i.recipients) ? i.recipients[0] : null),
+  email_reply: (i) => i.to || i.threadId,
+};
+
+/**
+ * Execute an org tool and, when it was one that speaks to a person and it
+ * succeeded, leave a delivery receipt.
+ *
+ * Strictly observational: the receipt is written AFTER the frame is resolved and
+ * only on success, it cannot alter the frame, and any failure writing it is
+ * swallowed by `recordOutbound` itself. A bookkeeping fault must never break a
+ * send — but the absence of a receipt is read as "the human heard nothing",
+ * which errs toward one extra message rather than silence.
+ */
 export async function executeOrgTool(name, input = {}, o = {}) {
+  const frame = await executeOrgToolInner(name, input, o);
+  try {
+    const locate = HUMAN_FACING_TOOLS[name];
+    if (locate && frame && frame.ok) {
+      const channel = locate(input || {});
+      if (channel) {
+        recordOutbound({
+          service: name.startsWith("email") ? "gmail" : "cohort",
+          channel,
+          kind: "session",
+          via: name,
+          chars: typeof (input && input.body) === "string" ? input.body.length : null,
+          agentRoot: (o && o.agentRoot) || process.env.AGENT_ROOT || process.env.AGENT_DIR,
+        });
+      }
+    }
+  } catch { /* never let a receipt break a send */ }
+  return frame;
+}
+
+async function executeOrgToolInner(name, input = {}, o = {}) {
   try {
     const cfg = resolveOrgToolConfig(o);
     // A curated tool first; else a granted integration tool from the disk cache
@@ -2507,6 +2926,78 @@ export async function executeOrgTool(name, input = {}, o = {}) {
       case "org_whoami":
         return whoami(cfg, { fetchImpl: o.fetchImpl, env: o.env || process.env });
 
+      case "engage_colleagues": {
+        // The judged path. `engage` loads the directory + rooms + this agent's
+        // engagement history, applies the threshold, and either sends or records
+        // why it didn't. Both outcomes come back as an OK frame carrying the
+        // reasoning: "nobody needed involving" is an answer, not an error, and
+        // returning it as an error would teach the model to retry until it
+        // manages to interrupt somebody.
+        const { engage } = await import("./engagement.mjs");
+        const i = input || {};
+        const work = {
+          id: String(i.id || ""),
+          title: String(i.title || ""),
+          summary: i.summary ? String(i.summary) : "",
+          scope: i.scope ? String(i.scope) : "",
+          state: String(i.state || "in_progress"),
+          durable: i.durable === true,
+          selfServeExhausted: i.selfServeExhausted === true,
+          ...(i.blockerKind || i.blockerDetail || i.blockerOwnerId
+            ? {
+                blocker: {
+                  kind: String(i.blockerKind || "information"),
+                  scope: i.scope ? String(i.scope) : "",
+                  detail: i.blockerDetail ? String(i.blockerDetail) : "",
+                  ownerId: i.blockerOwnerId ? String(i.blockerOwnerId) : null,
+                },
+              }
+            : {}),
+          risk: { irreversible: i.irreversible === true, external: i.external === true, financial: i.financial === true },
+          ...(i.reviewRequired || i.reviewerId
+            ? { review: { required: i.reviewRequired === true, reviewerId: i.reviewerId ? String(i.reviewerId) : null } }
+            : {}),
+          ...(i.commitmentToMemberId
+            ? { commitment: { toMemberId: String(i.commitmentToMemberId), atRisk: i.commitmentAtRisk === true } }
+            : {}),
+          origin: {
+            channelId: i.channelId ? String(i.channelId) : null,
+            threadRootId: i.threadRootId ? String(i.threadRootId) : null,
+            requesterId: i.requesterId ? String(i.requesterId) : null,
+          },
+          question: i.question ? String(i.question) : "",
+          options: Array.isArray(i.options) ? i.options.map(String) : [],
+          tried: Array.isArray(i.tried) ? i.tried.map(String) : [],
+          interestedParties: Array.isArray(i.interestedParties) ? i.interestedParties.map(String) : [],
+        };
+        if (!work.id || !work.title) return errFrame("BAD_REQUEST", "engage_colleagues: id and title are required");
+        // Own member id, so the judgement never routes the ask back to this
+        // seat. Unresolvable is survivable — `resolveTargets` only uses it to
+        // exclude self and to find a supervisor edge.
+        const envv = o.env || process.env;
+        const me = String(envv.COHORT_AGENT_ID || envv.COHORT_MEMBER_ID || "");
+        const run = await engage(work, {
+          cfg: { org: { cohort: { enabled: true, base: cfg.base, token: cfg.token, orgId: cfg.orgId, agentId: me } } },
+          agentRoot: cfg.agentRoot,
+          me,
+          fetchImpl: o.fetchImpl,
+        });
+        const d = run.decision || {};
+        return okFrame({
+          engaged: run.engaged,
+          outcome: run.outcome,
+          surface: run.surface,
+          channelId: run.channelId,
+          trigger: d.trigger || null,
+          reasonCode: d.reasonCode || null,
+          reason: d.reason || null,
+          targets: (d.targets || []).map((t) => ({ memberId: t.memberId, name: t.name, rung: t.rung, why: t.why })),
+          consideredNotEngaged: d.consideredNotEngaged || [],
+          why: d.why || [],
+          error: run.error || null,
+        });
+      }
+
       case "org_events_tail": {
         const q = {};
         if (input && input.cursor != null) q.cursor = input.cursor;
@@ -2562,7 +3053,12 @@ export async function executeOrgTool(name, input = {}, o = {}) {
       default: {
         const binding = def.binding || {};
         if (binding.kind === "read") {
-          return readToFrame(await read(binding.path, callOpts));
+          // `binding.query` lets a curated tool PIN a read's query params (e.g.
+          // org_pulse → ops?pulse=1). The alternative — telling every agent to
+          // pass ?pulse=1 through org_read — is not reachable at all below the
+          // CEO tier, since org_read is access:"admin". Same encoder org_read
+          // uses, so one read path cannot encode two ways.
+          return readToFrame(await read(withQuery(binding.path, binding.query), callOpts));
         }
         if (binding.kind === "rpc") {
           // SP5: a granted integration tool proxies to integration.invokeTool