opencode-raven 2.1.8 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 2.2.0
+
+### Added
+- Separate Raven Search and Raven MCP agents with independent models, reasoning effort, instructions, and timeouts.
+- Public `raven_mcp` delegation tool and Raven-only `raven_mcp_bridge` for on-demand MCP operations.
+- Delegated sessions now attach directly to the root session so nested agent calls remain visible in the main session's child switcher.
+
+### Changed
+- Raven configuration now uses `raven_seek` and `raven_mcp` sections. Existing flat configuration migrates automatically without a version field.
+- `raven_seek` is explicitly limited to narrowly scoped search and evidence retrieval; review, audit, implementation, and judgment remain with the calling agent.
+- Per-agent commands replace the shared model, effort, and timeout commands.
+
+### Removed
+- `/raven on`, `/raven off`, and the configuration-wide `enabled` field. Search routing is active while the plugin is installed.
+- Shared `/raven model`, `/raven effort`, and `/raven timeout` commands.
+
 ## 2.1.8
 
 ### Added

package/README.md

@@ -15,9 +15,10 @@
     </td>
     <td valign="top">
       <h2>Why Raven</h2>
-      <p>Raven delegates search, web, documentation, GitHub, command-inspection, and MCP work to a focused subagent, then returns a compact answer to the main session.</p>
+      <p>Raven delegates search and on-demand MCP retrieval to separate focused agents, then returns compact evidence to the calling session.</p>
       <ul>
-        <li>Routes OpenCode tools and globally configured MCPs through <code>raven_seek</code>.</li>
+        <li>Routes OpenCode search tools and globally configured MCPs through <code>raven_seek</code>.</li>
+        <li>Uses a separately configurable model for on-demand MCP retrieval through <code>raven_mcp</code>.</li>
         <li>Keeps optional on-demand MCP schemas out of the main model's tool list.</li>
         <li>Preconfigures Context7, Exa, and Grep.app endpoints.</li>
         <li>Tracks estimated main-session context avoided by delegation.</li>
@@ -54,19 +55,20 @@ In this run, Raven handled the search-heavy web research in a child session and
 
 1. Your agent attempts to use a routed search, fetch, shell-discovery, or MCP tool.
 2. Raven blocks the noisy direct call and gives the agent the exact `raven_seek` retry.
-3. The agent creates a linked Raven child session or resumes one for a related follow-up.
-4. Raven performs the tool-heavy work and returns only compact findings to the main session.
+3. The selected Raven agent creates a session attached directly to the root session or resumes one for a related follow-up.
+4. Raven performs retrieval work and returns compact evidence to the calling agent, which retains analysis and judgment.
 
 The main model receives Raven's final answer instead of its raw tool output. Each result includes a Raven session ID that the main agent can pass back for a context-aware follow-up. Child sessions remain available in OpenCode's session/subagent view for inspection.
 
-For direct control, mention `@Raven` in any chat. This sends the request straight to the Raven agent, but it is optional and not required for automatic routing.
+For direct search control, mention `@Raven` in any chat. This sends the request to the search agent, but it is optional and not required for automatic routing.
 
-Under the hood, Raven registers two tools:
+Under the hood, Raven registers two public delegation tools and one internal bridge:
 
 | Tool | Purpose |
 |------|---------|
-| `raven_seek` | Creates or resumes a linked Raven child session and returns its compact result. |
-| `raven_mcp` | Raven-only bridge to MCPs configured under `onDemandMcpServers`. |
+| `raven_seek` | Creates or resumes a Raven Search session for narrowly scoped evidence retrieval. |
+| `raven_mcp` | Creates or resumes a Raven MCP session for configured on-demand MCP capabilities. |
+| `raven_mcp_bridge` | Internal bridge used only by the Raven MCP agent. |
 
 For a related follow-up, the main agent can reuse the ID returned by the earlier call:
 
