Skip to main content
A plan is the Agent’s list of steps for a multi-step task. Each entry has a description, a priority, and a status. Agents may send plans to Clients through session/update notifications and update them as work progresses. The existing plan update is the baseline format. Clients that advertise plan during initialization can also receive identified plan operations through plan_update and plan_removed.

Creating plans

When the language model creates an execution plan, the Agent SHOULD report it to the Client:
PlanEntry[]
required
An array of plan entries representing the tasks to be accomplished

Plan operations

Agents MUST NOT send plan_update or plan_removed unless the Client advertised plan. If the Client omits plan, the Agent MUST fall back to the existing plan update. plan_update carries a plan object with a type discriminator. Every plan format includes a required planId so Clients can track multiple plans independently. When the Client advertised plan, the Agent SHOULD send its plans with plan_update instead of the plan update. Each plan_update replaces the whole plan with that planId, whatever its type, including when the type differs from the previous update.

Item-based plans

Markdown plans

string
required
The plan as Markdown.
string | null
The absolute path of the file that holds this plan. Omission and null are equivalent and mean the plan has no file.
path MUST be an absolute path. content is the plan to display whether or not path is set. Clients render content and don’t need to read the file. Clients can use path to open the file.

Removing plans

Agents can remove a plan by sending plan_removed with the plan ID:
Agents SHOULD send plan_removed when a plan is cancelled, for example when the user rejects it or the Agent abandons it. A finished plan doesn’t need to be removed. Clients MUST ignore plan_removed for a planId they don’t know.

Plan entries

Each plan entry represents a specific task or goal within the overall execution strategy:
string
required
A human-readable description of what this task aims to accomplish
PlanEntryPriority
required
The relative importance of this task.
  • high
  • medium
  • low
PlanEntryStatus
required
The current execution status of this task
  • pending
  • in_progress
  • completed

Updating plans

As the Agent progresses through the plan, it SHOULD report updates by sending more session/update notifications with the same structure. The Agent MUST send a complete list of all plan entries in each update and their current status. The Client MUST replace the current plan completely. For plan_update, the Agent sends updates with the same planId. For item-based plans, the Agent MUST send a complete list of all plan entries in each update and their current status, and the Client MUST replace the current contents of that plan completely. An empty entries array empties the plan. Clients MAY hide an empty plan.

Dynamic planning

Plans can change during execution. The Agent MAY add, remove, or modify plan entries as it discovers new requirements or completes tasks.