One registry for every AI tool

00TL;DR

Six things to take away before the detail.

01The system today

Three mechanisms decide which tools an LLM turn can see. They were built at different times and don't share a spine.

Mechanism A — the shared domain registry

Lives in src/mods/assistant/services/tool_registry_service.rs. The private collect_rig_tools(session, families, page_context, conversation_id, tier_flags, include_assistant_meta) applies three gates in order:

• Permission gate (ABAC) — has_any_of(session, &[Permission::…]); super-admins / owners bypass.
• Surfacing gate — surfacing_families(page_context) narrows by the page the human is on (Contacts → Contacts+Messages+Calls+Sales, etc.). A pure narrowing layer; never widens.
• Tier gate — TierToolFlags { knowledge_base_enabled, custom_analyzers_enabled, autonomous_plans_enabled } gates a few infra tools.

Two public entry points wrap it:

// Assistant: page-surfaced + the personalization meta-tool
pub fn collect_assistant_rig_tools(session, page_context, conversation_id, tier_flags)
    -> collect_rig_tools(session, &surfacing_families(page_context), …, true);

// Agent: ALL families, NO page surfacing, NO personalization
pub fn collect_agent_domain_rig_tools(session, tier_flags)
    -> collect_rig_tools(session, &Family::all(), None, None, tier_flags, false);

Mechanism B — the agent-control registry

Lives in src/mods/ai_agent/tools/mod.rs. build_agent_tools(allowlist, caller_thread_id) iterates the agent's stored tools_allowlist and matches each name against AiAgentToolName. This is the granular, per-tool model the user wants to generalise. The 14 tools cover memory, agent-to-agent messaging, self-management, escalation and skills — all curried with caller_thread_id and resolving agent/org identity from the thread.

Mechanism C — per-turn conditional tools

Some tools aren't in either gate — the turn runner injects them by situation: list_my_skills / load_skill (lazy-skill mode), resolve_escalation (only when the thread has open escalations), and the channel-bound propose_sms_replies / propose_webchat_replies / send_webchat_reply (curried with the live contact/message/session).

Where the other AI areas stand

So the consumers that genuinely benefit from a shared tool catalog are: assistant, agents, text-reply, widget, and (later) voice if it gains tool use. That's the "other AI areas might use them" the brief refers to.

02What's actually wrong

Not "tools are trapped in the assistant" — they aren't. The friction is structural.

03Three tool scopes (the core proposal)

Make scope an explicit property of every tool. The brief's "share some, keep some agent-only" becomes a declared tag, not a code path.

04Every tool, classified

The full inventory tagged by proposed scope. new marks tools that don't exist yet (§6).

shared — domain tools (any AI area)

agent — agent-control tools (autonomous only)

assistant — human-session tools

channel — per-turn injected (stays dynamic)

propose_sms_replies, propose_webchat_replies, send_webchat_reply. Curried with the live channel context, so they can't be static allowlist entries — the turn runner keeps injecting them by situation regardless of the registry refactor.

05Target architecture

One catalog, one builder, scope declared per tool, one granular allowlist for every consumer. "Follow the agent registry pattern" — generalised.

What "context" (ctx) carries

The one wrinkle: shared tools need a Session; agent tools need a caller_thread_id. The unified builder takes a ToolContext that can hold either or both. A tool's build(ctx) pulls what it needs; the builder asserts the required field is present (an agent-scoped tool with no thread id is a programming error, not a runtime grant).

pub struct ToolContext {
    pub session: Option<Session>,       // shared tools (ABAC)
    pub caller_thread_id: Option<Uuid>, // agent + channel tools
    pub page_context: Option<PageContext>, // assistant surfacing hints
    pub tier_flags: TierToolFlags,
}

06Missing tools — let agents do more

Given the schedule poller (#1531), escalation (#1543) and the learning/memory work on this branch, here's what an agent still can't reach — ranked by how much it unlocks.

What agents can already do (so we don't rebuild it)

• shared send_sms — send a message now (CORE domain tool).
• shared task_write — create a follow-up task for the owner.
• agent update_contact_memory / update_my_memory — remember what happened.
• agent escalate_to_user / resolve_escalation — ask the human and learn from the answer.

The real gaps

07The follow-up example, in full

Tracing "tomorrow at 9am, text Jane to confirm; then close the schedule" against today's code reveals exactly the four gaps.

What the schedule system gives us today

• ScheduleRecurrence has four variants: Hourly, Daily, Weekdays, Weekly. All recur. There is no "once, at this datetime" option.
• poll_due_agent_schedules() runs every minute, evaluates is_due_at(hour, minute, weekday) in org-local time, and on a hit wakes the agent via find_or_spawn_agent_thread with an AiThreadEventPayload::Scheduled { instruction }.
• That payload carries only a string. It is framed to the model as [Scheduled instruction from your owner — not the contact] with no contact id — unlike inbound events, which carry · id {contact_id}.
• Schedules are created through the management UI APIs (create_ai_agent_schedule_api …). No tool exposes this to the agent.

The desired sequence — and where it breaks

The four concrete changes

1. New tool create_schedule agent — thin wrapper over create_ai_agent_schedule, curried with caller_thread_id → agent_id. Input: recurrence + instruction (+ optional contact_id).
2. New tool cancel_schedule / list_my_schedules agent — so the agent can close a one-shot after it fires, or clean up obsolete recurring ones. Wraps delete_ai_agent_schedule / set_…_enabled.
3. New recurrence Once { at: DateTime } — fires a single time then auto-disables (cleanest UX), or rely on the agent calling cancel_schedule in Act 2 (no schema change, but fragile if the agent forgets). Recommend the auto-disabling Once variant; cancel_schedule stays useful for recurring schedules.
4. Carry contact context into the wake — either extend AiThreadScheduled with an optional contact_id (and surface · id {contact_id} in the frame, mirroring inbound events so update_contact_memory / send_sms are constructible from the turn alone), or require the agent to put the contact reference in the instruction text and re-resolve via contact_find. The former is cleaner and matches the #1494 Part-B pattern already in the payload type.

08Open decisions

Five choices that change the shape of the work. My recommendation is marked; push back freely — that's what this doc is for.

09Suggested build order

Sequenced so each phase compiles green and ships value on its own. Pill = rough size.

• P0Declare scopeS

  Add ToolScope + AiToolName::scope() and AiAgentToolName::scope(). No behaviour change — just makes scope explicit and reviewable. Unblocks everything else.

• P1Unify the registryL

  Move collect_rig_tools into the neutral home (Q1), introduce ToolContext + build_tools(allowlist, ctx, scope_filter), fold the two catalogs (Q2). Assistant and agent paths become thin callers. Behaviour preserved; tests pin the same tool sets.

• P2Granular domain allowlistM

  Expand attach_domain_tools into a recommended shared subset (Q3); let an agent's tools_allowlist name individual domain tools. Update the capabilities UI so owners pick exactly what an agent may do.

• P3Schedule toolsM

  create_schedule / cancel_schedule / list_my_schedules over the existing services + the Once recurrence variant + scheduled-wake contact context. Delivers the headline use case. Gate behind Q4's trust rules.

• P4Reclassify the straysS

  Settle delegate_bulk_operation (Q5) and confirm set_member_personalization stays assistant-only under the new scope filter.

• P5Optional: learning & planning toolsLATER

  record_lesson / reflect_now over run_learning_digest, and eventually present_plan for #1479. Defer until P0–P3 are proven.