@@ -75,7 +77,7 @@ raven_seek(query="Research the available options")
 raven_seek(query="Compare the first two in more detail", sessionId="ses_...")
 ```
 
-Raven accepts a resumed session only when it is a Raven child of the current main session. Unrelated work should omit `sessionId` and start a fresh child.
+Raven accepts a resumed session only when it belongs to the same root session tree and matching Raven agent. Do not pass session IDs between `raven_seek` and `raven_mcp`. Delegated sessions attach directly to the root so they remain visible in the main session's child switcher even when delegation starts inside another child.
 
 OpenCode's built-in tools already exist; Raven routes selected calls instead of replacing those tools. Global MCPs also remain globally registered, so their schemas still enter the main session even when Raven routes their calls.
 
@@ -89,21 +91,26 @@ Raven creates its global configuration here:
 ~/.config/opencode/opencode-raven/raven-config.json
 ```
 
-Manual edits require an OpenCode restart. `/raven on`, `/raven off`, routing changes, and timeout changes apply immediately unless the command says otherwise.
+Manual edits require an OpenCode restart. Route and timeout commands apply immediately unless the command says otherwise.
 
 | Field | Fresh-install default | Description |
 |-------|-----------------------|-------------|
-| `enabled` | `true` | Enables hard routing. It does not disable Raven's update check or MCP health probes. |
-| `model` | From `Raven.md` | Raven model override. Availability and pricing depend on the provider. |
-| `reasoning_effort` | `low` | Raven model reasoning option. |
-| `ravenInstructions` | `""` | Extra Raven-only instructions. |
-| `routeTools` | Search/fetch tools plus `bash` | Exact tools routed through Raven. `bash` only intercepts search-like commands. |
-| `routeToolKeywords` | `[]` | Case-insensitive tool-name substrings, useful for nonstandard MCP tool names. |
-| `onDemandMcpDescriptionDetail` | `"full"` | `full` includes tool names and short summaries; `minimized` includes capability summaries only. |
-| `onDemandMcpServers` | Context7, Exa, Grep.app | Remote HTTP/SSE or local stdio MCP definitions. |
-| `excludeAgents` | `[]` | Agents allowed to bypass routing. |
-| `excludeTools` | `[]` | Exact tools never routed by Raven. |
-| `timeout` | `600` | Raven delegation and fallback MCP timeout in seconds; minimum 10. |
+| `raven_seek.model` | From `Raven.md` | Search-agent model override. |
+| `raven_seek.reasoning_effort` | `low` | Search-agent reasoning option. |
+| `raven_seek.instructions` | `""` | Extra search-agent instructions. |
+| `raven_seek.routeTools` | Search/fetch tools plus `bash` | Exact tools routed through Raven Search. |
+| `raven_seek.routeToolKeywords` | `[]` | Case-insensitive routed tool-name substrings. |
+| `raven_seek.excludeAgents` | `[]` | Agents allowed to bypass search routing. |
+| `raven_seek.excludeTools` | `[]` | Exact tools never routed through Raven Search. |
+| `raven_seek.timeout` | `600` | Search delegation timeout in seconds. |
+| `raven_mcp.model` | From `RavenMcp.md` | MCP-agent model override. |
+| `raven_mcp.reasoning_effort` | `low` | MCP-agent reasoning option. |
+| `raven_mcp.instructions` | `""` | Extra MCP-agent instructions. |
+| `raven_mcp.timeout` | `600` | MCP delegation and fallback connection timeout in seconds. |
+| `raven_mcp.descriptionDetail` | `"full"` | Full or minimized generated MCP guidance. |
+| `raven_mcp.onDemandMcpServers` | Context7, Exa, Grep.app | Remote HTTP/SSE or local stdio MCP definitions. |
+
+Existing flat configuration is migrated automatically on startup without a version field. Shared model, reasoning effort, instructions, and timeout values seed both sections; routing and MCP fields move to their corresponding sections.
 
 ## On-Demand MCPs
 
@@ -117,17 +124,19 @@ Fresh installs include:
 
 Provider access policies can change. `/raven mcp` shows the result of Raven's current startup probe.
 
