Long-horizon agents — plan, approve, execute

Decision · TL;DR

01Why a planning primitive

Planning a complex task is a capability we want for any agent, not a feature of one workflow. Claude Code already models this well — we adapt it.

What we borrow from Claude Code plan mode

• Read-only plan phase. The agent explores with safe/read tools; mutations are withheld until a plan is approved. (In CC, writes never auto-approve in plan mode.)
• Present → approve → execute. A discrete proposal, a decision, then execution under a chosen permission posture.
• Approval is a policy, not always a human. CC's permission modes (default · acceptEdits · plan · auto · dontAsk · bypassPermissions) span interactive → autonomous, and canUseTool / hooks decide approval programmatically per action.

Approval policy ← permission modes

"Some plans auto-approve so the human isn't in the loop" = Auto / RiskGated. Sending real SMS is high-impact → HumanReview in v1, but the enum + hook exist so other agents/tasks can auto-approve without a rebuild.

02Anatomy of an AgentPlan

A general envelope (human-readable + auditable) wrapping a typed, extensible action. The action is what an executor knows how to run.

struct AgentPlan {
    id: Uuid,
    organization_id: Uuid,
    agent_id: Uuid,              // which agent authored it (e.g. the assistant clone)
    thread_id: Option<Uuid>,    // the conversation it came from
    title: String,             // "Follow up with 142 quiet quote leads"
    summary: String,           // human-readable rationale, rendered at review
    action: PlanAction,        // the typed, executable payload (below)
    approval_policy: ApprovalPolicy,
    status: PlanStatus,
    created_by: Option<Uuid>,
    approved_by: Option<Uuid>, approved_at: Option<DateTime>,
    executed_ref: Option<Uuid>,    // e.g. the assistant_operation it spawned
}

enum PlanAction {            // extensible — one variant implemented in v1
    BulkSmsCampaign {
        audience: Vec<ContactDecision>,  // { contact_id, include, reason, kind }
        message_concept: String,        // the idea, not the final text
    },
    // future: ContactCleanup { … }, ScheduleFollowUps { … }, EnrichContacts { … }
}

enum ApprovalPolicy { HumanReview, Auto, RiskGated }
enum PlanStatus { Drafting, AwaitingApproval, Approved, Rejected, Executing, Done, Failed }

03The plan lifecycle

Two gates remain, but they're now different kinds: plan approval (general, in the thread — the audience + the idea) and draft review (bulk-specific, the existing sheet — the actual messages). Auto-approval skips the first; the second stays a deliberate safety stop for sending real SMS.

04Approval & auto-approve

One resolver decides whether a plan pauses for a human. It's the seam where "agent autonomy" is tuned.

fn resolve_approval(agent: &Agent, plan: &AgentPlan) -> Decision {
    match plan.approval_policy {
        HumanReview => Decision::Gate,
        Auto       => Decision::Proceed,
        RiskGated  => assess_risk(plan),   // the canUseTool / permission_policy analog
    }
}
// v1 assess_risk: sends messages OR spends money OR mutates > N rows ⇒ Gate; else Proceed.

• v1 stance: BulkSmsCampaign is hardwired to HumanReview — real messages, real cost, irreversible. No auto-send in v1.
• The hook is the autonomy dial. Per-agent default policy + per-action override + assess_risk. Today it always gates bulk; tomorrow a trusted agent can auto-approve a read-only enrichment plan.
• Audit: every plan records policy + decision + approver + timestamp, so an auto-approved plan is as inspectable as a gated one.

05Bulk SMS as the first consumer

The feature you started from is now one PlanAction + one executor handler. Everything campaign-specific lives here; the primitive stays generic.

06The executor we reuse

The bulk engine is already durable and well-built. It executes the approved plan unchanged, save for consuming the concept.

07Data model

One new general table; a two-column touch on the bulk operation. The audience/exclusions live in the plan, so the item schema is untouched.

New new — ai_agent_plan (general)

CREATE TABLE ai_agent_plan (
  id               UUID PRIMARY KEY,
  organization_id  UUID NOT NULL REFERENCES organization(id),
  agent_id         UUID NOT NULL REFERENCES ai_agent(id),
  thread_id        UUID REFERENCES ai_thread(id),
  title            VARCHAR(255) NOT NULL,
  summary          TEXT NOT NULL,
  action_type      VARCHAR(48) NOT NULL,      // "bulk_sms_campaign"
  action_payload   JSONB NOT NULL,            // the typed PlanAction (audience + concept)
  approval_policy  VARCHAR(24) NOT NULL,      // human_review | auto | risk_gated
  status           VARCHAR(24) NOT NULL,      // drafting | awaiting_approval | …
  created_by       UUID REFERENCES "user"(id),
  approved_by      UUID REFERENCES "user"(id),
  approved_at      timestamptz,
  executed_ref     UUID,                      // the assistant_operation it spawned
  created_at       timestamptz NOT NULL,
  updated_at       timestamptz NOT NULL
);
CREATE INDEX idx_ai_agent_plan_org_status ON ai_agent_plan (organization_id, status);

Touch change — assistant_operation

ALTER TABLE assistant_operation
  ADD COLUMN message_concept TEXT,                // the approved idea, used by the drafter
  ADD COLUMN plan_id         UUID REFERENCES ai_agent_plan(id);  // provenance

No new column — the toggle lives in config_payload reuse

