npm - opencode-raven - Versions diffs - 2.0.0 → 2.1.0 - Mend

opencode-raven 2.0.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -4,35 +4,29 @@
 <tr>
 <td><img src="Raven.png" alt="Raven" width="768" /></td>
 <td>
-<strong>Hard tool/MCP rerouter for <a href="https://opencode.ai">opencode</a></strong><br/>
-Blocks configured tools and MCPs for non-Raven agents, then routes those requests through a focused Raven agent to reduce context flooding.
+<strong>Context firewall for <a href="https://opencode.ai">OpenCode</a></strong><br/>
+Raven routes noisy search, docs, web, GitHub, and MCP calls through a free focused agent before they hit your main model, saving cost and context.
 </td>
 </tr>
 </table>
-## Why?
+## What Raven Does
-Tool-heavy work floods context. Search, docs, web, GitHub examples, and verbose MCP calls can dump raw results into your expensive main model. Raven is a hard blocker-rerouter: configured tools fail closed for non-Raven agents and must be delegated through `raven_seek`, where a focused Raven agent performs the work and returns a compact answer.
-Raven fixes three problems:
-1. **Context flooding** — Keep noisy tool results out of the main session. Raven summarizes tool/MCP output before returning it.
-2. **Cost** — Use a cheaper model like `opencode/deepseek-v4-flash-free` for tool-heavy work while saving your main model's context for decisions and edits.
-3. **Enforcement** — This is not soft nudging. Raven blocks configured tools/MCP prefixes for non-Raven agents and gives them the exact `raven_seek` retry path.
-Raven defaults to search/fetch/docs/GitHub routing, but it works with any MCP whose opencode tool names share a prefix.
-Important limitation: opencode still loads enabled MCP tool schemas into the main session. Raven saves context from tool calls and raw results, but it cannot hide initial MCP schemas from the main model until opencode supports agent-scoped MCP visibility.
+Tool-heavy work floods context. Search, docs, web, GitHub examples, and verbose MCP calls can dump raw results into your expensive main model. Raven is a hard blocker-rerouter: configured tools fail closed for non-Raven agents and must be delegated through `raven_seek`, where a focused Raven agent performs the work and returns a compact answer.
-## Install
+Raven fixes three problems:
-```bash
-bun add opencode-raven
-# or
-npm install opencode-raven
-```
+1. **Context flooding** - Keep noisy tool results out of the main session. Raven summarizes tool/MCP output before returning it.
+2. **Cost** - Use a cheaper model like `opencode/deepseek-v4-flash-free` for tool-heavy work while saving your main model's context for decisions and edits.
+3. **Enforcement** - This is not soft nudging. Raven blocks configured tools/MCP prefixes for non-Raven agents and gives them the exact `raven_seek` retry path.
+Raven defaults to routing noisy search/fetch tools and bundles Context7, Exa, and Grep.app as on-demand MCPs that are always handled behind Raven.
+Important limitation: MCPs enabled directly in OpenCode config still load their tool schemas into the main session. Raven saves context from tool calls and raw results for those global MCPs, but schema hiding requires putting the MCP in Raven's `onDemandMcpServers`. **Strongly recommended:** configure noisy/search/docs/web MCPs as on-demand MCPs unless you need direct main-agent access.
+## Install
-Then add to your `opencode.jsonc`:
+Add Raven to your `opencode.jsonc` plugins:
 ```jsonc
 {
@@ -40,207 +34,205 @@ Then add to your `opencode.jsonc`:
 }
 ```
-Restart opencode.
+Restart opencode. It will resolve Raven from npm and cache the plugin automatically.
+Raven checks for package updates and notifies you when a newer version is available. Run `/raven update`, then restart opencode.
+## Quick Use
+Run `/raven` to see status, routed tools, on-demand MCP health, and saved context.
+When a configured tool or MCP is blocked, agents use `raven_seek` to delegate the same request through Raven:
+```txt
+raven_seek(query: "how to use useEffect cleanup")
+raven_seek(query: "Fetch/read https://example.com and summarize install steps")
+raven_seek(query: "Check whether archivemount/libarchive supports ISO or UDF. Use docs, web, or command output as needed.")
+```
+You can call Raven directly with `@Raven` in any OpenCode chat. The Raven agent runs with full filesystem and MCP access, without permission prompts.
+The main agent does not see Raven's internal tool calls or raw tool output, just the final findings. Raven parallelizes independent tool calls internally within a single session.
 ## Commands
 | Command | Action |
 |---------|--------|
