feat(unstable): Add unstable plan operations (#1299)

Author: benbrandt

Cargo.toml

@@ -22,6 +22,7 @@ unstable = [
     "unstable_llm_providers",
     "unstable_mcp_over_acp",
     "unstable_nes",
+    "unstable_plan_operations",
     "unstable_session_additional_directories",
     "unstable_session_delete",
     "unstable_session_fork",
@@ -41,6 +42,7 @@ unstable_elicitation = []
 unstable_llm_providers = []
 unstable_mcp_over_acp = []
 unstable_nes = []
+unstable_plan_operations = []
 unstable_session_additional_directories = []
 unstable_session_delete = []
 unstable_session_fork = []

docs/protocol/draft/agent-plan.mdx

@@ -7,6 +7,8 @@ Plans are execution strategies for complex tasks that require multiple steps.
 
 Agents may share plans with Clients through [`session/update`](./prompt-turn#3-agent-reports-output) notifications, providing real-time visibility into their thinking and progress.
 
+The existing `plan` update is the baseline format. Clients that advertise `planCapabilities` during [initialization](./initialization#client-capabilities) 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:
@@ -46,6 +48,96 @@ When the language model creates an execution plan, the Agent **SHOULD** report i
   accomplished
 </ParamField>
 
+## Plan Operations
+
+Agents **MUST NOT** send `plan_update` or `plan_removed` unless the Client advertised `planCapabilities`. If the Client omits `planCapabilities`, 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 `id` so Clients can track multiple plans independently.
+
+### Item-Based Plans
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "session/update",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "update": {
+      "sessionUpdate": "plan_update",
+      "plan": {
+        "type": "items",
+        "id": "plan-1",
+        "entries": [
+          {
+            "content": "Analyze the existing codebase structure",
+            "priority": "high",
+            "status": "pending"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+### Markdown Plans
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "session/update",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "update": {
+      "sessionUpdate": "plan_update",
+      "plan": {
+        "type": "markdown",
+        "id": "implementation-plan",
+        "content": "## Steps\n- [ ] Refactor module\n- [ ] Add tests"
+      }
+    }
+  }
+}
+```
+
+### File Plans
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "session/update",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "update": {
+      "sessionUpdate": "plan_update",
+      "plan": {
+        "type": "file",
+        "id": "design-doc",
+        "uri": "file:///tmp/plan.md"
+      }
+    }
+  }
+}
+```
+
+### Removing Plans
+
+Agents can remove a plan by sending `plan_removed` with the plan ID:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "session/update",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "update": {
+      "sessionUpdate": "plan_removed",
+      "id": "plan-1"
+    }
+  }
+}
+```
+
 ## Plan Entries
 
 Each plan entry represents a specific task or goal within the overall execution strategy: