Agent prompting architecture

00TL;DR

01How prompts are built today

One generic agent turn assembles a single system-prompt string, then passes the user/contact input as a separate message role. Here is the literal shape produced by build_system_prompt().

Key properties of the current generic path:

• Persona + goals are interpolated verbatim and are operator-editable. That is correct for voice/brand content, but today it is also where delivery mechanics live (“Use only the tools available to you this turn…”) — runtime concerns trapped in editable prose.
• The tool block is just names. The model is told which tools exist by name; rig forwards the real {name, description, input_schema} separately. There is no narrative of how / when to use them, and crucially no statement that calling a tool is the only way to act.
• Untrusted input is correctly isolated from the system prompt (passed as Message::user) — good injection hygiene — but the two user sources are flattened to identical bare text.
• The capture struct already has the slots for a layered prompt — they're just empty:

// ai_thread_log_entry_type.rs — filled with String::new() today
pub struct AiThreadLogEffectivePromptCapture {
    platform_rules:  String,   // ← Phase 3 placeholder (empty)
    org_rules:       String,   // ← Phase 3 placeholder (empty)
    agent_rules:     String,   // ← Phase 3 placeholder (empty)
    persona:         String,   // ← the only operator content wired
    goals:           String,
    learning:        String,   // ← Phase 8 placeholder (empty)
    pending_lessons: Vec<String>,
    skills:          Vec<String>,
    invokable_agents: Vec<String>,
    memory_snapshot: Option<String>,  // on-demand via tool
    delegated_context: String,  // ← the one wired runtime block
    thread_context:  String,
}

02The two-track problem

The Assistant already has the layered, capability-aware prompt we want every agent to have. The generic agents don't. The gap between them is the work.

03Prompting best practices we should follow

Drawn from Anthropic's Claude 4.x guidance and the project's own add-rig-tool standard. These are the principles the layered model is designed to satisfy.

04The layered instruction model

Five tiers (plus a Phase-3 rules layer). Each has exactly one owner and one injection point. The rule for any new instruction: find its tier, and that tells you who writes it and where it goes.

Assembled order (proposed)

05Where each instruction lives

The decision table. For each kind of instruction: its tier, who owns it, how it's injected, and whether the operator can edit it. This is the direct answer to "what goes in the core vs the agent vs a skill."

06Mandatory & system-wide skills

Skills today are purely opt-in: a skill reaches an agent only through an enabled ai_agent_skill_link row. There is no way to say "this guidance applies to all messaging agents, no opt-in." That's the missing piece you flagged.

Current mechanics

• A skill = {title, short_description, body_markdown, organization_id, is_active}. Platform skills have organization_id = NULL.
• Attach = a row in ai_agent_skill_link(agent_id, skill_id, is_enabled). The loader selects links where is_enabled = true, then loads active skills with an org-scope guard, and concatenates their bodies under ## {title}.
• No notion of mandatory, applicability, or precedence. An unlinked skill is invisible to the agent.

Two ways to model "mandatory system-wide"

07The three #1476 gaps, mapped to the model

Each acceptance-criterion failure is a missing tier. The model tells us exactly where the fix goes.

• GAP 1The agent never delivers a replyTier 1 + Tier 0

  In autonomous mode the model writes prose it believes is sent; the runtime only records it. The only delivery path is an explicit send_sms call, and nothing tells the model that. Fix: a capability-derived delivery block (Tier 1) that states the send-mandate when send_mode=autonomous, reinforced by the Tier-0 "plain text ≠ delivery" contract. This is the exact shape of the existing DELEGATED_SUBAGENT_BLOCK — reuse that pattern.

• GAP 2Can't tell operator from contactTier 0 + Tier 4

  as_text() returns the bare body for both InboundSms and UserMessage, so operator steering and contact messages are indistinguishable — and a contact message could read as an instruction (injection risk). Fix: a per-event source envelope (Tier 4) — [Incoming SMS from {contact} <{e164}>] vs [Operator instruction — not the contact], with the contact body sanitized — plus a Tier-0 rule that explains how to read the two sources.

• GAP 3Replies with no groundingTier 0

  The agent answers without consulting the contact's profile, history, notes, memory, or knowledge. Fix: a Tier-0 grounding directive — "before composing a reply or taking an action, gather the contact's context with your available read tools" — pairing with the operator-authored "never invent facts" already in persona.

08Concrete changes

The minimal-but-foundational build: everything #1476 needs, shaped so it instantiates the model rather than bolting on one-offs. Mapped to the issue's File Changes.

• C1Platform core block (Tier 0)build_system_prompt_service.rs

  Add a constant core block (sibling to DELEGATED_SUBAGENT_BLOCK) injected for domain agents: identity-of-runtime, "plain text ≠ delivery / act via tools", the operator≠contact contract, the grounding directive. Populate the platform_rules capture field instead of String::new(). Gate on attach_domain_tools so tool-less agents stay lean.

• C2Capability / delivery block (Tier 1)run_ai_agent_thread_service.rs / build_system_prompt

  Derive the delivery instruction from the resolved send_mode + the actual reply context: autonomous → "reply via send_sms (sends from the contact's line)"; suggest → "draft options via propose_sms_replies." Move this out of the Text Reply persona so the instruction always matches the live tool set. Decide: assemble in the executor (has the tool set) vs pass a flag into build_system_prompt.

• C3Per-event source framing (Tier 4)ai_thread_event_payload_type.rs + executor

  Add a framed renderer (e.g. as_framed_text() or a builder-side wrapper) that prefixes each event with its source and sanitizes the contact body via the existing sanitize_for_prompt / strip_prompt_newlines helpers. Use it where the turn prompt is joined (:269). Keep as_text() for non-prompt uses or migrate call sites deliberately.

• C4Trim the Text Reply persona (Tier 2)new seed migration

  Remove the delivery-mechanic lines ("Use only the tools available to you this turn…", the send-vs-draft branch) now carried by C1/C2; keep voice/brand/escalation/no-fabrication. Migrations are immutable — this is a new migration that updates the persona/goals of the base agent (and decides whether to re-sync existing unedited clones), not an edit to m20260611_130003.

• C5Non-regression guardstests

  Suggest mode still drafts via propose_sms_replies; ownerless/sessionless agents still degrade to no domain tools (and so get no Tier-1 send block); delegated sub-agents keep their block. Add prompt-assembly unit tests mirroring the existing ones in build_system_prompt_service.rs.

09Open decisions

The choices I'd like to lock before writing code. My recommendation is pre-selected; push back on any of them.