feat: add slash commands for agent switching

[dgageot]

Summary

Adds support for slash commands that switch the active agent. For example, declaring /plan in the agent config makes the planner sub-agent take over the conversation when the user types /plan.

Usage

A new agent: field can be set on a command in agent.yaml:

agents:
  root:
    sub_agents: [planner, reviewer]
    commands:
      plan:
        description: Hand off to the planner
        agent: planner
      review:
        description: Hand off to the reviewer
        agent: reviewer

When the user types /plan, the active agent is switched to planner. Anything typed after the command (e.g. /plan add a logout button) is forwarded to the target agent as the first user message.

agent: can be combined with instruction: to switch and send a fixed prompt; on its own it acts as a pure handoff.

A complete example lives in examples/agent_switching_commands.yaml.

Changes

• pkg/config/types/commands.go — new Agent field on Command; YAML parser accepts the agent key.
• pkg/runtime/commands.go — new LookupCommand helper; ResolveCommand forwards trailing args verbatim for agent-only commands.
• pkg/app/app.go — exposes App.LookupCommand.
• pkg/tui/handlers.go — handleAgentCommand switches the active agent before sending the resolved message.
• pkg/cli/runner.go — PrepareUserMessage does the same for the non-TUI flow.
• agent-schema.json — documents the new agent property.
• examples/agent_switching_commands.yaml — full example with /plan, /review, /back.
• pkg/runtime/commands_test.go — unit tests for the new behavior.

Validation

• task lint clean.
• task test passes for all changed packages.
• task build succeeds.

[docker-agent]

Assessment: 🔴 CRITICAL

[docker-agent]

[HIGH] Agent switched before ResolveCommand — raw /command string sent to target agent

In PrepareUserMessage, rt.SetCurrentAgent(cmd.Agent) is called on line 333 before runtime.ResolveCommand on line 339. Since ResolveCommand delegates to LookupCommand, which calls rt.CurrentAgentInfo(ctx) to look up the command by name, after SetCurrentAgent the lookup runs against the new agent's command table — not the original agent's.

If the target agent (e.g. planner) does not have the /plan command in its own commands: map (the common case — it's usually only defined on the root agent), LookupCommand returns ok=false and ResolveCommand falls back to returning the raw input verbatim, e.g. /plan add a login button, instead of the intended resolved form add a login button. That raw slash-command string is then sent to the target agent as the first user message.

Trigger: Any agent-only slash command (no instruction:) where the target agent doesn't re-declare that command.

Fix: Capture the resolved content before switching agents (mirroring the TUI flow in handleAgentCommand, which correctly calls LookupCommand/ResolveCommand first and switches after):

resolvedContent := runtime.ResolveCommand(ctx, rt, userInput)

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)
    }
}

[docker-agent]

[MEDIUM] Resolved message sent to old agent when handleSwitchAgent fails

When m.application.SwitchAgent(agentName) returns an error, handleSwitchAgent returns early with a notification.ErrorCmd without updating m.sessionState.CurrentAgentName. Back in handleAgentCommand, the if resolved != "" branch on line 645 is then unconditionally reached, and SendMsg{Content: resolved} is appended to cmds and dispatched via tea.Batch.

The result: the user sees the "Failed to switch to agent" notification AND has their message silently dispatched to the original (still-active) agent — not the intended target. This can cause user confusion because the message appears to be accepted even though the intended agent hand-off failed.

Suggested fix: Skip the SendMsg when the agent switch was requested but failed, by tracking whether the switch succeeded:

switchSucceeded := true
if ok && cmd.Agent != "" && cmd.Agent != m.sessionState.CurrentAgentName() {
    prevAgent := m.sessionState.CurrentAgentName()
    switched, switchCmd := m.handleSwitchAgent(cmd.Agent)
    m = switched.(*appModel)
    if switchCmd != nil {
        cmds = append(cmds, switchCmd)
    }
    switchSucceeded = m.sessionState.CurrentAgentName() != prevAgent
}

if resolved != "" && switchSucceeded {
    cmds = append(cmds, core.CmdHandler(messages.SendMsg{Content: resolved}))
}