feat: add slash commands for agent switching

Add support for commands that switch the active agent via a new 'agent:' field
in the commands section of agent.yaml. Users can now use /plan to switch to a
planner sub-agent, /review to switch to a reviewer, etc. Trailing arguments
after the command are forwarded to the target agent as the first prompt.

Author: dgageot

agent-schema.json

@@ -595,7 +595,7 @@
     },
     "CommandConfig": {
       "type": "object",
-      "description": "Advanced command configuration with description and instruction",
+      "description": "Advanced command configuration. Set 'instruction' to send a prompt to the current agent. Set 'agent' to switch the active agent to a sub-agent (e.g. /plan -> the 'planner' sub-agent). Both fields can be combined: the agent is switched first, then the instruction is sent to the new agent.",
       "properties": {
         "description": {
           "type": "string",
@@ -604,6 +604,10 @@
         "instruction": {
           "type": "string",
           "description": "The prompt sent to the agent. Supports bang commands (!`command`) and positional arguments ($1, $2, etc.)"
+        },
+        "agent": {
+          "type": "string",
+          "description": "Name of a sub-agent to switch to when this command is invoked. The agent must be reachable from the current agent's sub-agent graph. When set without 'instruction', any text typed after the slash command is forwarded as a prompt to the target agent."
         }
       },
       "additionalProperties": false

examples/agent_switching_commands.yaml

@@ -0,0 +1,63 @@
+#!/usr/bin/env docker agent run
+
+# This example demonstrates slash commands that switch the active agent.
+# Type "/plan" in the TUI to hand the conversation off to the planner sub-agent,
+# "/review" to switch to the reviewer, and "/back" to return to the root agent.
+#
+# Anything typed after the slash command (e.g. "/plan add a logout button") is
+# forwarded as the first user prompt to the target agent.
+
+models:
+  claude:
+    provider: anthropic
+    model: claude-sonnet-4-5
+
+agents:
+  root:
+    model: claude
+    description: The default agent. Implements the work once a plan exists.
+    instruction: |
+      You are the implementation agent. You write and edit code.
+      If the user asks for a plan or design discussion, use the /plan command
+      to switch to the planner sub-agent.
+    sub_agents:
+      - planner
+      - reviewer
+    toolsets:
+      - type: filesystem
+      - type: shell
+    commands:
+      plan:
+        description: "Hand off to the planner sub-agent"
+        agent: planner
+      review:
+        description: "Hand off to the reviewer sub-agent"
+        agent: reviewer
+
+  planner:
+    model: claude
+    description: Plans the work before implementation.
+    instruction: |
+      You are the planning agent. Ask clarifying questions, then produce a
+      step-by-step plan in markdown. Do not write code.
+    sub_agents:
+      - root
+    commands:
+      back:
+        description: "Return to the root agent"
+        agent: root
+
+  reviewer:
+    model: claude
+    description: Reviews local changes for quality and security.
+    instruction: |
+      You review the local Git changes and provide concise, actionable feedback
+      on code quality, security, and maintainability.
+    sub_agents:
+      - root
+    toolsets:
+      - type: shell
+    commands:
+      back:
+        description: "Return to the root agent"
+        agent: root

pkg/app/app.go

@@ -301,6 +301,15 @@ func (a *App) ResolveCommand(ctx context.Context, userInput string) string {
 	return runtime.ResolveCommand(ctx, a.runtime, userInput)
 }
 
+// LookupCommand parses userInput as a /command invocation and returns the
+// matching command, the trailing arguments, and whether a match was found.
+// Callers that want to act on command metadata (for example switching to a
+// sub-agent declared via the `agent:` field) should call this before
+// ResolveCommand to inspect the raw command.
+func (a *App) LookupCommand(ctx context.Context, userInput string) (types.Command, string, bool) {
+	return runtime.LookupCommand(ctx, a.runtime, userInput)
+}
+
 // EmitStartupInfo emits initial agent, team, and toolset information to the provided channel
 func (a *App) EmitStartupInfo(ctx context.Context, events chan runtime.Event) {
 	a.runtime.EmitStartupInfo(ctx, a.session, runtime.NewChannelSink(events))

pkg/cli/runner.go

@@ -326,6 +326,15 @@ func Run(ctx context.Context, out *Printer, cfg Config, rt runtime.Runtime, sess
 // attachment was used). Callers should pass that path to
 // session.Session.AddAttachedFile so sub-agents inherit the file context.
 func PrepareUserMessage(ctx context.Context, rt runtime.Runtime, userInput, globalAttachPath string) (*session.Message, string) {
+	// Switch the active agent first if the /command targets a sub-agent.
+	// This must happen before the message is added to the session so the
+	// next runtime turn runs on the right agent.
+	if cmd, _, ok := runtime.LookupCommand(ctx, rt, userInput); ok && cmd.Agent != "" {
+		if err := rt.SetCurrentAgent(cmd.Agent); err != nil {
+			slog.WarnContext(ctx, "Failed to switch agent for /command", "agent", cmd.Agent, "error", err)
+		}
+	}
+
 	// Resolve any /command to its prompt text
 	resolvedContent := runtime.ResolveCommand(ctx, rt, userInput)
 

pkg/config/types/commands.go

@@ -19,6 +19,12 @@ import (
 //	  instruction: |
 //	    Fix the lint issues reported by: !`golangci-lint run`
 //	    Focus on files: $1
+//
+// Agent-switching format (object value):
+//
+//	plan:
+//	  description: "Hand off to the planner sub-agent"
+//	  agent: planner
 type Command struct {
 	// Description is shown in completion dialogs and help text.
 	// For simple format commands, this is empty and the instruction is used for display.
@@ -29,15 +35,30 @@ type Command struct {
 	// - Bang commands: !`command` (executed and output inserted)
 	// - Positional arguments: $1, $2, etc.
 	Instruction string `json:"instruction,omitempty"`
+
+	// Agent, when set, makes the command switch the active agent to the named
+	// sub-agent before any (optional) instruction is sent. This lets users
+	// hand off to a different agent with a single slash command, e.g. /plan
+	// to switch to the "planner" sub-agent.
+	Agent string `json:"agent,omitempty"`
 }
 
 // DisplayText returns the text to show in completion dialogs.
-// Returns Description if available, otherwise truncates the Instruction.
+// It returns Description when available, otherwise the Instruction. For
+// agent-only commands (no instruction or description), it falls back to a
+// short "switch to <agent>" hint so the completion dialog still has
+// something meaningful to show.
 func (c Command) DisplayText() string {
 	if c.Description != "" {
 		return c.Description
 	}
-	return c.Instruction
+	if c.Instruction != "" {
+		return c.Instruction
+	}
+	if c.Agent != "" {
+		return "Switch to " + c.Agent
+	}
+	return ""
 }
 
 // Commands represents a set of named prompts for quick-starting conversations.
@@ -113,23 +134,24 @@ func (c *Commands) UnmarshalYAML(unmarshal func(any) error) error {
 
 // parseCommandValue parses a command value which can be either:
 // - a simple string (becomes the instruction)
-// - a map with description/instruction fields.
+// - a map with description/instruction/agent fields.
 func parseCommandValue(v any) (Command, error) {
 	switch val := v.(type) {
 	case string:
 		return Command{Instruction: val}, nil
 	case map[string]any:
 		desc, _ := val["description"].(string)
 		inst, _ := val["instruction"].(string)
+		agent, _ := val["agent"].(string)
 
-		if inst == "" && desc == "" {
-			return Command{}, errors.New("command must have at least 'instruction' or 'description'")
+		if inst == "" && desc == "" && agent == "" {
+			return Command{}, errors.New("command must have at least 'instruction', 'description' or 'agent'")
 		}
-		if inst == "" {
+		if inst == "" && agent == "" {
 			inst = desc
 		}
 
-		return Command{Description: desc, Instruction: inst}, nil
+		return Command{Description: desc, Instruction: inst, Agent: agent}, nil
 	default:
 		return Command{}, fmt.Errorf("invalid command value type: %T", v)
 	}

pkg/runtime/commands.go

@@ -10,6 +10,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/docker/docker-agent/pkg/config/types"
 	"github.com/docker/docker-agent/pkg/js"
 	"github.com/docker/docker-agent/pkg/tools"
 )
@@ -18,6 +19,27 @@ import (
 // This includes ${args}, ${args[N]}, ${args.join(...)}, ${args.length}, etc.
 var argsPlaceholderRegex = regexp.MustCompile(`\$\{args[^}]*\}`)
 
+// LookupCommand parses userInput as a /command invocation and returns the
+// matching command along with its trailing arguments. The boolean is false
+// when userInput doesn't start with '/' or doesn't match a configured
+// command. Callers that need both the resolved instruction and the original
+// command metadata (e.g. its target agent) typically call LookupCommand to
+// inspect the command before calling ResolveCommand.
+func LookupCommand(ctx context.Context, rt Runtime, userInput string) (cmd types.Command, rest string, ok bool) {
+	if !strings.HasPrefix(userInput, "/") {
+		return types.Command{}, "", false
+	}
+
+	head, tail, _ := strings.Cut(userInput, " ")
+	commandName := head[1:]
+
+	command, found := rt.CurrentAgentInfo(ctx).Commands[commandName]
+	if !found {
+		return types.Command{}, "", false
+	}
+	return command, tail, true
+}
+
 // ResolveCommand transforms a /command into its expanded instruction text.
 // It processes:
 // 1. Command lookup from agent commands
@@ -26,20 +48,26 @@ var argsPlaceholderRegex = regexp.MustCompile(`\$\{args[^}]*\}`)
 //   - ${args[0]}, ${args[1]}, etc. for positional arguments
 //   - ${args} or ${args.join(" ")} for all arguments
 //   - ${tool({...})} for tool calls
+//
+// For agent-switching commands (those declaring `agent: <name>` and no
+// instruction), ResolveCommand returns the trailing arguments verbatim so the
+// caller can forward them to the target sub-agent after switching. When the
+// command has no instruction and no arguments, the result is the empty
+// string, signalling "no message to send".
 func ResolveCommand(ctx context.Context, rt Runtime, userInput string) string {
-	if !strings.HasPrefix(userInput, "/") {
+	command, rest, ok := LookupCommand(ctx, rt, userInput)
+	if !ok {
 		return userInput
 	}
 
-	cmd, rest, _ := strings.Cut(userInput, " ")
-	commandName := cmd[1:] // Remove leading "/"
+	instruction := command.Instruction
 
-	command, found := rt.CurrentAgentInfo(ctx).Commands[commandName]
-	if !found {
-		return userInput
+	// Agent-only commands (no instruction): forward the trailing args verbatim
+	// so the target sub-agent receives the user's original prompt.
+	if instruction == "" {
+		return rest
 	}
 
-	instruction := command.Instruction
 	args := tokenize(rest)
 
 	// Execute JavaScript expressions (${...} syntax) with args array

pkg/runtime/commands_test.go

@@ -623,3 +623,64 @@ func TestResolveCommand_ArgsSlice(t *testing.T) {
 	result := ResolveCommand(t.Context(), rt, "/test first second third")
 	assert.Equal(t, "Rest: second third", result)
 }
+
+func TestLookupCommand_AgentTarget(t *testing.T) {
+	t.Parallel()
+
+	rt := &mockRuntime{
+		commands: types.Commands{
+			"plan": types.Command{
+				Description: "Hand off to the planner",
+				Agent:       "planner",
+			},
+		},
+	}
+
+	cmd, rest, ok := LookupCommand(t.Context(), rt, "/plan add a logout button")
+	assert.True(t, ok)
+	assert.Equal(t, "planner", cmd.Agent)
+	assert.Empty(t, cmd.Instruction)
+	assert.Equal(t, "add a logout button", rest)
+}
+
+func TestLookupCommand_NotACommand(t *testing.T) {
+	t.Parallel()
+
+	rt := &mockRuntime{commands: types.Commands{}}
+
+	_, _, ok := LookupCommand(t.Context(), rt, "hello there")
+	assert.False(t, ok)
+}
+
+func TestResolveCommand_AgentOnlyForwardsArgs(t *testing.T) {
+	t.Parallel()
+
+	rt := &mockRuntime{
+		commands: types.Commands{
+			"plan": types.Command{Agent: "planner"},
+		},
+	}
+
+	// With trailing args: forward verbatim to the target agent.
+	assert.Equal(t, "design a login flow", ResolveCommand(t.Context(), rt, "/plan design a login flow"))
+	// Without trailing args: empty so no message is sent after the switch.
+	assert.Empty(t, ResolveCommand(t.Context(), rt, "/plan"))
+}
+
+func TestResolveCommand_AgentWithInstruction(t *testing.T) {
+	t.Parallel()
+
+	rt := &mockRuntime{
+		commands: types.Commands{
+			"plan": types.Command{
+				Instruction: "Plan the work for: ${args.join(\" \")}",
+				Agent:       "planner",
+			},
+		},
+	}
+
+	// When both instruction and agent are set, the instruction wins (the
+	// caller is responsible for switching the agent before sending it).
+	result := ResolveCommand(t.Context(), rt, "/plan add login")
+	assert.Equal(t, "Plan the work for: add login", result)
+}

pkg/tui/handlers.go

@@ -624,8 +624,29 @@ func (m *appModel) handleOpenURL(url string) (tea.Model, tea.Cmd) {
 }
 
 func (m *appModel) handleAgentCommand(command string) (tea.Model, tea.Cmd) {
-	resolvedCommand := m.application.ResolveCommand(context.Background(), command)
-	return m, core.CmdHandler(messages.SendMsg{Content: resolvedCommand})
+	ctx := context.Background()
+
+	// Inspect the command before resolving so we can detect /commands that
+	// switch to a sub-agent. For those, we switch first and only then send
+	// the resolved message — otherwise the message would be processed by
+	// the previous agent.
+	cmd, _, ok := m.application.LookupCommand(ctx, command)
+	resolved := m.application.ResolveCommand(ctx, command)
+
+	var cmds []tea.Cmd
+	if ok && cmd.Agent != "" && cmd.Agent != m.sessionState.CurrentAgentName() {
+		switched, switchCmd := m.handleSwitchAgent(cmd.Agent)
+		m = switched.(*appModel)
+		if switchCmd != nil {
+			cmds = append(cmds, switchCmd)
+		}
+	}
+
+	if resolved != "" {
+		cmds = append(cmds, core.CmdHandler(messages.SendMsg{Content: resolved}))
+	}
+
+	return m, tea.Batch(cmds...)
 }
 
 func (m *appModel) handleAttachFile(filePath string) (tea.Model, tea.Cmd) {