@cohortapp/agent-sdk 2.10.0 → 2.11.1

package/lib/org/tool-access.test.mjs

@@ -0,0 +1,144 @@
+/**
+ * tool-access.test.mjs — the access-tier mechanism, and the two silent failures
+ * it exists to close.
+ *
+ * REGRESSION 1 — THE ADMIN TRAPDOOR. `access:"admin"` is the CEO-only tier
+ * (lib/tool-definitions.js withholds it from writeToolsLeadership AND from the
+ * default lookup set). A CAPABILITY parked there is shipped and dark for every
+ * seat below the operator's console — the exact state tool-surface.mjs's header
+ * describes when it says "for a leadership or default agent, 'the long tail is
+ * reachable via org_rpc' is false". The rule against it used to live in
+ * per-delta hand-listed name arrays, so it guarded the names someone
+ * remembered. ADMIN_TOOLS makes the tier a closed set instead.
+ *
+ * REGRESSION 2 — THE TYPO TRAPDOOR. The tiers were bucketed by exact string
+ * equality, so an entry whose `access` was missing or mis-cased matched no
+ * bucket and reached NO native tier at all, while the MCP plane kept publishing
+ * it. That is the tool-side twin of the caller-side footgun `normalizeAccessLevel`
+ * already fixes ("'CEO' yielded zero tools, a silent UNDER-privilege footgun").
+ * The test below drives the OLD comparison and the NEW one over the same bad
+ * row so the difference is on the record.
+ *
+ * Hermetic, no network, no env. Run: node --test lib/org/tool-access.test.mjs
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { METHODS } from "./protocol.mjs";
+import {
+  TOOL_ACCESS_LEVELS,
+  MOST_RESTRICTED_ACCESS,
+  ADMIN_TOOLS,
+  expectedAccessFor,
+  normalizeToolAccess,
+  partitionByAccess,
+} from "./tool-access.mjs";
+
+// ── the derivation ─────────────────────────────────────────────────────────
+
+test("expectedAccessFor derives the tier from the protocol SCOPE, not from sideEffecting", () => {
+  assert.equal(expectedAccessFor("resource.list"), "read");
+  assert.equal(expectedAccessFor("resource.create"), "write");
+
+  // The five audited reads: side-effecting (they land on the chain or the AI
+  // meter) yet `.read`-scoped on purpose, because a VIEWER seat may run them —
+  // exactly the ability its human seat has. hq keeps the same list under
+  // AUDITED_READ_SCOPE_WRITES. A sideEffecting-derived rule would demote every
+  // one of them out of the lookup set that every tier gets.
+  for (const m of [
+    "knowledge.search",
+    "directory.ask",
+    "branding.renderTemplate",
+    "branding.rewriteInVoice",
+    "branding.exportKit",
+  ]) {
+    assert.equal(METHODS[m].sideEffecting, true, `${m} is side-effecting`);
+    assert.equal(expectedAccessFor(m), "read", `${m} is nonetheless a read-tier tool`);
+  }
+
+  // The mirror case: not side-effecting, but write-scoped.
+  assert.equal(METHODS["artifact.create"].sideEffecting, false);
+  assert.equal(expectedAccessFor("artifact.create"), "write");
+
+  // Scopes that are neither `.read` nor `.write` (board.work, approval.request,
+  // mandate.propose) are writes — they are not callable by a read-only seat.
+  assert.equal(expectedAccessFor("board.claim"), "write");
+  assert.equal(expectedAccessFor("approval.request"), "write");
+  assert.equal(expectedAccessFor("mandate.propose"), "write");
+
+  // An unknown method is null, not a guess — the caller decides how loud to be.
+  assert.equal(expectedAccessFor("nope.nothing"), null);
+  assert.equal(expectedAccessFor(""), null);
+});
+
+// ── the admin trapdoor ─────────────────────────────────────────────────────
+
+test("ADMIN_TOOLS is the closed set of escape hatches — two names, both consoles", () => {
+  assert.deepEqual([...ADMIN_TOOLS].sort(), ["org_read", "org_rpc"]);
+  assert.equal(ADMIN_TOOLS.has("resource_create"), false);
+  // Frozen: a runtime widening would be a privilege change with no diff.
+  assert.throws(() => ADMIN_TOOLS.add("resource_create"));
+});
+
+// ── the typo trapdoor ──────────────────────────────────────────────────────
+
+test("normalizeToolAccess forgives casing/whitespace — 'Read' must not mean 'nowhere'", () => {
+  for (const good of TOOL_ACCESS_LEVELS) assert.equal(normalizeToolAccess(good, "t", () => {}), good);
+  assert.equal(normalizeToolAccess("Read", "t", () => {}), "read");
+  assert.equal(normalizeToolAccess(" WRITE ", "t", () => {}), "write");
+  assert.equal(normalizeToolAccess("Admin", "t", () => {}), "admin");
+});
+
+test("an unrecognised tier fails CLOSED and NOISY, never invisible", () => {
+  for (const bad of [undefined, null, "", "readonly", 7, {}, []]) {
+    const warnings = [];
+    const got = normalizeToolAccess(bad, "broken_tool", (m) => warnings.push(m));
+    assert.equal(got, MOST_RESTRICTED_ACCESS, `${JSON.stringify(bad)} → most-restricted`);
+    assert.equal(warnings.length, 1, `${JSON.stringify(bad)} warns exactly once`);
+    assert.match(warnings[0], /broken_tool/, "the warning names the bad row so it is findable");
+  }
+});
+
+test("a throwing warn sink cannot take the tool table down", () => {
+  assert.equal(
+    normalizeToolAccess("nonsense", "t", () => {
+      throw new Error("logger exploded");
+    }),
+    MOST_RESTRICTED_ACCESS,
+  );
+});
+
+test("REGRESSION: the old equality bucketing dropped a bad row from EVERY tier", () => {
+  const table = [
+    { name: "good_read", access: "read" },
+    { name: "good_write", access: "write" },
+    { name: "mis_cased", access: "Read" }, // a plausible table typo
+    { name: "no_access" }, // an entry someone forgot to tier
+  ];
+
+  // What the code used to do, verbatim: three independent equality filters.
+  const oldBuckets = ["read", "write", "admin"].map((a) => table.filter((t) => t.access === a));
+  const oldReach = new Set(oldBuckets.flat().map((t) => t.name));
+  assert.equal(oldReach.has("mis_cased"), false, "the old filter lost a mis-cased row…");
+  assert.equal(oldReach.has("no_access"), false, "…and an untiered one");
+  assert.equal(oldReach.size, 2, "two of four tools reached no access level at all, silently");
+
+  // What it does now: an exhaustive partition. Nothing is dropped.
+  const warnings = [];
+  const now = partitionByAccess(table, (m) => warnings.push(m));
+  assert.equal(now.read.length + now.write.length + now.admin.length, table.length, "exhaustive");
+  assert.deepEqual(now.read.map((t) => t.name), ["good_read", "mis_cased"], "casing recovered into its real tier");
+  assert.deepEqual(now.admin.map((t) => t.name), ["no_access"], "the untiered row fails closed, not open");
+  assert.equal(warnings.length, 1, "and exactly the untiered row is reported");
+  assert.match(warnings[0], /no_access/);
+});
+
+test("partitionByAccess survives a null/empty table (fail-open, like the rest of the client)", () => {
+  const empty = partitionByAccess(null, () => {});
+  assert.deepEqual(empty, { read: [], write: [], admin: [] });
+  const nullish = partitionByAccess([null, undefined], () => {});
+  assert.equal(nullish.admin.length, 2, "a null row is tiered, not thrown on");
+});

package/lib/org/tool-surface.mjs

@@ -7,16 +7,30 @@
  *   - the native function-call path (`lib/tool-definitions.js` category 7 +
  *     `lib/action-executor.js` executor routing).
  *
- * 38 curated tools + 5 email tools + 5 artifact tools + 69 agent-desk tools
+ * 54 curated tools + 5 email tools + 5 artifact tools + 77 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 one-to-one mirror of
- * the 460-method protocol table. The long tail
+ * design / call working sessions / venture deliverables — the additive families
+ * register only when the vendored protocol carries them — see
+ * emailFamilyAvailable / artifactFamilyAvailable / deskFamilyAvailable) — NOT a
+ * one-to-one mirror of the 483-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"`.
  *
+ * THE DESKS ARE HAND-WRITTEN; THE RESOURCE DESK IS NOT. Every block below down
+ * to "calls" transcribes hq's op list by hand, which is precisely why hq
+ * exposes 239 ops across 11 families and this table exposed 69 across 9 (files
+ * 29 vs 7, crm 44 vs 8). The `resource_*` block is GENERATED from the vendored
+ * protocol declaration by lib/org/resource-tools.mjs and parity-tested against
+ * it, so it cannot drift that way; it is the pattern the older blocks should
+ * migrate to.
+ *
+ * ACCESS IS DERIVED, NOT DECLARED. For an rpc-bound tool the tier is a pure
+ * function of the method's protocol scope (`expectedAccessFor`), and `admin` is
+ * a CLOSED set of two escape hatches (`ADMIN_TOOLS`) rather than whatever a
+ * table author typed. lib/org/tool-access.mjs records the two silent failures
+ * the old hand-written literals allowed.
+ *
  * 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
@@ -67,6 +81,14 @@ import {
   okFrame,
   errFrame,
 } from "./protocol.mjs";
+// The access tier of an rpc-bound tool is DERIVED from its protocol scope, and
+// the admin tier is a closed, named set — see lib/org/tool-access.mjs for the
+// two silent failures that hand-written `access` literals used to allow.
+import { ADMIN_TOOLS, expectedAccessFor, normalizeToolAccess } from "./tool-access.mjs";
+// The resource desk is GENERATED from the protocol declaration, never
+// hand-copied — the mechanism that produced hq's 239 ops against 69 curated
+// tools (files 29 vs 7, crm 44 vs 8) is two tables written twice by hand.
+import { RESOURCE_TOOLS } from "./resource-tools.mjs";
 import {
   loadOrgConfig,
   configFromAgent,
@@ -181,6 +203,10 @@ const DESK_PROBES = Object.freeze({
   // OLD calling method would light these tools up on a protocol that lacks
   // the app-share surface.
   calls: "calling.appShareStart",
+  // 2026-08 venture deliverables. Probes resource.list — the family landed
+  // whole (declaration first, handlers second), so any vendored protocol that
+  // carries one resource method carries all eight.
+  resource: "resource.list",
 });
 
 /**
@@ -335,6 +361,41 @@ export const ORG_TOOLS = Object.freeze([
     outbound: true,
     binding: { kind: "rpc", method: "messaging.send" },
   },
+  {
+    name: "messaging_send_voice_note",
+    title: "Send a voice note",
+    description:
+      "Speak. Records `text` as an audio VOICE NOTE in your OWN designed voice and posts it into a " +
+      "channel — a real voice note in the feed with a waveform, exactly like a human's. Use it whenever " +
+      "someone ASKS you to speak ('send me a voicenote with this update', 'record me a quick summary', " +
+      "'say that out loud'); you can do this even though the request itself arrived as text. Keep `text` " +
+      "short and plain — speech cannot carry code, tables, links or long lists, so leave those to `body` " +
+      "(the written message the recording rides on; defaults to `text`). REFUSES honestly when this " +
+      "deployment has no speech key, when your seat has no designed voice of its own, or when you have " +
+      "used the hour's recordings: relay that reason, never promise audio you cannot produce.",
+    input_schema: S(
+      {
+        channelId: str("Channel id (use messaging_open_dm for a member DM)."),
+        text: str("The words to SPEAK aloud. Plain prose, no markdown, no URLs."),
+        body: str("The written message body it rides on. Defaults to `text`."),
+        threadRootId: str("Reply under this thread root (optional)."),
+      },
+      ["channelId", "text"],
+    ),
+    access: "write",
+    // Outbound-screened like messaging_send: the spoken words and the written
+    // body are both content a human receives, and the audio is the harder of
+    // the two to retract once heard. The screen runs on BOTH strings before a
+    // single billable character is synthesised — see outboundScreenShape.
+    outbound: true,
+    // LOCAL, not a bare rpc binding: the capability is two hq methods
+    // (synthesize → send), split there because speech synthesis is a 20s
+    // provider round-trip that cannot ride hq's 5s transactional send lane. The
+    // model should not have to know that, so the seam is hidden here rather
+    // than in the prompt. The POST leg is plain messaging.send — same ACL, same
+    // audit row, same dedup as any typed message.
+    binding: { kind: "local" },
+  },
   {
     name: "messaging_open_dm",
     title: "Open a DM",
@@ -917,6 +978,67 @@ export const ORG_TOOLS = Object.freeze([
     access: "write",
     binding: { kind: "rpc", method: "memory.author" },
   },
+  // ── preferences: the durable facts hq already injects for free ───────────
+  // hq built the `preference.*` family FOR this plane and said so in the
+  // handler ("an SDK-driven agent could LEARN a durable fact about a colleague
+  // and had nowhere to put it — while the hq responder's `remember_preference`
+  // wrote it straight into PreferenceMemory"), then no tool was ever added
+  // here, so the reverse-parity fix never reached the plane it was built for —
+  // the same way `memory.recall` sat unreachable. The asymmetry it leaves is
+  // the one users actually feel: the workspace remembers your travel
+  // preference when hq answers and forgets it when your own seat does.
+  // BOTH halves ship together deliberately: hq injects known preferences into
+  // every responder prompt, an SDK seat gets no such injection and has to ask,
+  // so a write-only tool would let this seat store a fact it could never read
+  // back and re-derive it forever.
+  {
+    name: "preference_remember",
+    title: "Remember a preference",
+    description:
+      "Store one durable, member-scoped preference (preference.upsert) — the kind of standing " +
+      "fact a colleague should not have to repeat (\"always books aisle seats\", \"reviews on " +
+      "Thursdays\", \"never call before 10\"). It converges on ONE row per (subject, domain, key), " +
+      "so restating a preference updates it rather than accumulating contradictions. `why` is " +
+      "REQUIRED and is the evidence rule, not paperwork: store only what was actually stated or " +
+      "clearly demonstrated, and quote it. Never store a guess, a one-off request, or anything " +
+      "sensitive that was not offered as a standing preference — this is injected into future " +
+      "conversations, so a wrong row is wrong forever and in public.",
+    input_schema: S(
+      {
+        domain: str("The area, e.g. \"travel\", \"meetings\", \"comms\"."),
+        key: str("The specific preference, e.g. \"seat\", \"review-day\"."),
+        // Deliberately a plain string, though hq's zod union also takes a
+        // number, a boolean or a short array: every curated schema in this
+        // table declares ONE type, the MCP plane republishes these verbatim,
+        // and a preference value is read back as prose anyway. "aisle",
+        // "Thursday", "never before 10:00" all survive the round trip.
+        value: str("The preference value, as plain text — e.g. \"aisle\", \"Thursday\", \"never before 10:00\"."),
+        why: str("The evidence: quote or paraphrase where this was stated or shown (5–300 chars)."),
+        confidence: num("0–1, how sure you are (optional)."),
+        messageId: str("The message the evidence came from (optional)."),
+        subjectMemberId: str("Whose preference — omit for your own seat."),
+      },
+      ["domain", "key", "value", "why"],
+    ),
+    access: "write",
+    binding: { kind: "rpc", method: "preference.upsert" },
+  },
+  {
+    name: "preference_list",
+    title: "Read remembered preferences",
+    description:
+      "The preferences remembered about a member (preference.list) — yours by default, or a " +
+      "colleague's disclosed set, which is the same set their own profile page shows. Read this " +
+      "before asking someone something they have already told the workspace: hq's chat lane gets " +
+      "these injected into every prompt automatically, so a colleague reasonably expects you to " +
+      "know them. Empty is a real answer — nothing has been remembered yet.",
+    input_schema: S({
+      memberId: str("Whose preferences — omit for your own seat."),
+      domain: str("Narrow to one area, e.g. \"travel\"."),
+    }),
+    access: "read",
+    binding: { kind: "rpc", method: "preference.list" },
+  },
   // ── members / escalation ─────────────────────────────────────────────────
   {
     name: "member_profile",
@@ -950,6 +1072,227 @@ export const ORG_TOOLS = Object.freeze([
     access: "write",
     binding: { kind: "rpc", method: "escalation.create" },
   },
+  // ── mandate: the seat's own accountability spine ─────────────────────────
+  // THE ASYMMETRY THESE CLOSE, and it ran the wrong way. hq's chat-lane
+  // colleague has carried the whole mandate belt since the spine landed
+  // (read_mandate / read_agent_plan / propose_objective / record_kpi_sample —
+  // src/server/llm-responder/tools.ts, under a docblock that names SDK parity
+  // as the reason they exist) while the SDK plane they were written to match
+  // had NOTHING: `mandate.*` was protocol-declared, wired into the daemon's own
+  // internals (lib/mandate/*, lib/goals/loop.mjs) and reachable from a session
+  // only through `org_rpc`, which is access:"admin" and therefore does not
+  // exist for a leadership or default seat. So the DAEMON knew the seat's
+  // objectives and the SESSION it spawned did not: asked "what are you working
+  // toward", a session improvised. These five make the session read the same
+  // spine its own daemon compiles from.
+  //
+  // The tier is the SCOPE's, not a new judgement: the three reads and
+  // `propose` sit in DEFAULT_AGENT_SCOPES, `mandate.write` (adopt / retire)
+  // pointedly does not — a seat may not make its own targets live — so there is
+  // deliberately no adopt or retire tool in this table at all. Always-on rather
+  // than family-gated: `mandate.*` ships in the same vendored protocol as this
+  // file, so a probe could only ever answer yes.
+  {
+    name: "mandate_read",
+    title: "Read your mandate",
+    description:
+      "Your ADOPTED mandate snapshot (mandate.get): {version, checksum, body} — the outcomes " +
+      "you are actually held to, their metric, target, cadence and collaborators. Read this " +
+      "before answering \"what are you working toward / what are you responsible for\" instead " +
+      "of improvising from your prompt. `version: 0` with a null body is NOT an error and not " +
+      "an outage: it means nothing has been adopted for this seat yet, and the honest answer " +
+      "is to say exactly that. An objective is a commitment only once adopted; a proposed one " +
+      "is a suggestion awaiting a human. `memberId` defaults to your own seat — naming another " +
+      "requires mandate.write/admin and is refused in-domain, not silently widened.",
+    input_schema: S({ memberId: str("Whose mandate — omit for your own.") }),
+    access: "read",
+    binding: { kind: "rpc", method: "mandate.get" },
+  },
+  {
+    name: "mandate_objectives",
+    title: "The org objective tree",
+    description:
+      "The org's objective tree (mandate.tree): a FLAT node list plus explicit `childIds` and " +
+      "`roots` — pillars, objectives and goals, who owns each, its state and latest value. Use " +
+      "it to see where your own objectives sit in the org's, or to answer \"who owns this " +
+      "outcome\". All filters AND together; `includeRetired` defaults false because a retired " +
+      "objective is noise in a fleet view. Flat-with-edges by design: the tree is " +
+      "self-referencing and a bad parent edit would hang a nested serialiser.",
+    input_schema: S({
+      memberId: str("Only this seat's objectives."),
+      kind: str("PILLAR | OBJECTIVE | GOAL."),
+      state: str("proposed | active | at_risk | met | missed | retired."),
+      workstreamId: str("Only objectives on this workstream."),
+      includeRetired: bool("Include retired rows (default false)."),
+      limit: num("Max nodes (server caps at 2000)."),
+    }),
+    access: "read",
+    binding: { kind: "rpc", method: "mandate.tree" },
+  },
+  {
+    name: "mandate_kpi_series",
+    title: "An objective's measurements",
+    description:
+      "One objective's KPI samples plus the server-computed {value, target, gap, normalizedGap, " +
+      "trend, staleness} (mandate.series). Quote `gap` rather than re-deriving it: a POSITIVE " +
+      "gap always means \"short of target\" whichever way the metric points, and that convention " +
+      "is what makes gaps comparable across unlike metrics. `staleness.stale` is computed " +
+      "against 2x the objective's cadence — the same rule hq opens a stale-sensor drift on, so " +
+      "you and hq cannot disagree about whether a number has gone cold.",
+    input_schema: S(
+      {
+        objectiveId: str("The objective's id (from mandate_read or mandate_objectives)."),
+        limit: num("Max samples, newest first (1–500; default 50)."),
+      },
+      ["objectiveId"],
+    ),
+    access: "read",
+    binding: { kind: "rpc", method: "mandate.series" },
+  },
+  {
+    name: "mandate_propose_objective",
+    title: "Propose an objective",
+    description:
+      "PROPOSE a measurable outcome for yourself (mandate.propose). It is created in " +
+      "`state:'proposed'` and is NOT live: a human — or a manager who is not the owner — adopts " +
+      "it in hq, and you can never adopt your own. That is the whole anti-Goodhart law, not a " +
+      "temporary limitation, so do not report a proposal as a commitment. Re-proposing the same " +
+      "`key` UPDATES the proposal; an already-adopted objective is refused (CONFLICT) — retire " +
+      "it and propose a successor. The server also refuses a structurally unadoptable proposal " +
+      "at write time (no target, no charter edge, no sensor), which is a real answer about " +
+      "measurement debt, not a validation nit: relay it.",
+    input_schema: S(
+      {
+        key: str("Stable lowercase slug, e.g. \"pipeline-coverage\". The upsert key."),
+        text: str("The outcome in one line, as a human would state it."),
+        kind: str("PILLAR | OBJECTIVE | GOAL (default OBJECTIVE)."),
+        metric: str("What is measured, e.g. \"pipeline_coverage_x\"."),
+        unit: str("The unit the number is in."),
+        direction: str("up | down | hold | band (default up)."),
+        target: num("The number that counts as met."),
+        baseline: num("Where it stands today."),
+        tolerance: num("Allowed slack around target (>= 0)."),
+        weight: num("Relative weight among your objectives (>= 0)."),
+        cadence: str("daily | weekly | monthly | quarterly — how often it is measured."),
+        dueAt: str("ISO-8601 timestamp this is due by."),
+        parentId: str("The objective this one serves (id, same tenant)."),
+        charterSectionId: str(
+          "The charter PILLAR/CAPABILITY section this is accountable to. Read it off the seat's " +
+            "charter first — an objective that traces to no clause is accountable to nothing.",
+        ),
+        workstreamId: str("The workstream this belongs to."),
+        sensor: {
+          type: "object",
+          description:
+            "How it will be MEASURED, e.g. {method: \"crm.listDeals\"}. A method sensor naming a " +
+            "read-only protocol method is what later makes a sample count as measured rather " +
+            "than asserted.",
+        },
+        memberId: str("Whose objective — omit for your own."),
+      },
+      ["key", "text"],
+    ),
+    access: "write",
+    binding: { kind: "rpc", method: "mandate.propose" },
+  },
+  {
+    name: "mandate_record_kpi_sample",
+    title: "Report a measurement",
+    description:
+      "Record ONE measurement against an objective (mandate.sample). THE HONESTY GATE: the " +
+      "sample's `source` is decided by the SERVER from your evidence and any value you send for " +
+      "it is ignored outright. Cite a real read-only protocol method in `evidence.method` and " +
+      "the reading counts as MEASURED; anything else is `llm` — advisory, and your own admission " +
+      "gate refuses to create work from it. So do not dress up a number you inferred: an " +
+      "honest advisory sample is useful, a fabricated `method` claim is caught, recorded on " +
+      "the chain as downgraded, and teaches you nothing about your unwired sensor. Re-reporting " +
+      "the same `window` UPDATES that row rather than inflating the series.",
+    input_schema: S(
+      {
+        objectiveId: str("The objective's id (from mandate_read or mandate_objectives)."),
+        value: num("The measured value."),
+        window: str("The period: YYYY-MM-DD, YYYY-Www or YYYY-MM."),
+        evidence: {
+          type: "object",
+          description:
+            "Where the number came from, e.g. {method: \"books.reports\", note: \"quoted in #finance\"}. " +
+            "`method` must be a real read-only protocol method for the sample to count as measured.",
+        },
+      },
+      ["objectiveId", "value", "window"],
+    ),
+    access: "write",
+    binding: { kind: "rpc", method: "mandate.sample" },
+  },
+  // ── sub-agent registry (layer 1) ─────────────────────────────────────────
+  // The two halves of one feature that never met: maestro GENERATES sub-agents
+  // locally and hq keeps the org-scoped registry, but a running session could
+  // not read that registry through any curated tool — `subagent.*` was
+  // protocol-declared and reachable only via the admin-tier escape hatch. The
+  // wizard/CLI half already talks to hq through lib/subagents/client.mjs, which
+  // owns the offline OUTBOX and the lock file; these three are READS ONLY for
+  // exactly that reason. A curated write here would be a second writer that
+  // silently loses the outbox queueing and never touches the lock — so
+  // create/publishVersion/fork/pin/unpin/yank stay with `maestro subagents`,
+  // where the local state they mutate actually lives.
+  {
+    name: "subagent_list",
+    title: "List workspace sub-agents",
+    description:
+      "The workspace's sub-agent definitions (subagent.list) — ids, slugs, titles, summaries, " +
+      "tags, functions and altitudes, NEVER bodies. Use it to find whether a specialist already " +
+      "exists before proposing to write one. Yanked definitions are excluded unless asked for. " +
+      "Org-scoped server-side: there is no global catalogue to leak from.",
+    input_schema: S({
+      query: str("Free-text match over slug/title/summary."),
+      function: str("Filter by declared function."),
+      altitude: str("Filter by declared altitude."),
+      includeYanked: bool("Include yanked definitions (default false)."),
+      limit: num("Max definitions (1–500)."),
+    }),
+    access: "read",
+    binding: { kind: "rpc", method: "subagent.list" },
+  },
+  {
+    name: "subagent_get",
+    title: "Read one sub-agent",
+    description:
+      "One definition plus (by default) the BODY of its head version (subagent.get). Address it " +
+      "by `definitionId` or `slug` — one is required. `version` addresses a version by NUMBER, " +
+      "the same number a lock file carries. Bodies come back with {{agent.*}} tokens " +
+      "UNRENDERED — that is deliberate: rendering happens on the agent at load, so treat a " +
+      "token as a token and never paste one at a human as if it were a value. Set " +
+      "includeBody:false when you only need metadata; the body is the expensive field.",
+    input_schema: S({
+      definitionId: str("The definition's id (or pass slug)."),
+      slug: str("The definition's slug (or pass definitionId)."),
+      version: num("A specific version NUMBER; omit for the head."),
+      includeVersions: bool("Also return the bodyless version index."),
+      includeBody: bool("Set false for metadata only (default true)."),
+    }),
+    access: "read",
+    binding: { kind: "rpc", method: "subagent.get" },
+  },
+  {
+    name: "subagent_resolve",
+    title: "Resolve a seat's sub-agents",
+    description:
+      "Everything a seat can actually materialise (subagent.resolve): every ACTIVE pin with its " +
+      "body, frontmatter and provenance, plus advisory rewire verdicts for `refs` you parsed out " +
+      "of workflows. This is the EXPENSIVE read — it carries bodies — so reach for subagent_list " +
+      "when you only need to know what exists. hq resolves ONE layer; precedence across SDK / " +
+      "workspace / agent-local is decided locally on the agent, so this is an input to that " +
+      "decision, not the final answer. `memberId` defaults to your own seat; naming another is " +
+      "refused without admin rather than quietly widened.",
+    input_schema: S({
+      memberId: str("Whose sub-agents — omit for your own seat."),
+      function: str("Filter by declared function."),
+      altitude: str("Filter by declared altitude."),
+      refs: arr({ type: "string" }, "Agent references parsed from your workflows, for rewire verdicts."),
+    }),
+    access: "read",
+    binding: { kind: "rpc", method: "subagent.resolve" },
+  },
   // ── discoverability + escape hatches ─────────────────────────────────────
   {
     name: "org_describe",
@@ -2513,6 +2856,24 @@ export const ORG_TOOLS = Object.freeze([
     desk: "calls",
     binding: { kind: "rpc", method: "calling.getCallEvents" },
   },
+  // ── resource desk (venture deliverables; GENERATED, not hand-written) ──
+  //
+  // The eight `resource_*` entries are produced by lib/org/resource-tools.mjs
+  // from the vendored protocol declaration: the NAME, the ACCESS TIER, the
+  // BINDING and the DESK TAG are all derived, and the only hand-written part is
+  // presentation (title / description / input_schema). Every other desk block
+  // above is a hand-copy of hq's op list, and that is exactly why hq exposes
+  // 239 ops across 11 families where this table exposed 69 across 9 — files 29
+  // vs 7, crm 44 vs 8. A ninth `resource.*` method in the protocol becomes a
+  // ninth tool on the next import with no edit here, and
+  // lib/org/resource-tools.test.mjs goes red until it is described.
+  //
+  // Reads land at access:"read" (org.read → every tier, including
+  // least-privilege "default"); the six writes at access:"write" (org.write →
+  // ceo + leadership). NONE at "admin": a venture's own colleagues are default-
+  // and leadership-tier agents, so their deliverables at the CEO-only tier
+  // would be as unreachable as the org_rpc route a curated tool replaces.
+  ...RESOURCE_TOOLS,
 ]);
 
 // ---------------------------------------------------------------------------
@@ -2673,6 +3034,13 @@ async function screenOrgOutbound({ channel, recipient, text, agentRoot, screenIm
 
 /** Outbound screen inputs (recipient + text) for a screened tool/method. */
 function outboundScreenShape(toolName, method, input) {
+  if (toolName === "messaging_send_voice_note") {
+    // BOTH strings, because both reach a person: the spoken words and the
+    // written body. Screened before synthesis, so a blocked note costs nothing
+    // and — more to the point — is never recorded in a colleague's own voice.
+    const text = [input?.text, input?.body].filter((v) => typeof v === "string" && v).join("\n");
+    return { recipient: input?.channelId ?? "", text };
+  }
   if (method === "messaging.send") {
     return { recipient: input?.channelId ?? "", text: input?.body ?? "" };
   }
@@ -2998,6 +3366,54 @@ async function executeOrgToolInner(name, input = {}, o = {}) {
         });
       }
 
