Add custom commands support via list_commands and run_command

- Add session/list_commands method to retrieve available custom commands
- Add session/run_command method to execute custom commands with arguments
- Add CommandInfo type with name, description, and requiresArgument fields
- Add supportsCustomCommands to PromptCapabilities
- Update schema documentation and generated TypeScript bindings
- Implement empty command handlers in example and test agents

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: nathansobo

docs/protocol/schema.mdx

@@ -92,7 +92,7 @@ See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/ini
 <ResponseField name="agentCapabilities" type={<a href="#agentcapabilities">AgentCapabilities</a>} >
   Capabilities supported by the agent.
 
-    - Default: `{"loadSession":false,"promptCapabilities":{"audio":false,"embeddedContext":false,"image":false}}`
+    - Default: `{"loadSession":false,"promptCapabilities":{"audio":false,"embeddedContext":false,"image":false,"supportsCustomCommands":false}}`
 
 </ResponseField>
 <ResponseField name="authMethods" type={<><span><a href="#authmethod">AuthMethod</a></span><span>[]</span></>} >
@@ -143,6 +143,53 @@ See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/promp
   The ID of the session to cancel operations for.
 </ResponseField>
 
+<a id="session-list_commands"></a>
+### <span class="font-mono">session/list_commands</span>
+
+Lists available custom commands for a session.
+
+Returns all commands available in the agent's `.claude/commands` directory
+or equivalent command registry. Commands can be executed via `run_command`.
+
+#### <span class="font-mono">ListCommandsRequest</span>
+
+Request parameters for listing available commands.
+
+**Type:** Object
+
+**Properties:**
+
+<ResponseField
+  name="sessionId"
+  type={<a href="#sessionid">SessionId</a>}
+  required
+>
+  The session ID to list commands for.
+</ResponseField>
+
+#### <span class="font-mono">ListCommandsResponse</span>
+
+Response containing available commands.
+
+**Type:** Object
+
+**Properties:**
+
+<ResponseField
+  name="commands"
+  type={
+    <>
+      <span>
+        <a href="#commandinfo">CommandInfo</a>
+      </span>
+      <span>[]</span>
+    </>
+  }
+  required
+>
+  List of available commands.
+</ResponseField>
+
 <a id="session-load"></a>
 ### <span class="font-mono">session/load</span>
 
@@ -323,6 +370,36 @@ See protocol docs: [Check for Completion](https://agentclientprotocol.com/protoc
   Indicates why the agent stopped processing the turn.
 </ResponseField>
 
+<a id="session-run_command"></a>
+### <span class="font-mono">session/run_command</span>
+
+Executes a custom command within a session.
+
+Runs the specified command with optional arguments. The agent should
+stream results back via session update notifications.
+
+#### <span class="font-mono">RunCommandRequest</span>
+
+Request parameters for executing a command.
+
+**Type:** Object
+
+**Properties:**
+
+<ResponseField name="args" type={"string | null"}>
+  Optional arguments for the command.
+</ResponseField>
+<ResponseField name="command" type={"string"} required>
+  Name of the command to execute.
+</ResponseField>
+<ResponseField
+  name="sessionId"
+  type={<a href="#sessionid">SessionId</a>}
+  required
+>
+  The session ID to execute the command in.
+</ResponseField>
+
 ## Client
 
 Defines the interface that ACP-compliant clients must implement.
@@ -539,7 +616,7 @@ See protocol docs: [Agent Capabilities](https://agentclientprotocol.com/protocol
 <ResponseField name="promptCapabilities" type={<a href="#promptcapabilities">PromptCapabilities</a>} >
   Prompt capabilities supported by the agent.
 
-    - Default: `{"audio":false,"embeddedContext":false,"image":false}`
+    - Default: `{"audio":false,"embeddedContext":false,"image":false,"supportsCustomCommands":false}`
 
 </ResponseField>
 
@@ -646,6 +723,24 @@ This capability is not part of the spec yet, and may be removed or changed at an
 
 </ResponseField>
 
+## <span class="font-mono">CommandInfo</span>
+
+Information about a custom command.
+
+**Type:** Object
+
+**Properties:**
+
+<ResponseField name="description" type={"string"} required>
+  Human-readable description of what the command does.
+</ResponseField>
+<ResponseField name="name" type={"string"} required>
+  Command name (e.g., "create_plan", "research_codebase").
+</ResponseField>
+<ResponseField name="requiresArgument" type={"boolean"} required>
+  Whether this command requires arguments from the user.
+</ResponseField>
+
 ## <span class="font-mono">ContentBlock</span>
 
 Content blocks represent displayable information in the Agent Client Protocol.
@@ -1151,6 +1246,12 @@ in prompt requests for pieces of context that are referenced in the message.
 
     - Default: `false`
 
+</ResponseField>
+<ResponseField name="supportsCustomCommands" type={"boolean"} >
+  Agent supports custom slash commands via `list_commands` and `run_command`.
+
+    - Default: `false`
+
 </ResponseField>
 
 ## <span class="font-mono">ProtocolVersion</span>

package-lock.json

@@ -216,6 +216,27 @@ impl Agent for ClientSideConnection {
             Some(ClientNotification::CancelNotification(notification)),
         )
     }
+
+    async fn list_commands(
+        &self,
+        arguments: ListCommandsRequest,
+    ) -> Result<ListCommandsResponse, Error> {
+        self.conn
+            .request(
+                SESSION_LIST_COMMANDS,
+                Some(ClientRequest::ListCommandsRequest(arguments)),
+            )
+            .await
+    }
+
+    async fn run_command(&self, arguments: RunCommandRequest) -> Result<(), Error> {
+        self.conn
+            .request(
+                SESSION_RUN_COMMAND,
+                Some(ClientRequest::RunCommandRequest(arguments)),
+            )
+            .await
+    }
 }
 
 /// Marker type representing the client side of an ACP connection.
