plan-operations.mdx

title	Plan Operations Support

Author(s):

Elevator pitch

What are you proposing to change?

Introduce a new plan_update session update type that supports multiple plan formats (item-based, file-based, markdown text), multiple concurrent plans via IDs, and plan removal. The existing plan session update type remains unchanged for backward compatibility.

Status quo

How do things work today and what problems does this cause? Why would we change things?

• The plan session update contains entries: Vec<PlanEntry> — a flat list of items with priority/status
• Plans are one-way notifications (agent → client) via session/update
• No plan identity — each update replaces the previous plan entirely
• No way to remove/dismiss a plan once sent
• Only one plan representation (structured items) — no support for free-form markdown or file-based plans

What we propose to do about it

What are you proposing to improve the situation?

Add a new SessionUpdate variant — plan_update — that carries a plan field. The plan field is a tagged union (discriminated by type) with the following variants:

Type	Description	Specific fields
items	Structured entries (same semantics as today's plan)	entries: PlanEntry[]
file	Agent provides a file URI containing the plan	uri: string
markdown	Agent provides raw markdown text	content: string

All variants carry a required id: string that identifies the plan, and an optional _meta for extensibility.

Additionally, introduce a plan_removed session update type that carries only a plan id to signal dismissal. This keeps plan_update focused purely on content updates and makes removal a distinct, self-describing event.

The existing plan session update type is not modified and continues to work as before. Agents that want multi-plan support, new plan formats, or removal capabilities use plan_update and plan_removed instead.

Client Capabilities

Add to ClientCapabilities:

planCapabilities: PlanCapabilities? = null

When present ({}), signals the client supports the plan_update and plan_removed session update types. When absent, the agent must fall back to the existing plan session update type.

Multiple Plans

The id field on every plan variant identifies a specific plan.

• Each plan_update targets the plan with the given id
• Client tracks plans by ID; updates replace the content of that specific plan
• Different plans may use different types (e.g., one items plan and one markdown plan)

Plan Removal

Agent sends a plan_removed session update with the plan's id to dismiss it. This is a separate session update type from plan_update, keeping content updates and lifecycle events distinct.

Shiny future

How will things will play out once this feature exists?

Agents will be able to present plans in the format most natural to them — structured checklists for step-by-step execution, markdown for free-form design docs, or file URIs for large plans generated externally. Clients that support plan_update can show multiple concurrent plans (e.g., a high-level strategy and a detailed implementation checklist), and dismiss plans that are no longer relevant. Clients that don't advertise planCapabilities continue to receive the existing plan updates with no changes.

Implementation details and plan

Tell me more about your implementation. What is your detailed implementation plan?

Json Format Examples

Existing plan (unchanged):

{
  "sessionUpdate": "plan",
  "entries": [{ "content": "Step 1", "priority": "high", "status": "pending" }]
}

Item-based (plan_update):

{
  "sessionUpdate": "plan_update",
  "plan": {
    "type": "items",
    "id": "plan-1",
    "entries": [
      { "content": "Step 1", "priority": "high", "status": "pending" }
    ]
  }
}

Markdown:

{
  "sessionUpdate": "plan_update",
  "plan": {
    "type": "markdown",
    "id": "plan-1",
    "content": "## Steps\n- [ ] Refactor module\n- [ ] Add tests"
  }
}

File-based:

{
  "sessionUpdate": "plan_update",
  "plan": {
    "type": "file",
    "id": "design-doc",
    "uri": "file:///tmp/plan.md"
  }
}

Removal:

{
  "sessionUpdate": "plan_removed",
  "id": "plan-1"
}

Frequently asked questions

What questions have arisen over the course of authoring this document or during subsequent discussions?

Why a new session update type instead of extending the existing plan?

The existing plan variant flattens Plan's entries field directly into the SessionUpdate discriminated union object. Adding a nested plan field, optional id, and polymorphic types to the same variant would require breaking the existing format or complex dual-deserialization logic. A new plan_update variant avoids this entirely — old clients ignore it, new clients handle both.

Why a separate plan_removed session update type instead of a removal variant inside plan_update?

Keeping removal as a separate session update type means plan_update's type discriminator only covers content variants (items, file, markdown), making the schema cleaner.

Why plan-specific markdown and not a generic markdown content API?

A generic "agent shares markdown document" API would be simpler and more reusable. However, keeping it plan-typed enables clients to build plan-aware UX: selecting plan steps for partial execution, tracking plan progress, showing plan history. A generic markdown block wouldn't carry this semantic meaning. If future use cases need generic markdown sharing, that can be a separate feature.

What alternative approaches did you consider, and why did you settle on this one?

1. Extending the existing plan variant: Would break backward compatibility or require complex dual-format deserialization.
2. "type": "removed" variant inside plan_update: Instead of a separate plan_removed session update type, removal could be a variant in the plan_update tagged union (e.g., "type": "removed"). This keeps the entire plan lifecycle within a single update type. The tradeoff is that the type discriminator mixes content variants with a lifecycle event, making the schema less clean.

Revision history