+      case "messaging_send_voice_note": {
+        const channelId = input && input.channelId ? String(input.channelId) : "";
+        const spokenText = input && input.text ? String(input.text) : "";
+        if (!channelId || !spokenText) {
+          return errFrame("BAD_REQUEST", "messaging_send_voice_note: channelId and text are required");
+        }
+        // 1. RECORD. A refusal is FINAL and is relayed as-is: no key, no
+        //    designed voice for this seat, or the hourly cap. The one thing
+        //    this tool must never do is come back ok with nothing recorded —
+        //    an agent that believes it spoke will not repeat itself in text.
+        const rec = await call("messaging.synthesizeVoiceNote", { text: spokenText }, { ...callOpts });
+        if (!rec.ok) return rec;
+        const note = rec.result || {};
+        if (!note.fileId) {
+          return errFrame("INTERNAL", "messaging_send_voice_note: no recording came back");
+        }
+        // 2. POST. Plain messaging.send with the recording attached — the
+        //    server-side outbound gate, the channel ACL, the READY + own-upload
+        //    attachment rule, the dedup and the notifier all apply exactly as
+        //    they do to a typed message. There is no audio-only send path.
+        const sent = await call(
+          "messaging.send",
+          {
+            channelId,
+            body: input.body ? String(input.body) : spokenText,
+            ...(input.threadRootId ? { threadRootId: String(input.threadRootId) } : {}),
+            attachments: [{ fileId: note.fileId }],
+            idempotencyId: randomUUID(),
+          },
+          { ...callOpts, idempotencyKey: randomUUID() },
+        );
+        if (!sent.ok) {
+          // Recorded but unposted. Said plainly rather than folded into a bare
+          // transport error: the spend HAPPENED, and the caller's next move is
+          // to retry the post with this fileId, not to record again.
+          return errFrame(
+            sent.error?.code || "INTERNAL",
+            `voice note recorded (fileId ${note.fileId}) but the post failed: ${sent.error?.message || "unknown"}`,
+          );
+        }
+        return okFrame({
+          ...(sent.result || {}),
+          fileId: note.fileId,
+          durationMs: note.durationMs ?? null,
+          spokenChars: spokenText.length,
+        });
+      }
+
       case "org_events_tail": {
         const q = {};
         if (input && input.cursor != null) q.cursor = input.cursor;
@@ -3114,8 +3530,18 @@ async function executeOrgToolInner(name, input = {}, o = {}) {
   }
 }
 
+// Re-exported so both exposure planes and every parity test resolve the access
+// mechanism from ONE place — a second copy of "which tools may be admin" is how
+// the rule ended up enforced by hand-listed name arrays in the first place.
+export { ADMIN_TOOLS, expectedAccessFor, normalizeToolAccess };
+export { RESOURCE_TOOLS };
+
 export default {
   ORG_TOOLS,
+  RESOURCE_TOOLS,
+  ADMIN_TOOLS,
+  expectedAccessFor,
+  normalizeToolAccess,
   getOrgTools,
   isOrgTool,
   orgToolDef,