@@ -509,6 +530,12 @@ impl Side for AgentSide {
             SESSION_PROMPT_METHOD_NAME => serde_json::from_str(params.get())
                 .map(ClientRequest::PromptRequest)
                 .map_err(Into::into),
+            SESSION_LIST_COMMANDS => serde_json::from_str(params.get())
+                .map(ClientRequest::ListCommandsRequest)
+                .map_err(Into::into),
+            SESSION_RUN_COMMAND => serde_json::from_str(params.get())
+                .map(ClientRequest::RunCommandRequest)
+                .map_err(Into::into),
             _ => Err(Error::method_not_found()),
         }
     }
@@ -551,6 +578,14 @@ impl<T: Agent> MessageHandler<AgentSide> for T {
                 let response = self.prompt(args).await?;
                 Ok(AgentResponse::PromptResponse(response))
             }
+            ClientRequest::ListCommandsRequest(args) => {
+                let response = self.list_commands(args).await?;
+                Ok(AgentResponse::ListCommandsResponse(response))
+            }
+            ClientRequest::RunCommandRequest(args) => {
+                self.run_command(args).await?;
+                Ok(AgentResponse::AuthenticateResponse) // No specific response type for run_command
+            }
         }
     }
 

rust/acp.rs

@@ -105,6 +105,21 @@ pub trait Agent {
     ///
     /// See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation)
     fn cancel(&self, args: CancelNotification) -> impl Future<Output = Result<(), Error>>;
+
+    /// Lists available custom commands for a session.
+    ///
+    /// Returns all commands available in the agent's `.claude/commands` directory
+    /// or equivalent command registry. Commands can be executed via `run_command`.
+    fn list_commands(
+        &self,
+        arguments: ListCommandsRequest,
+    ) -> impl Future<Output = Result<ListCommandsResponse, Error>>;
+
+    /// Executes a custom command within a session.
+    ///
+    /// Runs the specified command with optional arguments. The agent should
+    /// stream results back via session update notifications.
+    fn run_command(&self, arguments: RunCommandRequest) -> impl Future<Output = Result<(), Error>>;
 }
 
 // Initialize