-| `/raven` | Show status — enabled/disabled, version, update availability, model, routing, reasoning effort, timeout (no args) |
-| `/raven on` | Enable hard tool/MCP routing (default) |
-| `/raven off` | Disable routing — all agents can use routed tools directly |
-| `/raven route` | Show routed tools and MCP server prefixes |
-| `/raven route tool add <name>` | Route a specific tool through Raven |
-| `/raven route tool remove <name>` | Stop routing a specific tool |
-| `/raven route mcp add <server>` | Route every tool whose name starts with `<server>_` through Raven |
-| `/raven route mcp remove <server>` | Stop routing an MCP server prefix |
-| `/raven update` | Check npm for a newer Raven, clear opencode's plugin cache if needed, then restart opencode |
+| `/raven` | Show status, version, model, routing, on-demand MCP health, stats, reasoning effort, and timeout |
+| `/raven help` | Show all Raven commands |
+| `/raven on` | Enable hard tool/MCP routing |
+| `/raven off` | Disable routing so all agents can use routed tools directly |
+| `/raven route` | Show routed tools, auto-routed global MCP prefixes, and routed tool keywords |
+| `/raven route tool add <name>` | Route a specific tool through Raven |
+| `/raven route tool remove <name>` | Stop routing a specific tool |
+| `/raven route keyword add <keyword>` | Route any tool whose name contains `<keyword>` |
+| `/raven route keyword remove <keyword>` | Stop routing a tool-name keyword |
+| `/raven mcp` | Show on-demand MCP status and generated metadata state |
+| `/raven mcp refresh [server]` | Recheck on-demand MCP health and regenerate tool descriptions/schema estimates |
+| `/raven mcp detail full\|minimized` | Choose full tool descriptions or minimized capability summaries in guidance |
+| `/raven update` | Check npm for a newer Raven, clear OpenCode's plugin cache if needed, then restart opencode |
 | `/raven model <name>` | Change Raven's model (requires restart) |
 | `/raven effort <value>` | Change Raven's reasoning effort (requires restart) |
