<!--
  Generated by docs/generate_plugin_api_docs.py.
  Do not edit this file directly.
-->

Handlers are async Python callables with this signature:

```python
async def handler(
    ctx: PluginCommandActionContext,
) -> PluginCommandActionResult | str | None:
    ...
```

Returning a plain string is shorthand for `PluginCommandActionResult(message=...)`.
Return `None` for no visible output.

### Manifest Command Fields

| Field | Type | Description |
|-------|------|-------------|
| `name` | `str` | Slash command name without the leading `/`. |
| `description` | `str` | Human-readable help text for listings and `/plugins` output. |
| `handler` | `str` | Python handler reference, for example `./commands.py:run`. |
| `input_hint` | `str | None` | Optional placeholder shown by surfaces that support command input hints. |
| `key` | `str | None` | Optional key binding metadata. |
| `completer` | `str | None` |  |

### Result Fields

| Field | Type | Description |
|-------|------|-------------|
| `message` | `str | None` | Plain text shown in the command output. |
| `markdown` | `str | None` | Markdown output rendered by the UI. |
| `buffer_prefill` | `str | None` | Draft text inserted into the user's input buffer. |
| `switch_agent` | `str | None` | Switch the active TUI agent after the command. |
| `refresh_agents` | `bool` | Refresh agent/card state after the command. |
| `images` | `list[PluginCommandActionImage]` |  |

### Context Fields

| Field | Type | Description |
|-------|------|-------------|
| `command_name` | `str` | Slash command name being executed. |
| `arguments` | `str` | Raw text after the slash command. |
| `agent` | `PluginCommandAgentProtocol` | Active agent surface exposed to the command. |
| `settings` | `Settings | None` | Resolved fast-agent settings, when available. |
| `session_cwd` | `Path | None` | Working directory for the interactive session, when available. |
| `runtime` | `PluginRuntime | None` | Optional live-runtime capabilities. |
| `is_tui` | `bool` | True when the command is running in the TUI surface. |
| `is_acp` | `bool` | True when the command is running in the ACP surface. |

### Context Helpers

| API | Signature | Description |
|-----|-----------|-------------|
| `ctx.agent_name` | `property` | Active agent name. |
| `ctx.context` | `property` | Current agent context, when available. |
| `ctx.message_history` | `property` | Current agent message history. |
| `ctx.agent_registry` | `property` | Registered agents, when available. |
| `ctx.load_message_history` | `(messages: list[PromptMessageExtended] | None) -> None` | Replace the active agent's message history. |
| `ctx.get_agent` | `(name: str) -> AgentProtocol | None` | Look up another registered agent. |
| `ctx.mark_user_adjusted` | `(message: PromptMessageExtended, *, note: str | None = None) -> None` | Mark a message as user-adjusted in the audit channel. |

### Runtime API

Runtime capabilities are optional because not every surface can support live changes.

```python
if ctx.runtime is not None:
    attached = await ctx.runtime.list_attached_mcp_servers()
```

| API | Signature | Description |
|-----|-----------|-------------|
| `attach_mcp_server` | `(*, server_name: str, agent_name: str | None = None, server_config: MCPServerSettings | None = None, options: MCPAttachOptions | None = None) -> MCPAttachResult` | Attach an MCP server to a running MCP-capable agent and refresh instructions. |
| `detach_mcp_server` | `(*, server_name: str, agent_name: str | None = None) -> MCPDetachResult` | Detach an MCP server from a running MCP-capable agent and refresh instructions. |
| `list_attached_mcp_servers` | `(*, agent_name: str | None = None) -> tuple[str, ...]` | List MCP servers attached to a running MCP-capable agent. |
| `list_configured_detached_mcp_servers` | `(*, agent_name: str | None = None) -> tuple[str, ...]` | List configured MCP servers that are not currently attached. |