@@ -368,6 +383,54 @@ pub struct PromptCapabilities {
     /// in prompt requests for pieces of context that are referenced in the message.
     #[serde(default)]
     pub embedded_context: bool,
+    /// Agent supports custom slash commands via `list_commands` and `run_command`.
+    #[serde(default)]
+    pub supports_custom_commands: bool,
+}
+
+// Slash commands
+
+/// Request parameters for listing available commands.
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[schemars(extend("x-side" = "agent", "x-method" = "session/list_commands"))]
+#[serde(rename_all = "camelCase")]
+pub struct ListCommandsRequest {
+    /// The session ID to list commands for.
+    pub session_id: SessionId,
+}
+
+/// Response containing available commands.
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[schemars(extend("x-side" = "agent", "x-method" = "session/list_commands"))]
+#[serde(rename_all = "camelCase")]
+pub struct ListCommandsResponse {
+    /// List of available commands.
+    pub commands: Vec<CommandInfo>,
+}
+
+/// Information about a custom command.
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+pub struct CommandInfo {
+    /// Command name (e.g., "create_plan", "research_codebase").
+    pub name: String,
+    /// Human-readable description of what the command does.
+    pub description: String,
+    /// Whether this command requires arguments from the user.
+    pub requires_argument: bool,
+}
+
+/// Request parameters for executing a command.
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[schemars(extend("x-side" = "agent", "x-method" = "session/run_command"))]
+#[serde(rename_all = "camelCase")]
+pub struct RunCommandRequest {
+    /// The session ID to execute the command in.
+    pub session_id: SessionId,
+    /// Name of the command to execute.
+    pub command: String,
+    /// Optional arguments for the command.
+    pub args: Option<String>,
 }
 
 // Method schema
@@ -413,6 +476,10 @@ pub(crate) const SESSION_LOAD_METHOD_NAME: &str = "session/load";
 pub(crate) const SESSION_PROMPT_METHOD_NAME: &str = "session/prompt";
 /// Method name for the cancel notification.
 pub(crate) const SESSION_CANCEL_METHOD_NAME: &str = "session/cancel";
+/// Method name for listing custom commands in a session.
+pub const SESSION_LIST_COMMANDS: &str = "session/list_commands";
+/// Method name for running a custom command in a session.  
+pub const SESSION_RUN_COMMAND: &str = "session/run_command";
 
 /// All possible requests that a client can send to an agent.
 ///
@@ -429,6 +496,8 @@ pub enum ClientRequest {
     NewSessionRequest(NewSessionRequest),
     LoadSessionRequest(LoadSessionRequest),
     PromptRequest(PromptRequest),
+    ListCommandsRequest(ListCommandsRequest),
+    RunCommandRequest(RunCommandRequest),
 }
 
 /// All possible responses that an agent can send to a client.
@@ -446,6 +515,7 @@ pub enum AgentResponse {
     NewSessionResponse(NewSessionResponse),
     LoadSessionResponse,
     PromptResponse(PromptResponse),
+    ListCommandsResponse(ListCommandsResponse),
 }
 
 /// All possible notifications that a client can send to an agent.

rust/agent.rs

@@ -96,6 +96,25 @@ impl acp::Agent for ExampleAgent {
         log::info!("Received cancel request {args:?}");
         Ok(())
     }
+
+    async fn list_commands(
+        &self,
+        arguments: acp::ListCommandsRequest,
+    ) -> Result<acp::ListCommandsResponse, acp::Error> {
+        log::info!("Received list_commands request {arguments:?}");
+        Ok(acp::ListCommandsResponse {
+            commands: vec![acp::CommandInfo {
+                name: "test".to_string(),
+                description: "A test command".to_string(),
+                requires_argument: false,
+            }],
+        })
+    }
+
+    async fn run_command(&self, arguments: acp::RunCommandRequest) -> Result<(), acp::Error> {
+        log::info!("Received run_command request {arguments:?}");
+        Ok(())
+    }
 }
 
 #[tokio::main(flavor = "current_thread")]

rust/example_agent.rs

@@ -634,6 +634,8 @@ impl SideDocs {
             "session/load" => self.agent_methods.get("load_session").unwrap(),
             "session/prompt" => self.agent_methods.get("prompt").unwrap(),
             "session/cancel" => self.agent_methods.get("cancel").unwrap(),
+            "session/list_commands" => self.agent_methods.get("list_commands").unwrap(),
+            "session/run_command" => self.agent_methods.get("run_command").unwrap(),
             _ => panic!("Introduced a method? Add it here :)"),
         }
     }

rust/markdown_generator.rs

@@ -160,6 +160,17 @@ impl Agent for TestAgent {
             .push(args.session_id);
         Ok(())
     }
+
+    async fn list_commands(
+        &self,
+        _arguments: ListCommandsRequest,
+    ) -> Result<ListCommandsResponse, Error> {
+        Ok(ListCommandsResponse { commands: vec![] })
+    }
+
+    async fn run_command(&self, _arguments: RunCommandRequest) -> Result<(), Error> {
+        Ok(())
+    }
 }
 
 // Helper function to create a bidirectional connection