Plugin api

Handlers are async Python callables with this signature:

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

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

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`

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]`	Images rendered after command output where supported.
`markdown_styles`	`tuple[MarkdownTextStyle, ...]`	Presentation-only Rich styles for literal visible Markdown text; ignored by portable clients.

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.
`user_turn_usage`	`tuple[UserTurnUsage, ...]`	Immutable live-session usage snapshots grouped by top-level user turn.

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.usage`	`property`	Canonical usage accumulator for the active agent, 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 capabilities are optional because not every surface can support live changes.

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.