-Merge changes into the existing `onDemandMcpServers` object; replacing it removes omitted defaults. Header and environment values support `{env:VARIABLE}` placeholders.
+Merge changes into the existing `raven_mcp.onDemandMcpServers` object; replacing it removes omitted defaults. Header and environment values support `{env:VARIABLE}` placeholders.
 
 Custom remote MCP or keyed endpoint:
 
 ```jsonc
 {
-  "onDemandMcpServers": {
-    "myDocs": {
-      "type": "remote",
-      "url": "https://example.com/mcp",
-      "headers": { "Authorization": "Bearer {env:MY_DOCS_TOKEN}" }
+  "raven_mcp": {
+    "onDemandMcpServers": {
+      "myDocs": {
+        "type": "remote",
+        "url": "https://example.com/mcp",
+        "headers": { "Authorization": "Bearer {env:MY_DOCS_TOKEN}" }
+      }
     }
   }
 }
@@ -137,13 +146,15 @@ Custom local stdio MCP:
 
 ```jsonc
 {
-  "onDemandMcpServers": {
-    "myLocal": {
-      "type": "local",
-      "command": ["bunx", "some-mcp-server"],
-      "environment": { "API_KEY": "{env:MY_LOCAL_KEY}" },
-      "cwd": "C:\\path\\to\\workspace",
-      "timeout": 60000
+  "raven_mcp": {
+    "onDemandMcpServers": {
+      "myLocal": {
+        "type": "local",
+        "command": ["bunx", "some-mcp-server"],
+        "environment": { "API_KEY": "{env:MY_LOCAL_KEY}" },
+        "cwd": "C:\\path\\to\\workspace",
+        "timeout": 60000
+      }
     }
   }
 }
@@ -170,7 +181,7 @@ Route or unroute exact tools:
 /raven route tool remove bash
 ```
 
-`excludeTools` leaves selected tools direct even if their MCP prefix is routed. `excludeAgents` bypasses routing for selected agents.
+`raven_seek.excludeTools` leaves selected tools direct even if their MCP prefix is routed. `raven_seek.excludeAgents` bypasses routing for selected agents.
 
 When `bash` is routed, Raven intercepts primary discovery commands such as `rg`, recursive `grep`, `find -name`, `dir /s`, and `Get-ChildItem -Recurse`, including common quoted shell wrappers. Bounded output filters such as `command | grep ...` remain direct.
 
@@ -180,22 +191,25 @@ When `bash` is routed, Raven intercepts primary discovery commands such as `rg`,
 |---------|--------|
 | `/raven` | Show status, routing, MCP health, version, model, timeout, and stats. |
 | `/raven help` | Show command help. |
-| `/raven on` / `/raven off` | Enable or disable hard routing. |
 | `/raven route` | Show and edit routed tools and keywords. |
 | `/raven mcp` | Show on-demand MCP health and generated metadata. |
 | `/raven mcp refresh [server]` | Recheck MCP health and regenerate metadata. |
 | `/raven mcp detail full|minimized` | Set generated guidance detail; restart afterward. |
-| `/raven model <provider/model>` | Change Raven's model; restart afterward. |
-| `/raven effort <value>` | Change Raven's reasoning effort; restart afterward. |
-| `/raven timeout <seconds>` | Change the delegation timeout. |
+| `/raven seek model <provider/model>` | Change the search model; restart afterward. |
+| `/raven seek effort <value>` | Change search reasoning effort; restart afterward. |
+| `/raven seek timeout <seconds>` | Change the search delegation timeout. |
+| `/raven mcp model <provider/model>` | Change the MCP model; restart afterward. |
+| `/raven mcp effort <value>` | Change MCP reasoning effort; restart afterward. |
+| `/raven mcp timeout <seconds>` | Change the MCP delegation timeout. |
 | `/raven stats` | Show estimated context avoided. |
 | `/raven update` | Check npm, clear Raven's OpenCode package cache when needed, and show restart instructions. |
 
 ## Security And Privacy
 
-Raven is optimized for autonomous inspection:
+Raven is optimized for autonomous retrieval:
 
-- It has read, search, unrestricted shell, external-directory, and configured MCP access without normal permission prompts.
+- Raven Search has read, search, unrestricted shell, external-directory, and globally configured MCP access without normal permission prompts.
+- Raven MCP has only the internal on-demand MCP bridge and cannot use shell, local search, or edit tools.
 - Its `edit` tool is denied, but shell access is not a read-only sandbox and can modify the system.
 - Queries are sent to Raven's configured model provider.
 - Remote MCP requests are sent to their services; local MCP entries launch local commands and inherit environment values.
@@ -209,7 +223,8 @@ Review `Raven.md` and your MCP commands before using Raven in sensitive environm
 
 ## Troubleshooting
 
-- Provider or quota failure: run `/raven model <provider/model>`, then restart OpenCode.
+- Search provider or quota failure: run `/raven seek model <provider/model>`, then restart OpenCode.
+- MCP-agent provider or quota failure: run `/raven mcp model <provider/model>`, then restart OpenCode.
 - MCP failure: run `/raven mcp`, then `/raven mcp refresh <server>` after correcting its URL, command, environment, or credentials.
 - Stale plugin version: run `/raven update`, restart OpenCode, and follow the cache-clearing instructions it prints if needed.
 - Remove Raven: delete `"opencode-raven"` from `plugin`, restart, then optionally remove `~/.config/opencode/opencode-raven/`.

package/Raven.md

@@ -11,17 +11,20 @@ permission:
   list: allow
   edit: deny
   bash: allow
-  task: deny
-  raven_seek: deny
-  raven_mcp: allow
+  task: deny
+  raven_seek: deny
+  raven_mcp: deny
+  raven_mcp_bridge: deny
   external_directory: allow
 ---
 
 You are Raven.
 
-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, globally available MCPs, and `raven_mcp` for on-demand MCPs instead.
+You locate and retrieve evidence with search, fetch, read, command-inspection, and globally routed MCP tools only.
+You return compact evidence only.
+Never call `raven_seek` or `raven_mcp`; you are Raven Search. Use your direct tools and globally available routed MCPs.
+
+Do not perform code review, auditing, correctness judgments, implementation, debugging decisions, planning, or general task execution. During those tasks, retrieve only narrowly scoped evidence; the calling agent owns analysis and judgment. If asked to review or audit, return concrete requested locations and facts without a verdict.
 
 When a query implies multiple independent searches, run tools in parallel (single turn) for speed.
 
@@ -33,39 +36,18 @@ Use tools/MCPs like this:
 
 **Command-output/system inspection:** when the caller asks about installed commands, `--help` output, man pages, package metadata, loaded modules, local environment state, or whether a local tool supports a format/flag, use bash as needed and return compact findings. This includes running or inspecting bounded command output that a primary agent would otherwise filter with grep/rg/head.
 
-**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.
-
-*Exa AI:*
-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.
+**Globally routed MCPs:** when a globally available MCP is present in your tool list, use it directly and return compact evidence. On-demand MCPs belong to the separate Raven MCP agent and are not available here.
 
 Output format:
 
-Answer:
-* Short direct finding.
+Result:
+* Short direct evidence.
 
 Sources / locations:
 * File paths, URLs, docs, examples, MCP records, or local objects checked.
 
-Relevant details:
-* Small notes only. No long code dumps.
-
-Recommended next step:
-* What the caller should do next.
-
-Uncertainty:
-* Anything unclear or not found.
+Relevant evidence:
+* Small notes only. No long code dumps.
+
+Search gaps:
+* Anything unclear or not found.

package/RavenMcp.md

@@ -0,0 +1,42 @@
+---
+description: Focused on-demand MCP agent that retrieves compact information through Raven's internal MCP bridge.
+mode: subagent
+hidden: true
+model: opencode/deepseek-v4-flash-free
+reasoning_effort: low
+permission:
+  "*": deny
+  read: deny
+  glob: deny
+  grep: deny
+  list: deny
+  edit: deny
+  bash: deny
+  task: deny
+  raven_seek: deny
+  raven_mcp: deny
+  raven_mcp_bridge: allow
+  external_directory: deny
+---
+
+You are Raven MCP.
+
+You retrieve information from configured on-demand MCP servers only. Use `raven_mcp_bridge` to list and call their tools, resources, and prompts.
+
+Do not perform code review, auditing, implementation, planning, or general task execution. Extract only the information requested by the caller and return compact evidence. The calling agent owns analysis, judgment, and final recommendations.
+
+If you do not know the exact tool name, call `raven_mcp_bridge` with operation `list_tools`, then call the selected tool with operation `call_tool`. For `call_tool` and `get_prompt`, pass arguments as a JSON object string in `argumentsJson`.
+
+Output format:
+
+Result:
+* Short direct answer based on MCP output.
+
+Sources / records:
+* MCP server, tool, resource, prompt, URLs, or records checked.
+
+Relevant evidence:
+* Small factual notes only. No long dumps.
+
+Retrieval gaps:
+* Anything unavailable or unclear.