# `Vibe.Plugin`
[🔗](https://github.com/elixir-vibe/vibe/blob/v0.2.3/lib/vibe/plugin.ex#L1)

Behaviour for Vibe plugins.

Plugins are BEAM modules, not model-facing tools by default. They can observe
lifecycle events, expose supervised children, register slash commands, provide
eval APIs, add model-facing actions, and update renderer-neutral UI state.

Use plugin APIs when a capability should be composable from `Vibe.Eval`; expose
model-facing actions only when the model needs direct tool access.

# `context`

```elixir
@type context() :: map()
```

# `event`

```elixir
@type event() :: %{:type => atom(), optional(atom()) => term()}
```

# `result`

```elixir
@type result() :: :ok | {:ok, map()} | {:error, term()} | {:halt, term()}
```

# `actions`
*optional* 

```elixir
@callback actions(term()) :: [module()]
```

# `apis`
*optional* 

```elixir
@callback apis(term()) :: [Vibe.Plugin.API.t() | keyword() | map()]
```

# `before_command`
*optional* 

```elixir
@callback before_command(String.t(), context(), term()) ::
  {:ok, term()} | {:warn, String.t(), term()} | {:block, String.t(), term()}
```

# `children`
*optional* 

```elixir
@callback children(term()) :: [Supervisor.child_spec() | {module(), term()} | module()]
```

# `children`
*optional* 

```elixir
@callback children(term(), map()) :: [
  Supervisor.child_spec() | {module(), term()} | module()
]
```

# `commands`
*optional* 

```elixir
@callback commands(term()) :: [module() | map()]
```

# `context`
*optional* 

```elixir
@callback context(list(), context(), term()) :: {:ok, term()} | {:ok, list(), term()}
```

# `handle_event`

```elixir
@callback handle_event(event(), context(), term()) :: {result(), term()}
```

# `init`

```elixir
@callback init(keyword()) :: {:ok, term()} | {:error, term()}
```

# `presentation_document`
*optional* 

```elixir
@callback presentation_document(term()) ::
  Vibe.Presentation.Document.t() | keyword() | map()
```

# `shutdown`
*optional* 

```elixir
@callback shutdown(term()) :: :ok
```

# `system_prompt`
*optional* 

```elixir
@callback system_prompt(context(), term()) :: {String.t() | nil, term()}
```

# `tool_call`
*optional* 

```elixir
@callback tool_call(map(), context(), term()) ::
  {:ok, term()} | {:ok, map(), term()} | {:block, String.t(), term()}
```

# `tool_result`
*optional* 

```elixir
@callback tool_result(map(), context(), term()) :: {:ok, term()} | {:ok, map(), term()}
```

# `api`
*macro* 

---

*Consult [api-reference.md](api-reference.md) for complete listing*