Checkpoint: Stabilizing commands

Author: agu-z

docs/docs.json

@@ -59,6 +59,7 @@
           "protocol/terminals",
           "protocol/agent-plan",
           "protocol/session-modes",
+          "protocol/commands",
           "protocol/extensibility",
           "protocol/schema"
         ]

docs/protocol/commands.mdx

@@ -0,0 +1,109 @@
+---
+title: "Commands"
+description: "Advertise available slash commands to clients"
+---
+
+Agents can advertise a set of slash commands that users can invoke. These commands provide quick access to specific agent capabilities and workflows.
+
+## Advertising commands
+
+After creating a session, the Agent **MAY** send a list of available commands via the `available_commands_update` session notification:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "session/update",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "update": {
+      "sessionUpdate": "available_commands_update",
+      "availableCommands": [
+        {
+          "name": "web",
+          "description": "Search the web for information",
+          "input": {
+            "hint": "query to search for"
+          }
+        },
+        {
+          "name": "test",
+          "description": "Run tests for the current project"
+        },
+        {
+          "name": "plan",
+          "description": "Create a detailed implementation plan",
+          "input": {
+            "hint": "description of what to plan"
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+<ResponseField name="availableCommands" type="AvailableCommand[]">
+  The list of commands available in this session
+</ResponseField>
+
+### AvailableCommand
+
+<ResponseField name="name" type="string" required>
+  The command name (e.g., "web", "test", "plan")
+</ResponseField>
+
+<ResponseField name="description" type="string" required>
+  Human-readable description of what the command does
+</ResponseField>
+
+<ResponseField name="input" type="AvailableCommandInput">
+  Optional input specification for the command
+</ResponseField>
+
+### AvailableCommandInput
+
+Currently supports unstructured text input:
+
+<ResponseField name="hint" type="string" required>
+  A brief description of the expected input
+</ResponseField>
+
+## Command lifecycle
+
+1. **Discovery**: The Agent sends available commands after session creation
+2. **Display**: The Client displays these commands in its UI (e.g., in a slash command menu)
+3. **Invocation**: When the user selects a command, the Client includes it in the prompt
+4. **Execution**: The Agent processes the command as part of the prompt
+
+Commands are not a separate protocol mechanism - they are simply a way for the Agent to advertise what slash commands it understands. The actual command invocation happens through the regular prompt mechanism.
+
+## Dynamic updates
+
+The Agent can update the list of available commands at any time during a session by sending another `available_commands_update` notification. This allows commands to be:
+
+- Added based on context (e.g., project type detection)
+- Removed when no longer relevant
+- Modified with updated descriptions or input hints
+
+Clients may also add their own local commands (e.g., authentication commands) to the list before displaying them to users.
+
+## Example usage
+
+When a user types `/web climate change` in the Client, it would send:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "session/prompt",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "prompt": {
+      "type": "text",
+      "text": "/web climate change"
+    }
+  }
+}
+```
+
+The Agent recognizes the command prefix and processes it accordingly, potentially using web search tools to gather information about climate change.

docs/protocol/schema.mdx

@@ -1098,6 +1098,8 @@ Information about a command.
 
 ## <span class="font-mono">AvailableCommandInput</span>
 
+The input specification for a command.
+
 **Type:** Union
 
 <ResponseField name="Object">
@@ -2225,6 +2227,8 @@ Available commands are ready or have changed
 <ResponseField name="current_mode_update">
 The current mode of the session has changed
 
+See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)
+
 <Expandable title="Properties">
 
 <ResponseField

rust/client.rs

@@ -214,22 +214,20 @@ pub enum SessionUpdate {
     /// See protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/agent-plan)
     Plan(Plan),
     /// Available commands are ready or have changed
-    #[cfg(feature = "unstable")]
     #[serde(rename_all = "camelCase")]
-    #[schemars(extend("x-docs-ignore" = true))]
     AvailableCommandsUpdate {
         available_commands: Vec<AvailableCommand>,
     },
     /// The current mode of the session has changed
+    ///
+    /// See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)
     #[serde(rename_all = "camelCase")]
-    // todo!
     CurrentModeUpdate { current_mode_id: SessionModeId },
 }
 
 /// Information about a command.
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
 #[serde(rename_all = "camelCase")]
-#[cfg(feature = "unstable")]
 pub struct AvailableCommand {
     /// Command name (e.g., "create_plan", "research_codebase").
     pub name: String,
@@ -242,9 +240,9 @@ pub struct AvailableCommand {
     pub meta: Option<serde_json::Value>,
 }
 
+/// The input specification for a command.
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
 #[serde(untagged, rename_all = "camelCase")]
-#[cfg(feature = "unstable")]
 pub enum AvailableCommandInput {
     /// All text that was typed after the command name is provided as input.
     #[schemars(rename = "UnstructuredCommandInput")]

rust/example_client.rs

@@ -98,7 +98,8 @@ impl acp::Client for ExampleClient {
             | acp::SessionUpdate::ToolCall(_)
             | acp::SessionUpdate::ToolCallUpdate(_)
             | acp::SessionUpdate::Plan(_)
-            | acp::SessionUpdate::CurrentModeUpdate { .. } => {}
+            | acp::SessionUpdate::CurrentModeUpdate { .. }
+            | acp::SessionUpdate::AvailableCommandsUpdate { .. } => {}
         }
         Ok(())
     }

rust/rpc_tests.rs

@@ -727,6 +727,7 @@ async fn test_full_conversation_flow() {
                             found_tool_update = true;
                         }
                     }
+                    SessionUpdate::AvailableCommandsUpdate { .. } => {}
                     _ => {}
                 }
             }

schema/schema.json

@@ -262,7 +262,8 @@
           "title": "UnstructuredCommandInput",
           "type": "object"
         }
-      ]
+      ],
+      "description": "The input specification for a command."
     },
     "BlobResourceContents": {
       "description": "Binary resource contents.",
@@ -1715,11 +1716,10 @@
             }
           },
           "required": ["sessionUpdate", "availableCommands"],
-          "type": "object",
-          "x-docs-ignore": true
+          "type": "object"
         },
         {
-          "description": "The current mode of the session has changed",
+          "description": "The current mode of the session has changed\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)",
           "properties": {
             "currentModeId": {
               "$ref": "#/$defs/SessionModeId"

typescript/schema.ts

@@ -401,6 +401,9 @@ export type SessionModeId = string;
  */
 /** @internal */
 export type AgentNotification = SessionNotification | ExtNotification1;
+/**
+ * The input specification for a command.
+ */
 export type AvailableCommandInput = UnstructuredCommandInput;
 
 /**