Planning is opt-in per agent via the existing ai_agent.config_payload JSONB (same place #1476 reads agent_rules): planning_enabled: bool (default false) + plan_approval: "human_review"|"auto"|"risk_gated" (default human_review). No schema change on ai_agent — mirrors how agent_rules is stored, and keeps the cached static prompt prefix byte-stable when off.

08Planning as an agent capability

Not assistant-only. Any agent can be given planning — the owner toggles it on, and the runtime layers the capability onto #1476's tiered prompt.

The toggle (per-agent config)

Planning rides on the same config_payload that #1476/#1478 use for agent_rules. Two keys, default off:

// ai_agent.config_payload
{
  "agent_rules": "…",                 // (#1476)
  "planning_enabled": true,           // "Let this agent plan complex tasks" — default false
  "plan_approval": "human_review"     // human_review | auto | risk_gated — default human_review
}

• Surfaced in the agent config UI (the #1478 instructions/rules editor): a "Planning" toggle + an approval-mode selector ("Always review my agent's plans" / "Let it proceed on low-risk plans"). This is the "user can check if they want the agents to plan" control.
• Generic across agent types — Text Reply, voice, the assistant, custom agents. Default off means today's behaviour is unchanged until an owner opts in.

What turning it on does — two gated additions

The planning turn itself

• List-aware via existing domain tools. A domain agent already attaches the Session-bound toolset (attach_domain_tools). Planning reuses those reads — contacts, tags, custom fields, recent messages, opt-out — to build and justify the audience. No new planner model area.
• Read-only invariant. During a planning turn the runtime withholds mutating tools (send SMS, write contact) and offers present_plan as the terminal action. The only mutation is post-approval execution. (This is the one place #1476's "you act only by calling tools" contract needs a planning-mode complement — withhold the writing tools.)

09Execution & the worker

On approval, a thin dispatcher maps the action to a handler. The per-contact drafter barely changes.

async fn dispatch(plan: AgentPlan) -> Result<(), AppError> {
    match plan.action {
        PlanAction::BulkSmsCampaign { audience, message_concept } => {
            let included = audience.iter().filter(|d| d.include).map(|d| d.contact_id);
            let op = create_bulk_operation(included, message_concept, …).await?;  // opt-out safety net inside
            spawn_draft_engine(op.operation_id);
            set_executed_ref(plan.id, op.operation_id).await?;
        }
    }
}

Fan-out (20 concurrent), claim batch (50), prefetch, counters, websockets, send path — all untouched.

10UI surfaces

Progressive disclosure: the plan card defaults to summary + concept + counts; the full included/excluded lists expand on demand (mirrors the engine review sheet and the UX-principles disclosure rules). Auto-approved plans skip the card and post a "plan auto-approved → executing" note instead.

11Learning loop later

Both decisions are signal, and now they attach to a clean entity — the plan.

Both feed the authoring agent's ai_agent_learning / ai_agent_lesson (evergreen, versioned; weekly agent cadence). Because the plan records its agent_id, this works for any planning agent, not just the campaign case.

12Build phases

Build the primitive thin, shaped by the one real consumer; prove it with bulk SMS. Compliance fix lands first.

• P1Opt-out pre-filter (compliance)S

  Add opt-out + dupe to create_bulk_operation's deterministic skip. Independent of everything else — closes the live gap now.

  bulk_operation_engine_service.rs · opt-out read helper

• P2ai_agent_plan entity + lifecycleM

  Migration + types (PlanStatus, ApprovalPolicy, PlanAction envelope); persistence; resolve_approval + assess_risk stub. just generate.

  migration/… · mods/ai_agent/types/… · services/ai_agent_plan_service.rs (new)

• P3present_plan tool + PLANNING_BLOCK tier + read-only postureL

  New ai_agent tool (schema = AgentPlan); runtime persists, resolves policy, gates or auto-dispatches. Add the PLANNING_BLOCK prompt tier to build_system_prompt + offer present_plan, both gated by config_payload.planning_enabled; withhold mutating tools during a planning turn. Builds on #1476's tiered build_system_prompt — rebase on it.

  mods/ai_agent/tools/present_plan_tool.rs (new) · build_system_prompt_service.rs (#1476) · run_ai_agent_thread_service.rs · tool_registry

• P4PlanExecutor + BulkSmsCampaign handlerM

  Dispatcher; BulkSmsCampaign → create_bulk_operation + spawn_draft_engine; thread message_concept into the drafter; set executed_ref. Retarget delegate_bulk_operation as the handler.

  services/plan_executor_service.rs (new) · bulk_operation_engine_service.rs · follow_up_drafter_extractor_service.rs · delegate_bulk_operation.rs

• P5Plan APIs + review cardM

  GET plan · PUT plan (edit concept / include-exclude, opt-out re-include blocked) · POST approve / reject. Plan card in the thread; auto-approve note path.

  mods/ai_agent/api/ai_agent_plan_api.rs (new) · components/agent_plan_card_component.rs (new)

• P6Per-agent toggle + config UIM

  Read/write config_payload.planning_enabled + plan_approval; add a "Planning" toggle + approval-mode selector to the agent instructions/rules editor. Lands in #1478's config UI (or extends it). Default off → no behaviour change until an owner opts in.

  #1478 agent config UI · ai_agent config DTOs / api

• P7Learning signals laterM

  Plan-gate + draft-gate edits → ai_agent_lesson on the authoring agent. Gated behind the flow shipping.

  ai_agent learning services · plan card + draft sheet

13Open decisions

14Files to touch

15Risks & non-goals

• Non-goal: agent-per-contact drafting (⑤) or a live operation thread (④). Drafting stays a cheap extractor the executor fans out.
• Non-goal: auto-sending bulk SMS in v1. BulkSmsCampaign is always HumanReview; auto-approve is for future low-risk actions.
• Non-goal: per-segment concepts, multi-action plans, plan templates — the envelope leaves room; none built now.