-| `/raven timeout <seconds>` | Change raven_seek timeout (min 10s, takes effect immediately) |
-| `/raven stats` | Show context saved (session + all-time, bytes + tokens) |
+| `/raven timeout <seconds>` | Change `raven_seek` timeout, minimum 10 seconds |
+| `/raven stats` | Show estimated context saved, including avoided MCP schema load, session, and all-time totals |
-Config persists across restarts in `~/.config/opencode/raven-config.json` (global, shared across all projects). Auto-created on first run.
+Config persists across restarts in `~/.config/opencode/opencode-raven/raven-config.json`. It is global and shared across all projects.
-## Updates
+## Example
-opencode caches npm plugins, so `"opencode-raven"` / `"opencode-raven@latest"` may not automatically refresh after a new npm release.
+<p align="center">
+  <img src="example.gif" alt="Raven example: searching today's top 30 AI news items while saving 71K context" />
+</p>
-Raven checks npm after the TUI starts. If an update is available, it shows a notification. `/raven` also shows the current version and update availability. To update:
+In this example, the main model asks for the top 30 AI news items from today. Raven handles the noisy search/web work in a focused agent and returns the compact result, saving about 71K context that would otherwise have landed in the main session.
-```txt
-/raven update
-```
-This checks npm, clears Raven's opencode plugin cache when a newer version exists, and tells you to restart opencode.
+## Recommended MCP Setup
-Manual alternatives:
+Raven's bundled Context7, Exa, and Grep.app MCPs are on-demand by default. They live in `onDemandMcpServers`, so Raven connects to them internally through `raven_mcp` instead of registering their full tool schemas in OpenCode's global MCP config.
-```bash
-bun update --latest opencode-raven
-# or
-npm install opencode-raven@latest
-```
+On-demand MCPs are always behind Raven and do not need routing entries.
-If opencode still loads the old cached plugin, clear the opencode plugin cache and restart:
+Raven checks configured on-demand MCPs after startup. `/raven` and `/raven mcp` show loaded, failed, and pending MCPs. Loaded MCPs count toward avoided schema-load stats, while failed or pending MCPs do not. Raven shows a warning toast after startup or manual refresh if any configured on-demand MCP fails to load.
-```powershell
-Remove-Item -Recurse -Force "$HOME\.cache\opencode\packages\opencode-raven*"
-```
+Raven also warns if the same MCP server name is configured both globally in OpenCode and in Raven's `onDemandMcpServers`. Prefer one location: on-demand for schema hiding, or global only when direct main-agent access is required.
-```bash
-rm -rf ~/.cache/opencode/packages/opencode-raven*
-```
+All three bundled MCPs work without API keys. Add keys for higher rate limits:
-## Direct access
+| MCP | URL | API key |
+|-----|-----|---------|
+| Context7 | `https://mcp.context7.com/mcp` | Free key at [context7.com/dashboard](https://context7.com/dashboard) for higher limits |
+| Exa AI | `https://mcp.exa.ai/mcp` | Free key at [exa.ai](https://exa.ai) for higher limits |
+| Grep.app | `https://mcp.grep.app` | Public API, no key needed |
-You can call Raven directly with `@Raven` in any opencode chat. The Raven agent runs with full filesystem and MCP access — no permission prompts.
+To add an API key to an on-demand MCP, edit Raven config:
-## raven_seek
+```jsonc
+{
+  "onDemandMcpServers": {
+    "exa": {
+      "type": "remote",
+      "url": "https://mcp.exa.ai/mcp",
+      "headers": { "x-api-key": "{env:EXA_API_KEY}" },
+      "description": "Live web search and webpage fetching."
+    }
+  }
+}
+```
-When configured tools/MCPs are blocked, agents use **`raven_seek`** — a unified delegation tool that sends the request to Raven. It handles routed MCP requests, local codebase search, filesystem discovery, specific URL/page reads, web/docs research, GitHub examples, and command-output/system inspection. Output includes elapsed time and tokens processed.
+To add a local stdio MCP:
-```
-raven_seek(query: "how to use useEffect cleanup")
-raven_seek(query: "Fetch/read https://example.com and summarize install steps")
-raven_seek(query: "Check whether archivemount/libarchive supports ISO or UDF. Use docs, web, or command output as needed.")
+```jsonc
+{
+  "onDemandMcpServers": {
+    "localServer": {
+      "type": "stdio",
+      "command": "bunx",
+      "args": ["some-mcp-server"],
+      "env": { "API_KEY": "{env:API_KEY}" },
+      "cwd": "/optional/path",
+      "description": "Local MCP server."
+    }
+  }
+}
 ```
-The main agent doesn't see Raven's internal tool calls or raw tool output — just the final findings. Raven parallelizes independent tool calls internally within a single session.
+`description` is user-authored and never overwritten. Raven fills missing generated metadata after startup or when you run `/raven mcp refresh [server]`, storing tool summaries, MCP health, and avoided schema-load estimates separately in `~/.config/opencode/opencode-raven/autogenerated-on-demand-mcp-metadata.json`.
+Raven also writes generated main-model guidance to `~/.config/opencode/opencode-raven/autogenerated-on-demand-guidance.md` and injects that file into OpenCode instructions at startup.
 ## Configuration
-### raven-config.json
+Raven config lives at `~/.config/opencode/opencode-raven/raven-config.json`. It is auto-created on first run and auto-migrated on startup when new config fields are added. Old root files such as `~/.config/opencode/raven-config.json` are moved into the `opencode-raven` folder automatically.
-Located at `~/.config/opencode/raven-config.json`. Auto-created on first run and auto-migrated on startup when new config fields are added. Default route lists are only applied when the field is missing, so removed tools/MCP prefixes stay removed. Edit manually or use `/raven` commands:
+Edit config manually or use `/raven` commands:
 ```json
 {
-  "enabled": true,
-  "model": "opencode/deepseek-v4-flash-free",
-  "reasoning_effort": "low",
-  "ravenInstructions": "",
-  "routeTools": ["grep", "glob", "webfetch", "fetch", "bash"],
-  "routeMcpServers": ["context7", "exa", "grep_app"],
-  "allowBundledMCPServers": true,
-  "excludeAgents": [],
-  "excludeTools": [],
-  "timeout": 180
+  "enabled": true,
+  "model": "opencode/deepseek-v4-flash-free",
+  "reasoning_effort": "low",
+  "ravenInstructions": "",
+  "routeTools": ["grep", "glob", "webfetch", "fetch", "websearch", "bash"],
+  "routeToolKeywords": [],
+  "onDemandMcpDescriptionDetail": "full",
+  "onDemandMcpServers": {
+    "context7": {
+      "type": "remote",
+      "url": "https://mcp.context7.com/mcp",
+      "description": "Library/framework documentation lookup."
+    },
+    "exa": {
+      "type": "remote",
+      "url": "https://mcp.exa.ai/mcp",
+      "description": "Live web search and webpage fetching."
+    },
+    "grep_app": {
+      "type": "remote",
+      "url": "https://mcp.grep.app",
+      "description": "Public GitHub code search and real-world examples."
+    }
+  },
+  "excludeAgents": [],
+  "excludeTools": [],
+  "timeout": 180
 }
 ```
 | Field | Default | Description |
 |-------|---------|-------------|
-| `enabled` | `true` | Whether tool/MCP routing is active |
-| `model` | *(from Raven.md)* | Override Raven's model without editing package files |
-| `reasoning_effort` | *(from Raven.md)* | Override Raven's reasoning effort (e.g. `"low"`, `"medium"`, `"high"`) |
-| `ravenInstructions` | `""` | Extra instructions appended to Raven's prompt. Useful for custom MCP usage rules. |
-| `routeTools` | built-in search/fetch tools plus `bash` | Exact tool names hard-routed through Raven. `bash` means route only search-like bash commands, not every bash call. e.g. `["grep", "glob", "bash", "linear_search_issues"]` |
-| `routeMcpServers` | `["context7", "exa", "grep_app"]` | MCP server prefixes hard-routed through Raven. `"linear"` routes tools like `linear_search_issues` and `linear_get_issue` |
-| `allowBundledMCPServers` | `true` | Whether Raven auto-registers bundled Context7, Exa, and Grep.app MCP defaults. Existing `opencode.jsonc` MCP entries are never overwritten. |
-| `excludeAgents` | `[]` | Agents that bypass Raven routing (case-insensitive). e.g. `["librarian", "explorer"]` |
-| `excludeTools` | `[]` | Exact tools that never get blocked, even if matched by `routeMcpServers`. e.g. `["my_mcp_validate"]` |
-| `timeout` | `180` | Max seconds for a `raven_seek` call. On timeout the session is kept for inspection. |
-| `stats` | *(auto)* | Session + global context saved by Raven (bytes + tokens). Managed automatically. |
-### MCP servers
-All three MCPs work without API keys. Add keys for higher rate limits:
-| MCP | URL | API key |
-|-----|-----|---------|
-| Context7 | `https://mcp.context7.com/mcp` | Free key at [context7.com/dashboard](https://context7.com/dashboard) — higher limits |
-| Exa AI | `https://mcp.exa.ai/mcp` | Free key at [exa.ai](https://exa.ai) — higher limits |
-| Grep.app | `https://mcp.grep.app` | Not available — public API, no key needed |
-When `allowBundledMCPServers` is `true`, Raven auto-registers bundled Context7, Exa, and Grep.app MCP defaults. It merges those MCP defaults with your existing `opencode.jsonc` settings, preserving custom headers, URLs, and `enabled: false` overrides. Set `allowBundledMCPServers` to `false` if you do not want Raven to add bundled MCP defaults.
-To add other MCPs, configure them in `opencode.jsonc`, then add their server prefix to `routeMcpServers` if you want Raven to route them. Raven does not install arbitrary MCPs from `raven-config.json`.
-Use `ravenInstructions` for extra Raven-only guidance, such as how to use custom MCPs:
-```json
-{
-  "ravenInstructions": "For Linear requests, prefer assigned open issues and include issue keys in the answer."
-}
-```
-To add an API key, override the MCP in your `opencode.jsonc` with a `headers` field:
+| `enabled` | `true` | Whether tool/MCP routing is active |
+| `model` | from `Raven.md` | Override Raven's model without editing package files |
+| `reasoning_effort` | from `Raven.md` | Override Raven's reasoning effort, such as `low`, `medium`, or `high` |
+| `ravenInstructions` | `""` | Extra instructions appended to Raven's prompt. Useful for custom MCP usage rules. |
+| `routeTools` | built-in search/fetch tools plus `bash` | Exact tool names hard-routed through Raven. `bash` routes only search-like bash commands, not every bash call. |
+| `routeToolKeywords` | `[]` | Case-insensitive substrings hard-routed through Raven for globally registered tools with non-standard names. Catches suffix-style names like `web_search_exa`. |
+| `onDemandMcpDescriptionDetail` | `"full"` | On-demand MCP guidance detail. `full` includes tool names/descriptions; `minimized` uses compact capability summaries. |
+| `onDemandMcpServers` | Context7, Exa, Grep.app | MCPs Raven connects to internally on demand, without registering full schemas in OpenCode global MCP config. Supports `remote` and `stdio`. |
+| `excludeAgents` | `[]` | Agents that bypass Raven routing, case-insensitive. |
+| `excludeTools` | `[]` | Exact tools that never get blocked, even if matched by auto-routed global MCP prefixes. |
+| `timeout` | `180` | Max seconds for a `raven_seek` call. On timeout the session is kept for inspection. |
+| `stats` | auto | Session and global estimated context saved by Raven. Managed automatically. |
+Use `ravenInstructions` for extra Raven-only guidance, such as how to use custom MCPs:
-```jsonc
+```json
 {
-  "mcp": {
-    "exa": {
-      "type": "remote",
-      "url": "https://mcp.exa.ai/mcp",
-      "headers": { "x-api-key": "{env:EXA_API_KEY}" },
-      "enabled": true
-    }
-  }
+  "ravenInstructions": "For Linear requests, prefer assigned open issues and include issue keys in the answer."
 }
 ```
-To disable an MCP entirely:
+## Routing And Exceptions
-```jsonc
+By default, Raven routes these built-in tools and auto-routes globally configured MCPs by detected server name:
+| Config | Default |
+|--------|---------|
+| `routeTools` | `grep`, `glob`, `webfetch`, `fetch`, `websearch`, `bash` |
+| `routeToolKeywords` | none |
+Global MCPs configured in OpenCode are auto-routed through Raven by server name. For example, an MCP named `linear` routes tools named `linear_*`. This works for any MCP whose OpenCode tool names use the normal `<server>_<tool>` prefix. Matching is case-insensitive.
+If a server uses suffix-style or mixed tool names, route by keyword instead. For example, `exa` catches names like `web_search_exa` and `web_fetch_exa`:
+```txt
+/raven route keyword add exa
+```
+If an MCP is routed but one tool should remain direct, add the exact tool to `excludeTools`:
+```json
 {
-  "mcp": {
-    "exa": { "type": "remote", "url": "https://mcp.exa.ai/mcp", "enabled": false }
-  }
+  "excludeTools": ["my_mcp_validate"]
 }
 ```
-## How it works
+To route one specific tool without routing the whole MCP server:
-| Hook | What it does |
-|------|--------------|
-| `config` | Registers Raven agent, optionally merges bundled Context7/Exa/Grep.app MCP defaults, loads MCP routing guidance |
-| `tool` | Registers `raven_seek` — creates Raven sessions with timeout, error recovery, timing, and session tree visibility. Tracks context saved for stats (both `raven_seek` and direct `@Raven`). |
-| `chat.message` | Tracks agent ↔ session mapping for allowlist and Raven exclusion |
-| `event` | Shows startup update notifications after the TUI event stream is ready |
-| `command.execute.before` | Handles `/raven on\|off\|route\|update\|model\|effort\|timeout\|stats\|status` |
-| `tool.execute.before` | Hard-blocks configured tools/MCPs for non-Raven, non-excluded agents (respects `excludeTools`). Error output gives the next `raven_seek(query="...")` call. Injects dynamic `<raven_guidance>` with configured routes into subagent prompts. |
-| `tool.execute.after` | Tracks direct `@Raven` calls for context-saved stats. |
-### Routed tools (blocked and redirected except for Raven and any agents in `excludeAgents`)
-By default, Raven routes these built-in tools and MCP server prefixes:
-| Config | Default |
-|------|--------|
-| `routeTools` | `grep`, `glob`, `webfetch`, `fetch`, `bash` |
-| `routeMcpServers` | `context7`, `exa`, `grep_app` |
-To route another MCP, add its server prefix. For example, `"linear"` routes every tool named `linear_*` through Raven:
-```txt
-/raven route mcp add linear
-```
-This works for any MCP whose opencode tool names share a prefix. For example, if an MCP exposes tools named `my_mcp_search`, `my_mcp_fetch`, and `my_mcp_get_item`, this routes all of them:
-```txt
-/raven route mcp add my_mcp
-```
-The prefix must match the actual tool name before `_`. If the tools are named `project_search`, add `project`, not the display name of the MCP. Matching is case-insensitive.
-If an MCP is routed but one tool should remain direct, add the exact tool to `excludeTools`:
-```json
-{
-  "routeMcpServers": ["context7", "exa", "grep_app", "my_mcp"],
-  "excludeTools": ["my_mcp_validate"]
-}
-```
-To route one specific tool without routing the whole MCP server:
-```txt
-/raven route tool add linear_search_issues
-```
-**Bash commands** — intercepted only while `bash` is included in `routeTools` and the command matches a primary search/discovery pattern:
+```txt
+/raven route tool add linear_search_issues
+```
+`bash` is intercepted only while `bash` is included in `routeTools` and the command matches a primary search/discovery pattern.
 | Pattern | Examples |
 |---------|----------|
@@ -248,44 +240,57 @@ To route one specific tool without routing the whole MCP server:
 | Filesystem exploration | `Get-ChildItem -Recurse`, `gci -Recurse`, `Get-ChildItem -Filter`, `find -name`, `find -type`, `ls -R`, `ls --recursive`, `dir /s` |
 | Shell bypass | `cmd /c dir /s`, `cmd /c findstr`, `cmd /c find`, `cmd /c tree` |
-**Unrestricted for non-Raven agents**: `read`, `task`, `subtask`, `raven_seek`, non-routed tools, and non-search `bash` commands.
+Unrestricted for non-Raven agents: `read`, `task`, `subtask`, `raven_seek`, non-routed tools, and non-search `bash` commands.
-**Allowed output filters**: Piped filters like `command | grep ...`, `command | rg ...`, `command | findstr ...`, and `command | head ...` are allowed. Raven only blocks search commands when they are used as primary discovery commands, not when they filter bounded output from another command.
-To stop routing search-like bash commands, remove `bash` from `routeTools`:
-```txt
-/raven route tool remove bash
-```
+Allowed output filters: piped filters like `command | grep ...`, `command | rg ...`, `command | findstr ...`, and `command | head ...` are allowed. Raven only blocks search commands when they are used as primary discovery commands, not when they filter bounded output from another command.
-**Bash quote stripping**: Quoted content in bash commands is stripped before pattern matching — `echo "use grep here"` won't falsely trigger blocking.
+To stop routing search-like bash commands, remove `bash` from `routeTools`:
+```txt
+/raven route tool remove bash
+```
-**Comment stripping**: Shell comments are stripped before matching — `# use grep later` won't falsely trigger blocking.
+Quoted content and shell comments in bash commands are stripped before pattern matching. For example, `echo "use grep here"` and `# use grep later` do not trigger routing.
-**Subagent guidance**: Every non-Raven, non-excluded subagent gets `<raven_guidance>` injected into its prompt at spawn time.
-The injected guidance includes the current `routeTools` and `routeMcpServers`, including user-added custom MCP prefixes, so subagents know which calls must go through `raven_seek`.
-### What Raven Saves
-Raven saves context from tool call results and raw MCP output by moving the work into a Raven session and returning a compact answer. It does not currently save context from MCP tool schemas that opencode loads into the main session when an MCP is enabled globally.
-This means large MCPs may still increase the main session's starting context. Raven still prevents repeated verbose tool outputs from accumulating in the main session.
-## Agent capabilities
+## What Raven Saves
-Raven itself has access to these tools (blocked for other agents when configured by the plugin):
+Raven saves context from tool call results and raw MCP output by moving the work into a Raven session and returning a compact answer. On-demand MCPs also avoid loading full MCP tool schemas into the main OpenCode session because Raven connects to them internally through `raven_mcp`.
+MCPs configured directly in OpenCode `opencode.jsonc` still load globally and may increase the main session's starting context. Use `onDemandMcpServers` for MCPs you want Raven to keep behind the context firewall.
+`/raven stats` uses a balanced estimate: Raven's final session token total minus the first Raven assistant turn's input/cache baseline, then minus the compact answer returned to the main session. This counts tool/web/MCP result context Raven handled while avoiding Raven's starting prompt and tool-schema overhead.
+`Avoided MCP schema load` is a separate estimate based on full loaded on-demand MCP tool schemas discovered by Raven but not loaded into the main model. Failed or pending MCPs do not count toward this total. It is stored in autogenerated MCP metadata and shown separately from delegated session savings.
+## How It Works
+| Hook | What it does |
+|------|--------------|
+| `config` | Registers Raven agent, loads MCP routing guidance, and starts on-demand MCP health/metadata checks. Bundled MCPs are on-demand by default, not injected into global OpenCode MCP config. |
+| `tool` | Registers `raven_seek` and Raven-only `raven_mcp`. `raven_seek` creates Raven sessions with timeout, error recovery, timing, and session tree visibility. Tracks context saved for stats. |
+| `chat.message` | Tracks agent to session mapping for allowlist and Raven exclusion. |
+| `event` | Shows startup update and MCP failure notifications after the TUI event stream is ready. |
+| `command.execute.before` | Handles `/raven help`, routing commands, MCP commands, update checks, model settings, timeout, and stats. |
+| `tool.execute.before` | Hard-blocks configured tools/MCPs for non-Raven, non-excluded agents. Error output gives the next `raven_seek(query="...")` call. Injects dynamic `<raven_guidance>` with configured routes into subagent prompts. |
+| `tool.execute.after` | Tracks direct `@Raven` calls for context-saved stats. |
+Every non-Raven, non-excluded subagent gets `<raven_guidance>` injected into its prompt at spawn time. The injected guidance includes `routeTools`, auto-detected global MCP prefixes, `routeToolKeywords`, and on-demand MCP capabilities.
+## Agent Capabilities
+Raven itself has access to these tools, blocked for other agents when configured by the plugin:
 | Tool / MCP | Purpose |
 |------------|---------|
 | `read`, `glob`, `grep`, `list` | Local codebase inspection |
-| `bash` (all commands) | Full local shell access (`rg`, `grep`, `dir`, `ls`, `Get-ChildItem`, `find`, etc.) |
-| `external_directory` | Allowed — no permission prompts when accessing paths outside the workspace |
-| Context7 | Library/framework/SDK/API docs |
-| Exa AI | Web search, news, pages, products |
-| Grep.app | Public GitHub examples |
-`raven_seek` is denied inside Raven itself so Raven cannot recursively call its own wrapper tool. Raven uses direct tools/MCPs instead.
+| `bash` | Full local shell access, including `rg`, `grep`, `dir`, `ls`, `Get-ChildItem`, and `find` |
+| `external_directory` | Allowed, with no permission prompts when accessing paths outside the workspace |
+| `raven_mcp` | Raven-only bridge to on-demand remote/stdio MCP servers |
+| Context7 | On-demand library/framework/SDK/API docs |
+| Exa AI | On-demand web search, news, pages, products |
+| Grep.app | On-demand public GitHub examples |
+`raven_seek` is denied inside Raven itself so Raven cannot recursively call its own wrapper tool. Raven uses direct tools, globally available MCPs, and `raven_mcp` for on-demand MCPs instead.
 Raven returns compact findings: answer, sources, relevant details, recommended next step, and uncertainty.

package/Raven.md CHANGED Viewed

@@ -1,5 +1,5 @@
 ---
-description: Tool/MCP delegation agent for web, docs, code, examples, and configured external systems.
+description: Context firewall for OpenCode that routes noisy search, docs, web, GitHub, and MCP calls through a free focused agent before they hit your main model.
 mode: subagent
 hidden: false
 model: opencode/deepseek-v4-flash-free
@@ -13,14 +13,15 @@ permission:
   bash: allow
   task: deny
   raven_seek: deny
+  raven_mcp: allow
   external_directory: allow
 ---
 You are Raven.
-You search, fetch, inspect, and use routed MCPs only.
+You search, fetch, inspect, and use routed MCPs only.
 You return compact findings only.
-Never call `raven_seek`; you are Raven. Use your direct tools and MCPs instead.
+Never call `raven_seek`; you are Raven. Use your direct tools, globally available MCPs, and `raven_mcp` for on-demand MCPs instead.
 When a query implies multiple independent searches, run tools in parallel (single turn) for speed.
@@ -34,6 +35,9 @@ Use tools/MCPs like this:
 **MCP usage guidance:**
+Use direct MCP tools when they are globally available in your tool list.
+Use `raven_mcp` for on-demand MCPs described in your prompt. If you do not know the exact tool name, call `raven_mcp` with `operation: "list_tools"` first, then call the selected tool with `operation: "call_tool"`. For `call_tool` and `get_prompt`, pass arguments as a JSON object string in `argumentsJson`.
 *Context7:*
 Use when implementing, configuring, or debugging code that depends on a library, framework, SDK, package, or API.
 Prefer Context7 over memory when docs may be version-specific or recently changed.
@@ -42,12 +46,12 @@ Prefer Context7 over memory when docs may be version-specific or recently change
 Use for live web search, current information, company/product research, reading webpages, comparing tools, and broad external research.
 Use Exa when the answer may depend on recent updates, pricing, docs pages, releases, or online sources.
-*Grep.app:*
-Use for searching public GitHub code examples, real-world usage patterns, config examples, and how other projects structure similar code.
-Use Grep.app when docs are unclear or when implementation examples would help.
-*Other routed MCPs:*
-When the caller asks for a configured MCP, use that MCP directly and return a compact summary of only what the primary agent needs.
+*Grep.app:*
+Use for searching public GitHub code examples, real-world usage patterns, config examples, and how other projects structure similar code.
+Use Grep.app when docs are unclear or when implementation examples would help.
+*Other routed MCPs:*
+When the caller asks for a configured MCP, use that MCP directly and return a compact summary of only what the primary agent needs.
 Output format:
@@ -55,7 +59,7 @@ Answer:
 * Short direct finding.
 Sources / locations:
-* File paths, URLs, docs, examples, MCP records, or local objects checked.
+* File paths, URLs, docs, examples, MCP records, or local objects checked.
 Relevant details:
 * Small notes only. No long code dumps.

package/example.gif ADDED Viewed

Binary file