@cohortapp/agent-sdk 2.3.0

package/lib/tool-definitions.js

@@ -0,0 +1,738 @@
+/**
+ * Maestro — Comprehensive Tool Definitions
+ *
+ * Reusable tool schemas for Claude API tool_use, scoped by access level.
+ * Covers all operational capabilities an autonomous agent in an
+ * organisation might need.
+ *
+ * Categories:
+ *   1. Communication — Slack, Email, WhatsApp, SMS
+ *   2. Search / RAG — Email, Calendar, Files, Meetings, Slack, Web
+ *   3. Knowledge — Decisions, People, Regulatory, Strategy
+ *   4. Operations — Queues, Action Items, Scheduling
+ *   5. Analysis — Financial, Pipeline, Engineering Health
+ *   6. Document Generation — Memos, Briefs, Reports
+ *   7. Org (Cohort) — the curated org operating surface, generated from
+ *      lib/org/tool-surface.mjs (ONE table shared with the cohort-mcp server
+ *      so the two planes cannot drift). Reads land in every level's lookup
+ *      set; writes in leadership+; the org_rpc/org_read escape hatches are
+ *      CEO-only (server-side scopes still gate regardless). The additive
+ *      families appear automatically once the vendored protocol carries them:
+ *      email tools, artifact tools, and the agent desks (mail app / files /
+ *      calendar / crm / books / meetings.recapFile).
+ *
+ * Usage:
+ *   import { getToolsForAccessLevel } from "@cohortapp/agent-sdk/lib/tool-definitions.js";
+ *   const tools = getToolsForAccessLevel("ceo");
+ *   // Pass to Claude API: { tools }
+ *
+ * @module tool-definitions
+ */
+
+import { getOrgTools, loadIntegrationToolsFromDisk } from "./org/tool-surface.mjs";
+
+// ============================================================================
+// 1. COMMUNICATION TOOLS
+// ============================================================================
+
+const slackSend = {
+  name: "slack_send",
+  description:
+    "Send a Slack message to a team member or channel. Confirm recipient and content before invoking.",
+  input_schema: {
+    type: "object",
+    properties: {
+      recipient: { type: "string", description: "Person or channel (e.g. 'Alex', '#engineering')" },
+      message: { type: "string", description: "Message content" },
+      thread_ts: { type: "string", description: "Thread timestamp to reply in-thread (optional)" },
+      urgent: { type: "boolean", description: "Whether urgent (affects formatting)" },
+    },
+    required: ["recipient", "message"],
+  },
+};
+
+const draftEmail = {
+  name: "draft_email",
+  description:
+    "Draft or send an email. Drafts are saved for review; set urgency to 'immediate' to send now.",
+  input_schema: {
+    type: "object",
+    properties: {
+      to: { type: "string", description: "Recipient name or email" },
+      subject: { type: "string", description: "Subject line" },
+      body: { type: "string", description: "Email body" },
+      cc: { type: "string", description: "CC recipients (comma-separated)" },
+      voice: { type: "string", enum: ["agent", "principal"], description: "Whose voice (default: agent)" },
+      urgency: { type: "string", enum: ["routine", "urgent", "immediate"], description: "Urgency level" },
+    },
+    required: ["to", "subject", "body"],
+  },
+};
+
+const whatsappSend = {
+  name: "whatsapp_send",
+  description: "Send a WhatsApp message to a registered contact.",
+  input_schema: {
+    type: "object",
+    properties: {
+      recipient: { type: "string", description: "Person name" },
+      message: { type: "string", description: "Message content" },
+    },
+    required: ["recipient", "message"],
+  },
+};
+
+const smsSend = {
+  name: "sms_send",
+  description: "Send an SMS text message via Twilio.",
+  input_schema: {
+    type: "object",
+    properties: {
+      recipient: { type: "string", description: "Person name or phone number (E.164)" },
+      message: { type: "string", description: "Message content (160 char limit for single SMS)" },
+    },
+    required: ["recipient", "message"],
+  },
+};
+
+const sendVoiceMessage = {
+  name: "send_voice_message",
+  description:
+    "Synthesize speech from text (OpenAI TTS) and deliver as a voice note. " +
+    "Auto-routes the transport: a Slack channel/DM id (C/D/G prefix) → audio file upload, " +
+    "an E.164 phone with WhatsApp configured → inline voice note (PTT), " +
+    "an E.164 phone without WhatsApp → Twilio outbound call that speaks the message. " +
+    "Use this when prose-via-voice is more appropriate than text (warm follow-ups, " +
+    "longer briefings someone will listen to in transit, content the recipient should " +
+    "hear in your agent voice).",
+  input_schema: {
+    type: "object",
+    properties: {
+      to: {
+        type: "string",
+        description:
+          "Destination: Slack channel id (C…/D…/G…), WhatsApp JID (…@s.whatsapp.net), or E.164 phone (+…)",
+      },
+      text: {
+        type: "string",
+        description: "Spoken content (max 4096 chars). Keep < 60s of audio for conversational feel.",
+      },
+      transport: {
+        type: "string",
+        enum: ["whatsapp", "slack", "pstn"],
+        description: "Force a specific transport (default: auto-routed based on `to`).",
+      },
+      voice: {
+        type: "string",
+        enum: ["alloy", "ash", "ballad", "coral", "echo", "sage", "shimmer", "verse"],
+        description: "TTS voice (default: from config/voice.yaml, falls back to alloy).",
+      },
+    },
+    required: ["to", "text"],
+  },
+};
+
+const ragSearch = {
+  name: "rag_search",
+  description:
+    "Semantic / keyword search across the agent's own corpus (memory, knowledge, " +
+    "decisions, queues, agent definitions, workflows, briefs, policies). Use this " +
+    "when you need a specific fact or quote from the agent's institutional memory " +
+    "and the answer isn't already in your pre-loaded context. Each call is fast " +
+    "(<50ms, no network) but adds ~1s of conversational silence so prefer it for " +
+    "specific lookups, not exploratory browsing. " +
+    "Top result is always shown; ask for more by raising top_n.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: "Free-text query. Specific names, project IDs, and dates work best.",
+      },
+      top_n: { type: "number", description: "Max hits to return (default: 5, max: 20)" },
+      kind: {
+        type: "string",
+        enum: [
+          "memory", "knowledge", "queue", "dashboard", "config",
+          "agent_def", "workflow", "brief", "memo", "policy",
+        ],
+        description:
+          "Filter to a single content kind. Useful when you know the answer must " +
+          "be in (say) decisions vs. briefs.",
+      },
+    },
+    required: ["query"],
+  },
+};
+
+const placeVoiceCall = {
+  name: "place_voice_call",
+  description:
+    "Place a live conversational outbound phone call. Bridges Twilio outbound → " +
+    "OpenAI Realtime so the agent voice (gpt-realtime-2) talks with the peer in " +
+    "real time, with the same tool bridge as inbound calls. Use only when a " +
+    "synchronous voice conversation is genuinely needed; one-shot voice messages " +
+    "should use send_voice_message instead (much cheaper, no real-time pressure).",
+  input_schema: {
+    type: "object",
+    properties: {
+      to: { type: "string", description: "E.164 phone number to call" },
+      brief: {
+        type: "string",
+        description:
+          "What the agent should accomplish on the call. Becomes the model's session " +
+          "instructions. Be specific: 'Confirm with the principal that they received the board " +
+          "resolution and answer any questions about clause 4.2.'",
+      },
+      voice: {
+        type: "string",
+        enum: ["cedar", "marin", "alloy", "ash", "ballad", "coral", "echo", "sage", "shimmer", "verse"],
+        description: "Realtime voice (default: cedar)",
+      },
+    },
+    required: ["to", "brief"],
+  },
+};
+
+// ============================================================================
+// 2. SEARCH / RAG TOOLS
+// ============================================================================
+
+const searchEmail = {
+  name: "search_email",
+  description:
+    "Search Gmail for emails. Use for finding correspondence, checking what someone sent, recalling email threads.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Natural language or Gmail search syntax (e.g. 'from:alex budget this week')" },
+      max_results: { type: "number", description: "Max results (default: 5)" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchCalendar = {
+  name: "search_calendar",
+  description:
+    "Look up calendar events — meetings, availability, schedule. Returns titles, times, attendees.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "What to find (e.g. 'meetings tomorrow', 'next call with Shayan', 'free time Thursday')" },
+      time_range: { type: "string", description: "'today', 'tomorrow', 'this week', 'next week', or specific date" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchFiles = {
+  name: "search_files",
+  description:
+    "Search the agent's knowledge base, documents, and operational files. Covers knowledge/, config/, state/, docs/, outputs/.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "What to search for (e.g. 'regulatory submission status', 'rollup targets')" },
+      scope: { type: "string", enum: ["all", "knowledge", "config", "state", "docs", "outputs"], description: "Scope (default: all)" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchMeetings = {
+  name: "search_meetings",
+  description:
+    "Search past meeting notes and transcripts. Use for recalling discussions, decisions, and action items from meetings.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "What to find in meeting notes (e.g. 'board meeting decisions', 'hiring discussion')" },
+      date_range: { type: "string", description: "Date range (e.g. 'last week', 'March 2026')" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchSlack = {
+  name: "search_slack",
+  description:
+    "Search Slack message history across channels. Find conversations, decisions made in Slack, mentions.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Search query (e.g. 'Q3 deployment', 'compliance in #legal')" },
+      channel: { type: "string", description: "Limit to channel (optional)" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchWeb = {
+  name: "search_web",
+  description:
+    "Search the web for current information. Use for market data, competitor intel, regulatory updates, news.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Web search query" },
+      max_results: { type: "number", description: "Max results (default: 5)" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchDocuments = {
+  name: "search_documents",
+  description:
+    "Search shared documents in Google Drive, Confluence, or other document stores. Find reports, proposals, specs.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "What to find (e.g. 'investor deck Q1', 'board pack March')" },
+      doc_type: { type: "string", enum: ["all", "docs", "sheets", "slides", "pdf"], description: "Filter by type" },
+    },
+    required: ["query"],
+  },
+};
+
+// ============================================================================
+// 3. KNOWLEDGE / INSTITUTIONAL MEMORY TOOLS
+// ============================================================================
+
+const searchDecisions = {
+  name: "search_decisions",
+  description:
+    "Search the decision archive — past decisions, their rationale, who made them, and outcomes.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "What decision to find (e.g. 'hiring freeze rationale', 'Singapore entity structure')" },
+    },
+    required: ["query"],
+  },
+};
+
+const lookupPerson = {
+  name: "lookup_person",
+  description:
+    "Look up information about a person — role, contact details, reporting line, recent activity, communication preferences.",
+  input_schema: {
+    type: "object",
+    properties: {
+      name: { type: "string", description: "Person's name" },
+      info_type: { type: "string", enum: ["all", "contact", "role", "activity", "preferences"], description: "What to look up" },
+    },
+    required: ["name"],
+  },
+};
+
+const searchRegulatory = {
+  name: "search_regulatory",
+  description:
+    "Search regulatory and compliance information — licence status, submission deadlines, compliance requirements, legal obligations.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Regulatory query (e.g. 'licence gaps', 'submission deadline', 'regulatory requirements')" },
+      jurisdiction: { type: "string", description: "Jurisdiction filter (e.g. 'DIFC', 'Cayman', 'UK')" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchStrategy = {
+  name: "search_strategy",
+  description:
+    "Search strategic context — priorities, OKRs, initiative status, strategic memos, competitive intelligence.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Strategic query (e.g. 'strategic initiative status', 'Q2 priorities', 'competitive landscape')" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchPrecedents = {
+  name: "search_precedents",
+  description:
+    "Search operational precedents — how similar situations were handled before, templates, playbooks.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Situation to find precedent for (e.g. 'investor objection handling', 'candidate rejection template')" },
+    },
+    required: ["query"],
+  },
+};
+
+// ============================================================================
+// 4. OPERATIONS TOOLS
+// ============================================================================
+
+const queueUpdate = {
+  name: "queue_update",
+  description:
+    "Update status or priority of an item in operational queues (action-stack, follow-ups, decision-queue).",
+  input_schema: {
+    type: "object",
+    properties: {
+      search_term: { type: "string", description: "Text to search in item titles (fuzzy match)" },
+      new_status: { type: "string", enum: ["open", "in_progress", "blocked", "resolved", "closed"] },
+      new_priority: { type: "string", enum: ["critical", "high", "medium", "low"] },
+      note: { type: "string", description: "Note to add to the item's history" },
+    },
+    required: ["search_term", "new_status"],
+  },
+};
+
+const createActionItem = {
+  name: "create_action_item",
+  description:
+    "Create a new action item, follow-up, or decision in the operational queues.",
+  input_schema: {
+    type: "object",
+    properties: {
+      title: { type: "string", description: "Brief title" },
+      queue: { type: "string", enum: ["action-stack", "follow-ups", "decision-queue", "tech-debt"], description: "Queue (default: action-stack)" },
+      priority: { type: "string", enum: ["critical", "high", "medium", "low"] },
+      due_date: { type: "string", description: "Due date YYYY-MM-DD" },
+      owner: { type: "string", description: "Responsible person (default: agent)" },
+      context: { type: "string", description: "Background context" },
+      blocked_by: { type: "string", description: "What blocks this item" },
+    },
+    required: ["title"],
+  },
+};
+
+const scheduleMeeting = {
+  name: "schedule_meeting",
+  description:
+    "Schedule a meeting on Google Calendar. Checks availability and sends invites.",
+  input_schema: {
+    type: "object",
+    properties: {
+      title: { type: "string", description: "Meeting title" },
+      attendees: { type: "string", description: "Attendee names or emails (comma-separated)" },
+      date: { type: "string", description: "Date (YYYY-MM-DD or 'tomorrow', 'next Monday')" },
+      time: { type: "string", description: "Time (HH:MM in agent timezone, or 'morning', 'afternoon')" },
+      duration: { type: "string", description: "Duration (e.g. '30m', '1h', default: 30m)" },
+      description: { type: "string", description: "Meeting description/agenda" },
+      location: { type: "string", description: "Location or video link" },
+    },
+    required: ["title", "attendees", "date"],
+  },
+};
+
+const createReminder = {
+  name: "create_reminder",
+  description:
+    "Set a reminder for the agent or principal. Fires via Slack DM at the specified time.",
+  input_schema: {
+    type: "object",
+    properties: {
+      message: { type: "string", description: "Reminder message" },
+      when: { type: "string", description: "When to remind (e.g. 'in 2 hours', 'tomorrow 9am', '2026-04-10 14:00')" },
+      for_whom: { type: "string", description: "Who to remind (default: principal)" },
+    },
+    required: ["message", "when"],
+  },
+};
+
+// ============================================================================
+// 5. ANALYSIS TOOLS
+// ============================================================================
+
+const searchFinancial = {
+  name: "search_financial",
+  description:
+    "Look up financial data — runway, burn rate, capital readiness, fundraising pipeline, AUM figures.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Financial query (e.g. 'current runway', 'fundraising status', 'AUM pipeline')" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchPipeline = {
+  name: "search_pipeline",
+  description:
+    "Search the commercial/relationship pipeline — deal stages, partner status, investor conversations.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Pipeline query (e.g. 'acquisition targets status', 'investor conversations this month')" },
+      stage: { type: "string", enum: ["all", "prospecting", "engaged", "diligence", "closing", "closed"], description: "Filter by stage" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchEngineering = {
+  name: "search_engineering",
+  description:
+    "Search engineering health data — repo activity, PR status, delivery confidence, tech debt, deployment status.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Engineering query (e.g. 'adaptic-engine PR status', 'deployment blockers', 'tech debt priority')" },
+      repo: { type: "string", description: "Specific repository name (optional)" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchHiring = {
+  name: "search_hiring",
+  description:
+    "Search hiring pipeline — open roles, candidate status, interview pipeline, offer tracking.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Hiring query (e.g. 'open engineering roles', 'candidates for CFO', 'offers pending')" },
+      status: { type: "string", enum: ["all", "open", "screening", "interviewing", "offer", "filled"], description: "Filter by status" },
+    },
+    required: ["query"],
+  },
+};
+
+const searchRisk = {
+  name: "search_risk",
+  description:
+    "Search the enterprise risk register — active risks, mitigations, severity, ownership.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Risk query (e.g. 'critical risks', 'regulatory risks', 'unmitigated risks')" },
+      severity: { type: "string", enum: ["all", "critical", "high", "medium", "low"], description: "Filter by severity" },
+    },
+    required: ["query"],
+  },
+};
+
+// ============================================================================
+// 6. DOCUMENT GENERATION TOOLS
+// ============================================================================
+
+const generateMemo = {
+  name: "generate_memo",
+  description:
+    "Generate a branded PDF memo or brief. Saved to outputs/drafts/ and optionally shared via Slack.",
+  input_schema: {
+    type: "object",
+    properties: {
+      title: { type: "string", description: "Document title" },
+      content: { type: "string", description: "Memo content (markdown)" },
+      type: { type: "string", enum: ["memo", "brief", "board-pack", "letter", "investor"], description: "Document type" },
+      share_to: { type: "string", description: "Slack channel or person to share with (optional)" },
+    },
+    required: ["title", "content"],
+  },
+};
+
+const generateReport = {
+  name: "generate_report",
+  description:
+    "Generate an analytical report by aggregating data from dashboards, queues, and operational state.",
+  input_schema: {
+    type: "object",
+    properties: {
+      report_type: {
+        type: "string",
+        enum: ["executive-summary", "engineering-health", "hiring-pipeline", "strategy-scorecard", "leadership-accountability", "risk-register", "custom"],
+        description: "Report type",
+      },
+      custom_query: { type: "string", description: "For custom reports — what to analyse" },
+      time_range: { type: "string", description: "Time range (default: current)" },
+    },
+    required: ["report_type"],
+  },
+};
+
+// ============================================================================
+// 7. ORG (COHORT) TOOLS — generated from lib/org/tool-surface.mjs
+// ============================================================================
+//
+// ONE curated table serves both the cohort-mcp server and this native
+// function-call path. The schemas in the table are already Claude
+// `tool_use`-shaped, so the projection below is a plain field pick — the two
+// planes cannot drift. The additive families gate on the vendored protocol
+// (tool-surface: emailFamilyAvailable / artifactFamilyAvailable /
+// deskFamilyAvailable) — email tools, artifact tools, and the agent-desk tools
+// (mail app / files / calendar / crm / books / meetings) register only when
+// their family is vendored.
+
+// The CURATED org tools are import-time stable (family gating is fixed per the
+// vendored protocol), so a one-time snapshot is fine here. The integration tools
+// getOrgTools now appends are EXCLUDED from this frozen list (`!t.integration`)
+// and added fresh per getToolsForAccessLevel call, below — so the native plane
+// hot-refreshes them without a restart and they're never double-counted (SP5).
+const ORG_TOOL_DEFS = getOrgTools({}).filter((t) => !t.integration);
+const asClaudeTool = ({ name, description, input_schema }) => ({ name, description, input_schema });
+const orgTools = ORG_TOOL_DEFS.map(asClaudeTool);
+const orgToolsByAccess = (access) =>
+  ORG_TOOL_DEFS.filter((t) => t.access === access).map(asClaudeTool);
+
+/**
+ * The workspace's GRANTED integration tools (SP5), read FRESH from the shared
+ * disk cache (state/org/toolset.json) on each call so the native plane reflects a
+ * newly-granted tool WITHOUT a daemon/session restart — the curated tools above
+ * are the only import-time-frozen part; the integration set is the sole runtime-
+ * mutable part. They are access "write", so they ride the write tiers (ceo +
+ * leadership) exactly like orgWriteTools. Fail-open to [].
+ * @returns {Array<{name:string,description:string,input_schema:object}>}
+ */
+function currentOrgIntegrationTools() {
+  try {
+    return loadIntegrationToolsFromDisk().map(asClaudeTool);
+  } catch {
+    return [];
+  }
+}
+
+// Reads → every level's lookup set; writes → leadership+; the escape hatches
+// (org_rpc / org_read, access "admin") → CEO only. hq's server-side scope gate
+// applies regardless — the native clamp only narrows, never grants.
+const orgReadTools = orgToolsByAccess("read");
+const orgWriteTools = orgToolsByAccess("write");
+const orgAdminTools = orgToolsByAccess("admin");
+
+// Voice curation: conversation-sized org actions only.
+const ORG_VOICE_NAMES = new Set(["org_whoami", "messaging_history", "messaging_send", "board_ready"]);
+const orgVoiceTools = orgTools.filter((t) => ORG_VOICE_NAMES.has(t.name));
+
+// ============================================================================
+// ACCESS LEVEL SCOPING
+// ============================================================================
+
+// All lookup/search tools (read-only, safe for any authorised user)
+const lookupTools = [
+  searchEmail, searchCalendar, searchFiles, searchMeetings, searchSlack,
+  searchWeb, searchDocuments, searchDecisions, lookupPerson, searchRegulatory,
+  searchStrategy, searchPrecedents, searchFinancial, searchPipeline,
+  searchEngineering, searchHiring, searchRisk,
+  ...orgReadTools,
+];
+
+// Write tools (require higher access)
+const writeToolsCeo = [
+  slackSend, draftEmail, whatsappSend, smsSend,
+  sendVoiceMessage, placeVoiceCall,
+  queueUpdate, createActionItem, scheduleMeeting, createReminder,
+  generateMemo, generateReport,
+  ...orgWriteTools,
+  // Escape hatches are deliberately withheld from lower native access levels.
+  ...orgAdminTools,
+];
+
+const writeToolsLeadership = [
+  slackSend, draftEmail,
+  sendVoiceMessage,
+  queueUpdate, createActionItem, scheduleMeeting, createReminder,
+  ...orgWriteTools,
+];
+
+// Voice-specific tool surface — exposed to Realtime sessions via tool-bridge.
+// rag_search lands here too: voice sessions benefit massively from being
+// able to retrieve specific snippets from the agent's corpus mid-call.
+const voiceTools = [
+  slackSend, draftEmail, whatsappSend, smsSend,
+  sendVoiceMessage,
+  ragSearch,
+  queueUpdate, createActionItem, scheduleMeeting,
+  ...[searchEmail, searchCalendar, searchSlack, searchDecisions, lookupPerson, searchFinancial, searchPipeline],
+  ...orgVoiceTools,
+];
+
+// Known access-level keys. "default" is the least-privilege fallback.
+export const KNOWN_ACCESS_LEVELS = ["ceo", "leadership", "voice", "default"];
+
+/**
+ * Normalise an access-level key to a known, safe value.
+ *
+ * Access-level lookups used to be case-sensitive and silently returned an EMPTY
+ * tool set for any unrecognised key — so "CEO" (instead of "ceo") yielded zero
+ * tools, a silent UNDER-privilege footgun. This normaliser:
+ *   - lowercases/trims the input so "CEO", " ceo ", etc. all map to "ceo"
+ *   - coerces any truly-unknown / invalid level to the least-privilege
+ *     "default" (NEVER empty, NEVER throws), logging a warning so the
+ *     misconfiguration is visible
+ *
+ * Known levels (ceo / leadership / voice / default) are returned unchanged.
+ *
+ * @param {string} accessLevel - Raw access-level key (any casing/whitespace).
+ * @returns {string} A guaranteed-known access-level key.
+ */
+export function normalizeAccessLevel(accessLevel) {
+  const key =
+    typeof accessLevel === "string" ? accessLevel.trim().toLowerCase() : "";
+  if (KNOWN_ACCESS_LEVELS.includes(key)) {
+    return key;
+  }
+  // Unknown / empty / non-string: fall back to least privilege.
+  console.warn(
+    `[tool-definitions] Unknown access level ${JSON.stringify(
+      accessLevel,
+    )}; coercing to least-privilege "default".`,
+  );
+  return "default";
+}
+
+/**
+ * Get tools available for a caller's access level.
+ *
+ * The level is normalised first (case/whitespace-insensitive); an unknown level
+ * coerces to the least-privilege "default" surface rather than an empty set.
+ *
+ * @param {string} accessLevel - "ceo", "leadership", "voice", or "default"
+ * @returns {Array<object>} Claude API tool schemas
+ */
+export function getToolsForAccessLevel(accessLevel) {
+  // Granted integration tools (write tier) are read fresh from the disk cache
+  // on every call so a newly-granted tool appears without a restart (SP5).
+  const integrationTools = currentOrgIntegrationTools();
+  switch (normalizeAccessLevel(accessLevel)) {
+    case "ceo":
+      return [...writeToolsCeo, ...integrationTools, ...lookupTools];
+    case "leadership":
+      return [...writeToolsLeadership, ...integrationTools, ...lookupTools];
+    case "voice":
+      // Curated set for Realtime voice sessions — communication +
+      // common lookups, no document-generation (long-form artefacts
+      // don't fit conversational voice flow).
+      return [...voiceTools];
+    case "default":
+    default:
+      // normalizeAccessLevel guarantees a known key, so "default" is the only
+      // path here — read-only search and lookup tools.
+      return [...lookupTools];
+  }
+}
+
+/**
+ * Get tool names for an access level.
+ * @param {string} accessLevel
+ * @returns {string[]}
+ */
+export function getToolNamesForAccessLevel(accessLevel) {
+  return getToolsForAccessLevel(accessLevel).map((t) => t.name);
+}
+
+/**
+ * Get all tool definitions (for documentation / init-maestro generation).
+ * @returns {{ communication: object[], search: object[], knowledge: object[], operations: object[], analysis: object[], documents: object[], org: object[] }}
+ */
+export function getAllToolsByCategory() {
+  return {
+    communication: [slackSend, draftEmail, whatsappSend, smsSend, sendVoiceMessage, placeVoiceCall],
+    search: [searchEmail, searchCalendar, searchFiles, searchMeetings, searchSlack, searchWeb, searchDocuments, ragSearch],
+    knowledge: [searchDecisions, lookupPerson, searchRegulatory, searchStrategy, searchPrecedents],
+    operations: [queueUpdate, createActionItem, scheduleMeeting, createReminder],
+    analysis: [searchFinancial, searchPipeline, searchEngineering, searchHiring, searchRisk],
+    documents: [generateMemo, generateReport],
+    org: [...orgTools],
+  };
+}