rubino-agent 0.3.0

data/docs/memory.md

@@ -0,0 +1,98 @@
+# Memory
+
+rubino remembers facts about you and the project across sessions. The default backend is a small SQLite "tiny-Zep" store — Zep/Graphiti-inspired, minus the graph database, the server, and the multi-call pipeline.
+
+## Backends
+
+Memory backends are pluggable (registered like tools). Two ship:
+
+| `memory.backend` | What it is |
+|---|---|
+| `sqlite` (**default**) | tiny-Zep: LLM-extracted atomic facts, bi-temporal supersession, hybrid FTS5/BM25 (+ optional vector) ranked recall, graph-lite 1-hop blend |
+| `default` | the legacy non-ranked store (kept for back-compat) |
+
+Switch backends:
+
+```bash
+rubino memory backend          # show the active backend + available names
+rubino memory backend sqlite   # switch (writes memory.backend to config.yml)
+```
+
+The agent loop, the in-chat `/memory` view, the `/status` panel, the `rubino memory` CLI, and the HTTP `/v1/memory` operations all use the **active** backend (fixed in #94/#106/#83 — these surfaces previously read a hardwired legacy table and never saw the facts the agent actually persists).
+
+## The sqlite tiny-Zep backend
+
+### What's stored
+
+One declarative **fact** per row. Facts carry a `kind` (`user_profile`, `preference`, `fact`, `project`, `env`, …), the source session, a confidence, optional entity tags, and bi-temporal validity columns (`valid_from` / `valid_to`).
+
+- **User profile** (`user_profile` facts) — durable facts about you, metered against `memory.user_char_limit`.
+- **Project context** (`project` / `env` facts) — facts about the codebase/environment.
+- **General facts** — everything else.
+
+### How facts are extracted (write path)
+
+When `memory.auto_extract` is on, auto-extraction runs as a post-turn job (`ExtractMemoryJob` — executed immediately after the turn in the default inline jobs mode): a single auxiliary-LLM call looks at the recent turn and returns `{add, supersede}`:
+
+- **add** — new atomic facts (deduplicated via a Jaccard near-dup check against the live set, no second LLM call).
+- **supersede** — a contradicted fact is **soft-retired** (its `valid_to` is set and `superseded_by` points at the replacement), not deleted — temporal correctness without losing provenance (Graphiti-style edge invalidation collapsed to one call).
+
+When extraction stores facts, the chat prints a deterministic confirmation from the write path (`✓ saved to memory · 2 facts (e6bf776b, a91c03d2)`) — the agent's "I'll remember that" narration alone is not a save signal.
+
+Every write goes through the same injection-defense floor as the legacy store: a `ThreatScanner` (prompt-injection / exfiltration patterns) plus a character budget. A fact that trips a guard is skipped, not allowed to splice tainted/over-budget content into a future system prompt.
+
+Two budgets, deliberately separate:
+
+- `memory.memory_char_limit` (2200) / `memory.user_char_limit` (1375) — the **injection** budget: how much is packed into the prompt at retrieval time.
+- `memory.ingest_char_limit` (null = unbounded) — the **store** budget: storing facts isn't throttled by the injection budget, so long multi-session conversations don't stall once the injection budget fills.
+
+### How facts are recalled (read path)
+
+`retrieve` runs a **hybrid ranked** recall over LIVE facts (`valid_to IS NULL`):
+
+1. **Direct relevance** — FTS5/BM25 over the query (and vector KNN when enabled), fused with Reciprocal Rank Fusion and lightly kind-weighted (durable `user_profile`/`preference`/`env` facts win ties). These are the only content-matching signals, so the fact a keyword probe ranks #1 stays #1.
+2. **Tail supplements** — graph (1-hop entity neighbours of the query) then recency only **backfill** the remaining budget after direct hits. They can never outrank a direct content match (this was the dominant cause of single-shot recall misses).
+
+Results are greedily packed under the retrieval char budget. Common stopwords ("user", "project", "the", …) are excluded from the FTS MATCH so a probe doesn't match every fact on a trivial word.
+
+### Tuning
+
+```yaml
+memory:
+  sqlite:
+    vector: false   # opt-in sqlite-vec / RubyLLM.embed KNN on top of FTS5 (off by default — no extra deps needed)
+    graph: true     # graph-lite 1-hop entity/edge blend (on by default; set false to A/B the graph signal)
+```
+
+Vector mode requires both `vector: true` **and** `RubyLLM.embed` to be wired; otherwise it's FTS5-only.
+
+## The `memory` tool
+
+The agent persists facts autonomously via the `memory` tool (gated by `tools.memory`, on by default):
+
+- `action: add` — record a new fact.
+- `action: replace` — supersede an existing fact (`old_text` selects it).
+- `action: remove` — hard-delete a fact.
+- `target: user` writes the user profile; `target: memory` writes general memory.
+
+The tool stores **one atomic fact per call** — separate facts go in separate calls so each can be superseded or forgotten independently. Every write is confirmed deterministically in chat by the tool-result line, e.g.:
+
+```
+└ ✓ Memory replaced (id=e6bf776b, kind=user_profile).
+```
+
+Content is scanned for injection/exfiltration patterns and subject to the character budget. Because this lets the agent write to its own future context, see [security.md](security.md#autonomous-memory) for the trust model.
+
+## Inspecting and managing memory
+
+```bash
+rubino memory list             # most recent LIVE facts (active backend)
+rubino memory list --all       # include superseded (soft-retired) facts
+rubino memory list --kind user_profile --limit 50
+rubino memory show <id>        # full fact incl. the temporal chain (id prefix accepted)
+rubino memory delete <id>      # hard-delete
+```
+
+`list` and the in-chat `/memory` views show only **live** facts (`valid_to IS NULL`) — superseded facts are retained for provenance but hidden, so a contradicted fact is never presented as current and the header count always matches the rows. Pass `--all` to `rubino memory list` to see the supersession history; `rubino memory show <id>` prints a retired fact's `Retired:` / `Superseded by:` chain.
+
+In-chat, `/memory` inspects, searches (`/memory <query>` or `/memory search <query>`), and forgets what the agent remembers. Both surfaces read the active backend.

data/docs/models-and-keys.md

@@ -0,0 +1,173 @@
+# Models & keys
+
+Which provider, which model, which key — answered in 60 seconds. The fastest path is `rubino setup`, which writes all of the blocks below for you. This page is the manual reference and the per-provider copy-paste.
+
+## The decision
+
+| Provider | When | Default model the wizard writes |
+|---|---|---|
+| **OpenAI** | Recommended default; GPT models | `gpt-4.1` |
+| **MiniMax** | Anthropic-compatible | `MiniMax-M2.7` |
+| **Anthropic** | Claude models | `claude-sonnet-4-5` |
+| **Google (Gemini)** | Gemini models | `gemini-2.5-pro` |
+| **OpenAI-compatible gateway** | A gateway picks the upstream | `auto` |
+| **fake** | Tests/demos only | `fake/happy-path` (needs `RUBINO_ALLOW_FAKE=1`) |
+
+How resolution works: an explicit `model.provider` (anything other than `auto`) wins. When `provider: auto`, the provider is derived from the `model.default` id by ruby_llm's registry. A key for the resolved provider must be available either via `providers.<name>.api_key` in `config.yml` **or** the provider's native ENV var.
+
+## ⚠️ The default→OpenRouter trap (refs #93)
+
+The shipped default is:
+
+```yaml
+model:
+  default: "openai/gpt-4.1"
+  provider: "auto"
+```
+
+In ruby_llm's model registry, the id `openai/gpt-4.1` resolves to **OpenRouter**, not OpenAI's own API. Historically, a brand-new user with no key hit ~80 seconds of silent retries against an endpoint they never chose, then got an empty answer and a success exit — a dead end with no signal.
+
+**This is now fixed.** Before any model call, rubino checks that the resolved provider has a usable credential (`LLM::CredentialCheck`). If not:
+
+- On a TTY → the onboarding wizard runs so you pick a provider + paste a key.
+- Non-interactively (`-q` / piped / no TTY) → it prints a clear, actionable message and exits non-zero (no silent retry storm):
+
+  ```
+  No API key configured for provider 'openai' (model openai/gpt-4.1).
+  Set it up one of these ways:
+    • run `rubino setup` for a guided first-run setup, or
+    • add OPENAI_API_KEY=<your-key> to ~/.rubino/.env, or
+    • set providers.openai.api_key in ~/.rubino/config.yml.
+  ```
+
+The simplest fix is `rubino setup`. To deliberately use OpenAI's own API (not OpenRouter), set a bare `gpt-4.1` with `provider: openai` as shown below.
+
+## Where keys live
+
+- Keys go in `~/.rubino/.env` (mode `0600`) as `KEY=value`, or directly as `providers.<name>.api_key` in `config.yml`.
+- In `config.yml` you can reference an env var with the substitution syntax: `api_key: "${MINIMAX_API_KEY}"` or `"{env:MINIMAX_API_KEY}"`.
+- `RUBINO_HOME` relocates the whole home (config, `.env`, and the database follow it).
+
+The native ENV var per provider: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY` (or `GOOGLE_API_KEY`), `BEDROCK_API_KEY`, `MINIMAX_API_KEY`.
+
+---
+
+## Per-provider setup
+
+Each block goes in `~/.rubino/config.yml`; the key goes in `~/.rubino/.env`.
+
+### MiniMax (Anthropic-compatible)
+
+MiniMax speaks the Anthropic API, so it routes through the anthropic-compatible path.
+
+```yaml
+model:
+  default: "MiniMax-M2.7"
+  provider: "minimax"
+
+providers:
+  minimax:
+    anthropic_compatible: true
+    base_url: "https://api.minimax.io/anthropic"
+    api_key: "${MINIMAX_API_KEY}"
+```
+
+```bash
+# ~/.rubino/.env
+MINIMAX_API_KEY=...
+```
+
+> MiniMax M2 ignores tool definitions and roleplays bash in markdown; use **MiniMax-M2.7** for working tool use.
+
+### OpenAI (GPT) (recommended default)
+
+Uses OpenAI's own API (not OpenRouter) when `provider: openai` and the model id is a bare OpenAI id.
+
+```yaml
+model:
+  default: "gpt-4.1"
+  provider: "openai"
+```
+
+```bash
+# ~/.rubino/.env
+OPENAI_API_KEY=sk-...
+```
+
+For Azure/custom endpoints set `providers.openai.base_url`.
+
+### Anthropic (Claude)
+
+```yaml
+model:
+  default: "claude-sonnet-4-5"
+  provider: "anthropic"
+```
+
+```bash
+# ~/.rubino/.env
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+### Google (Gemini)
+
+The provider id is `google`.
+
+```yaml
+model:
+  default: "gemini-2.5-pro"
+  provider: "google"
+```
+
+```bash
+# ~/.rubino/.env
+GEMINI_API_KEY=...
+# GOOGLE_API_KEY is also accepted
+```
+
+### OpenAI-compatible gateway
+
+Point this at any OpenAI-compatible gateway; the gateway decides which upstream (OpenAI/MiniMax/Anthropic/…) and which model to call. Route everything to it with `provider: gateway` and `model: auto`, and set `base_url` + `api_key` for your gateway.
+
+```yaml
+model:
+  default: "auto"
+  provider: "gateway"
+  supports_vision: null   # set true/false if the gateway hides the upstream model name
+
+providers:
+  gateway:
+    openai_compatible: true
+    assume_model_exists: true
+    base_url: "https://your-gateway/v1"
+    api_key: "${OPENAI_API_KEY}"
+```
+
+`openai_compatible` providers fall back to `OPENAI_API_KEY` when no `providers.<name>.api_key` is set.
+
+### fake (testing only)
+
+```yaml
+model:
+  default: "fake/happy-path"
+```
+
+```bash
+export RUBINO_ALLOW_FAKE=1   # required; chat/server refuse to boot fake otherwise
+```
+
+See the [README](../README.md#fake-llm-provider) for scenario authoring.
+
+---
+
+## Auxiliary models
+
+Compression, approval scoring, vision, and document summarization can each run on a separate (often cheaper) model. By default they reuse the primary (`provider: "main"`). See [configuration.md](configuration.md#auxiliary) — for example, set `auxiliary.vision.model: "auto-vision"` to let an OpenAI-compatible gateway pick a vision model for the `vision` tool.
+
+## Verifying
+
+```bash
+rubino doctor
+```
+
+`doctor` reports the resolved provider for your configured model and whether a usable credential is present — the same check the chat preflight uses.

data/docs/oauth-providers.md

@@ -0,0 +1,145 @@
+# OAuth provider connectors
+
+Built-in OAuth integration lets users connect third-party accounts (Github, Google, etc.) so tools running inside rubino can act on their behalf.
+
+## Design
+
+Four pieces:
+
+1. **`Rubino::OAuth::Provider`** — abstract class. Subclasses describe one provider: authorize URL builder (PKCE S256), token exchange, default scopes, account info fetcher.
+2. **`Rubino::OAuth::Registry`** — Mutex-protected module. `load_from_config!` registers a provider instance per entry in `config.oauth.providers` at boot; lookup by id via `OAuth::Registry.fetch(id)`.
+3. **`Rubino::OAuth::ConnectionRepository`** — Sequel-backed CRUD on `oauth_connections`. Encrypts `access_token`/`refresh_token` on write and decrypts on read. Upsert keyed on `(provider, account_id)`.
+4. **`Rubino::OAuth::TokenEncryptor`** — AES-256-GCM with key from `RUBINO_ENCRYPTION_KEY` (32-byte base64). Wire format: `Base64(IV || ciphertext || tag)`.
+
+Tools resolve tokens via the repository:
+```ruby
+repo = Rubino::OAuth::ConnectionRepository.new
+conn = repo.list.find { |c| c[:provider] == "github" }
+client = Octokit::Client.new(access_token: conn[:access_token])
+```
+
+> **Current scope:** no auto-refresh. Expired tokens are returned as-is; the tool that uses them is responsible for handling 401s (typically by surfacing a re-auth prompt). A future task will add transparent refresh inside the repository's read path.
+
+## Built-in providers
+
+| ID | Class | Default scopes | Required env |
+|---|---|---|---|
+| `github` | `OAuth::Provider::Github` | `repo`, `user:email` | `GITHUB_OAUTH_CLIENT_ID`, `GITHUB_OAUTH_CLIENT_SECRET` |
+| `google` | `OAuth::Provider::Google` | `openid`, `email`, `profile` | `GOOGLE_OAUTH_CLIENT_ID`, `GOOGLE_OAUTH_CLIENT_SECRET` |
+
+Adding a new provider = new file under `lib/rubino/oauth/provider/`, add it to `Rubino::OAuth::Registry::BUILTINS`, declare it in `config.oauth.providers`. `load_from_config!` (called at boot) instantiates and registers every provider whose section in the config carries both `client_id` and `client_secret`. ~50 LOC for a standard OAuth 2.0 provider.
+
+## Flow (PKCE by default)
+
+```
+client                    rubino                provider
+  │                            │                         │
+  │  POST /v1/oauth/.../connect │                         │
+  │ ───────────────────────────►│                         │
+  │                            │  generates state +      │
+  │                            │  PKCE code_verifier     │
+  │  { authorize_url, state,    │                         │
+  │    code_verifier }          │                         │
+  │ ◄───────────────────────────│                         │
+  │                            │                         │
+  │   user redirected to authorize_url                    │
+  │ ─────────────────────────────────────────────────────►│
+  │                            │                         │
+  │   provider redirects to client with code + state      │
+  │ ◄─────────────────────────────────────────────────────│
+  │                            │                         │
+  │  POST /v1/oauth/.../callback│                         │
+  │  { code, state, expected_state,                       │
+  │    code_verifier, redirect_uri }                      │
+  │ ───────────────────────────►│                         │
+  │                            │  POST /token            │
+  │                            │ ───────────────────────►│
+  │                            │ ◄───────────────────────│
+  │  serialized connection      │                         │
+  │  (id, provider, account_id, │                         │
+  │   account_email, scopes,    │                         │
+  │   expires_at, metadata)     │                         │
+  │ ◄───────────────────────────│                         │
+```
+
+The **client** (e.g. a web UI) keeps `state` + `code_verifier` between connect and callback. rubino does not maintain a per-flow session — keeps it stateless.
+
+## Storage
+
+```sql
+CREATE TABLE oauth_connections (
+  id              text PRIMARY KEY,      -- uuid
+  provider        text NOT NULL,
+  account_id      text NOT NULL,         -- provider's user id
+  account_email   text,
+  access_token    text NOT NULL,         -- encrypted, Base64(IV||ct||tag)
+  refresh_token   text,                  -- encrypted, Base64(IV||ct||tag)
+  expires_at      text,                  -- iso8601
+  scopes_json     text NOT NULL,         -- json array
+  metadata_json   text,                  -- json
+  created_at      text NOT NULL,
+  updated_at      text NOT NULL,
+  UNIQUE (provider, account_id)
+);
+```
+
+The repository transparently encodes/decodes `scopes_json`/`metadata_json` so callers see `:scopes` (Array) and `:metadata` (Hash) on read.
+
+Encryption key from `RUBINO_ENCRYPTION_KEY` (32-byte base64). Boot fails if missing in production.
+
+**Tokens are never logged. Ever.** The logger has a redaction filter on `access_token`, `refresh_token`, `client_secret`.
+
+## Configuration
+
+`config/rubino.yml`:
+```yaml
+oauth:
+  providers:
+    github:
+      client_id: ${GITHUB_OAUTH_CLIENT_ID}
+      client_secret: ${GITHUB_OAUTH_CLIENT_SECRET}
+      scopes: [repo, user:email]
+    google:
+      client_id: ${GOOGLE_OAUTH_CLIENT_ID}
+      client_secret: ${GOOGLE_OAUTH_CLIENT_SECRET}
+      scopes:
+        - openid
+        - email
+        - profile
+        - https://www.googleapis.com/auth/calendar.readonly
+```
+
+Providers not declared in config are not registered — `GET /v1/oauth/providers` only lists configured ones.
+
+## Setup guides
+
+### Github
+
+1. Github → Settings → Developer settings → OAuth Apps → New
+2. Authorization callback URL: `<your-client>/oauth/callback`
+3. Copy Client ID + generate Client Secret
+4. Export `GITHUB_OAUTH_CLIENT_ID` / `GITHUB_OAUTH_CLIENT_SECRET`
+
+### Google
+
+1. Google Cloud Console → APIs & Services → Credentials → Create OAuth client ID
+2. Application type: Web. Authorized redirect URIs: `<your-client>/oauth/callback`
+3. Enable required APIs (Calendar, Gmail, Drive, ...) based on scopes you want
+4. Export `GOOGLE_OAUTH_CLIENT_ID` / `GOOGLE_OAUTH_CLIENT_SECRET`
+
+## Why we did this (and not "delegate to client")
+
+Rich did it: it has `/api/providers/oauth/*`. Reason it makes sense in rubino too:
+
+- **Tools need tokens.** A `GithubTool` needs a token to call the API. If OAuth is the client's responsibility, the client has to forward tokens with every run, which is ugly and leaky.
+- **Refresh logic will be centralized.** Once auto-refresh lands, expired tokens get refreshed in one place, not duplicated per client.
+- **Encrypted persistence.** Clients shouldn't store user tokens long-term; the agent does, encrypted, with a redaction-aware logger.
+
+The client (a web UI) handles only the redirect dance — opening the authorize URL in a browser and POSTing the code back. Everything else stays here.
+
+## Non-goals
+
+- **Apple Sign-In:** uses JWT-signed assertions, not standard OAuth. Postponed.
+- **Multi-account per provider:** one connection per provider per instance is supported. Multi-account requires UI for selection — out of scope.
+- **OAuth1.0:** Twitter/X is the only relevant one. Postponed.
+- **OIDC discovery:** providers are explicit classes. No `.well-known/openid-configuration` autodiscovery.

data/docs/plugins.md

@@ -0,0 +1,195 @@
+# Plugin System
+
+rubino defines 38 hook points for extending and customizing behavior.
+
+> **Status:** The plugin registry and DSL (`Rubino.plugin do ... end`) are
+> functional, but the hook points themselves are **not yet fired from the
+> lifecycle** — they are declared in `Plugins::HOOKS` but not all are wired into
+> the runtime yet. This document describes the intended hooks and their context
+> shape (design intent); subscribing to a hook that isn't fired yet is harmless
+> but has no effect.
+
+## Creating a Plugin
+
+Place Ruby files in `.rubino/plugins/` or `~/.rubino/plugins/`:
+
+```ruby
+# .rubino/plugins/logging.rb
+Rubino.plugin do
+  on(:tool_execute_before) do |context|
+    puts "[AUDIT] Tool: #{context[:tool_name]} args: #{context[:arguments]}"
+    context  # Return context (optionally modified)
+  end
+
+  on(:tool_execute_after) do |context|
+    puts "[AUDIT] Result: #{context[:result]&.truncated_preview}"
+    context
+  end
+end
+```
+
+## Hook Behavior
+
+- Hooks receive a context hash and should return it (optionally modified)
+- Multiple handlers per hook are supported (executed in registration order)
+- If a handler returns a Hash, it's merged into the context for the next handler
+- Errors in hooks are caught and logged but don't break the main flow
+
+## All 38 Hooks
+
+### Tool Lifecycle
+
+| Hook | Trigger | Context Keys |
+|------|---------|--------------|
+| `tool_execute_before` | Before any tool runs | `tool_name`, `arguments`, `session_id` |
+| `tool_execute_after` | After tool completes | `tool_name`, `arguments`, `result`, `duration` |
+| `tool_approval_before` | Before approval check | `tool_name`, `risk_level`, `arguments` |
+| `tool_approval_after` | After approval decision | `tool_name`, `decision` (:allow/:ask/:deny) |
+| `tool_result_transform` | Transform tool output | `tool_name`, `result` |
+
+### Shell
+
+| Hook | Trigger | Context Keys |
+|------|---------|--------------|
+| `shell_env` | Inject env vars into shell | `command`, `env` (mutable hash) |
+| `shell_execute_before` | Before shell command | `command`, `cwd` |
+| `shell_execute_after` | After shell command | `command`, `output`, `exit_code` |
+
+### File Operations
+
+| Hook | Trigger | Context Keys |
+|------|---------|--------------|
+| `file_read_before` | Before reading a file | `path` |
+| `file_read_after` | After reading a file | `path`, `content`, `size` |
+| `file_write_before` | Before writing a file | `path`, `content` |
+| `file_write_after` | After writing a file | `path`, `size` |
+
+### Context Compaction
+
+| Hook | Trigger | Context Keys |
+|------|---------|--------------|
+| `compaction_before` | Before compaction starts | `session_id`, `message_count`, `token_estimate` |
+| `compaction_after` | After compaction finishes | `session_id`, `saved_tokens`, `new_session_id` |
+| `compaction_context_inject` | Inject custom context into compaction summary | `session_id`, `messages` |
+
+### Sessions
+
+| Hook | Trigger | Context Keys |
+|------|---------|--------------|
+| `session_start` | New session created | `session_id`, `model`, `source` |
+| `session_end` | Session ended | `session_id`, `message_count` |
+| `session_fork` | Session forked | `source_id`, `forked_id`, `at_message` |
+| `session_persist` | Session state saved | `session_id`, `token_count` |
+
+### Messages
+
+| Hook | Trigger | Context Keys |
+|------|---------|--------------|
+| `message_before` | Before message is processed | `role`, `content`, `session_id` |
+| `message_after` | After message persisted | `message_id`, `role`, `content` |
+| `message_stream_chunk` | Each streaming chunk | `chunk`, `session_id` |
+
+### Memory
+
+| Hook | Trigger | Context Keys |
+|------|---------|--------------|
+| `memory_extract` | During memory extraction | `session_id`, `candidates` |
+| `memory_save_before` | Before saving a memory | `kind`, `content` |
+| `memory_retrieve_after` | After retrieving memories | `memories`, `context` |
+
+### Jobs
+
+| Hook | Trigger | Context Keys |
+|------|---------|--------------|
+| `job_before` | Before job execution | `job_type`, `payload` |
+| `job_after` | After job completes | `job_type`, `result` |
+| `job_failed` | When job fails | `job_type`, `error`, `attempts` |
+
+### Model/LLM
+
+| Hook | Trigger | Context Keys |
+|------|---------|--------------|
+| `model_call_before` | Before LLM API call | `model`, `messages`, `tools` |
+| `model_call_after` | After LLM response | `model`, `response`, `tokens` |
+| `model_response_transform` | Transform LLM response | `content`, `tool_calls` |
+
+### Prompt Assembly
+
+| Hook | Trigger | Context Keys |
+|------|---------|--------------|
+| `prompt_assemble_before` | Before building prompt | `session_id`, `memory_context` |
+| `prompt_assemble_after` | After prompt built | `messages`, `token_estimate` |
+
+### Agent
+
+| Hook | Trigger | Context Keys |
+|------|---------|--------------|
+| `agent_switch` | Agent switched | `from`, `to` |
+| `agent_route` | Input routed to agent | `input`, `agent_name` |
+
+### System
+
+| Hook | Trigger | Context Keys |
+|------|---------|--------------|
+| `config_reload` | Config reloaded | `config` |
+| `startup` | Application starting | `version` |
+| `shutdown` | Application stopping | `reason` |
+
+## Examples
+
+### Auto-format after writes
+
+```ruby
+Rubino.plugin do
+  on(:file_write_after) do |context|
+    path = context[:path]
+    if path.end_with?(".rb")
+      system("rubocop -A '#{path}' 2>/dev/null")
+    elsif path.end_with?(".js", ".ts")
+      system("prettier --write '#{path}' 2>/dev/null")
+    end
+    context
+  end
+end
+```
+
+### Inject environment into shell
+
+```ruby
+Rubino.plugin do
+  on(:shell_env) do |context|
+    context[:env]["RAILS_ENV"] ||= "development"
+    context[:env]["BUNDLE_GEMFILE"] ||= File.join(Dir.pwd, "Gemfile")
+    context
+  end
+end
+```
+
+### Block dangerous operations
+
+```ruby
+Rubino.plugin do
+  on(:tool_execute_before) do |context|
+    if context[:tool_name] == "shell"
+      cmd = context.dig(:arguments, "command") || ""
+      if cmd.match?(/rm\s+-rf\s+\/|dd\s+if=|mkfs|format/)
+        raise Rubino::ToolError, "Blocked dangerous command: #{cmd}"
+      end
+    end
+    context
+  end
+end
+```
+
+### Custom telemetry
+
+```ruby
+Rubino.plugin do
+  on(:model_call_after) do |context|
+    tokens = context[:tokens] || 0
+    model = context[:model]
+    File.open("usage.log", "a") { |f| f.puts "#{Time.now.iso8601} #{model} #{tokens}" }
+    context
+  end
+end
+```