opencode-raven 2.3.2 → 2.3.3

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 2.3.3
+
+### Fixed
+- V2 Raven agents auto-approve webfetch, websearch, fetch, and enabled global MCP tools at permission evaluation time, without blanket agent permissions. Main-agent permissions and explicit denials remain unchanged.
+- Blocked web search, URL fetching, and recognized global MCP calls now recommend `raven_mcp`; local search calls still recommend `raven_seek`. Routing availability and provider recovery use the selected agent.
+
+### Changed
+- Raven MCP now has the same retrieval tools as Raven Search, including local file access, shell, and built-in web tools, plus its private on-demand MCP bridge. Edit tools and nested delegation remain denied. V2 web/global MCP execution approvals apply to both Raven agents.
+- Delegation instructions distinguish lightweight local retrieval through `raven_seek` from online research through `raven_mcp`, even when no MCP is configured.
+
 ## 2.3.2
 
 ### Added

package/README.md

@@ -18,8 +18,8 @@
       <h2>Why Raven</h2>
       <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 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>Routes local search and filesystem discovery through lightweight <code>raven_seek</code>.</li>
+        <li>Uses a separately configurable model for online research, built-in web tools, and global or on-demand MCPs 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>
@@ -34,7 +34,17 @@
 
 ### OpenCode V2
 
-Use the v2 `plugins` key in `opencode.jsonc`:
+In OpenCode's **Install plugin** feature, enter `opencode-raven`.
+
+Or install globally from the CLI:
+
+```sh
+opencode plugin add opencode-raven
+```
+
+Either way, OpenCode manages the plugin configuration and automatically loads Raven's terminal companion—no separate terminal plugin install is needed.
+
+For manual configuration, use the v2 `plugins` key in `opencode.jsonc` instead:
 
 ```jsonc
 {
@@ -94,7 +104,7 @@ In this run, Raven handled the search-heavy web research in a child session and
 **Raven works automatically.** Ask OpenCode for what you need as usual. You do not need to mention Raven, run a command, or manually call a delegation tool.
 
 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.
+2. Raven blocks the noisy direct call and gives the agent the exact retry: `raven_seek` for local searches, or `raven_mcp` for web search, URL fetching, and global MCP tools.
 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.
 
@@ -105,7 +115,7 @@ The main model receives Raven's final answer instead of its raw tool output. Eac
 On V2, `raven_seek` and `raven_mcp` **run in the background by default**. The initial response contains a child-session handle, not the findings. The calling agent can continue independent work; Raven delivers compact findings or a failure notice to that same calling session when retrieval finishes, including when the caller is itself a child session.
 
 ```text
-raven_seek(query="Find the current API documentation")
+raven_mcp(query="Find the current API documentation")
 raven_mcp(query="Retrieve library examples", background=true)
 raven_seek(query="Find the definition needed for my next step", background=false)
 ```
@@ -124,17 +134,17 @@ Under the hood, Raven registers two public delegation tools and one internal bri
 
 | Tool | Purpose |
 |------|---------|
-| `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_seek` | Creates or resumes a lightweight Raven Search session for local file search, discovery, and command-output inspection. |
+| `raven_mcp` | Creates or resumes a Raven MCP session for online research using built-in web tools, global or on-demand MCPs, and local retrieval tools when needed for context. No MCP is required. |
 | `raven_mcp_bridge` | Internal bridge used only by the Raven MCP agent. |
 
-On OpenCode V2, Raven auto-approves permission checks for the public `raven_seek` and `raven_mcp` delegation tools instead of prompting on every call. Explicit deny rules still apply. This does not change permission checks for other tools or access restrictions on the internal MCP bridge.
+On OpenCode V2, Raven auto-approves permission checks for the public `raven_seek` and `raven_mcp` delegation tools instead of prompting on every call. Inside either Raven agent, it also auto-approves `webfetch`, `websearch`, `fetch`, and tools belonging to enabled globally configured MCP servers. Explicit deny rules still apply. These execution-time approvals do not add a blanket agent permission or change the main agent's tool permissions, model request, or access restrictions on the internal MCP bridge.
 
 For a related follow-up, the main agent can reuse the ID returned by the earlier call:
 
 ```text
-raven_seek(query="Research the available options")
-raven_seek(query="Compare the first two in more detail", sessionId="ses_...")
+raven_mcp(query="Research the available options")
+raven_mcp(query="Compare the first two in more detail", sessionId="ses_...")
 ```
 
 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.
@@ -234,6 +244,8 @@ Generated MCP metadata and main-model guidance live beside `raven-config.json`.
 
 Default routed tools are `grep`, `glob`, `webfetch`, `fetch`, `websearch`, and search-like `bash` commands. On OpenCode 2, Raven also recognizes the native `shell` tool; `bash` and `shell` are routing aliases, so existing routing settings continue to work. Exact `excludeTools` entries use the host's actual tool name.
 
+Local search tools route to `raven_seek`; `webfetch`, `fetch`, `websearch`, and recognized global MCP tools route to `raven_mcp`. Each route uses its target agent's configured model and recovery instructions. Raven MCP can use built-in web tools even with no on-demand MCP servers configured.
+
 Global MCPs are automatically routed when their OpenCode tool names use the normal `<server>_<tool>` prefix. Use a keyword for suffix-style names:
 
 ```txt
@@ -275,13 +287,13 @@ When `bash` is routed, Raven intercepts primary discovery commands such as `rg`,
 Raven is optimized for autonomous retrieval:
 
 - 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.
+- Raven MCP has the same retrieval access as Raven Search, plus the internal on-demand MCP bridge. It can use built-in web tools without an MCP and inspect local files for research context.
+- Both agents deny edit tools and nested delegation, 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.
 - Startup performs an npm update check and probes enabled on-demand MCPs.
 
-Review `Raven.md` and your MCP commands before using Raven in sensitive environments.
+Review `Raven.md`, `RavenMcp.md`, and your MCP commands before using Raven in sensitive environments.
 
 ## Context Estimates
 

package/Raven.md

@@ -1,5 +1,5 @@
 ---
-description: Context firewall for OpenCode that routes noisy search, docs, web, GitHub, and MCP calls through a focused agent before they hit your main model.
+description: Lightweight local evidence retrieval through file search, filesystem discovery, and command-output inspection.
 mode: subagent
 hidden: false
 reasoning_effort: low
@@ -23,6 +23,8 @@ You locate and retrieve evidence with search, fetch, read, command-inspection, a
 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.
 
+Your primary role is local evidence retrieval. Calling agents should use `raven_mcp` for online research, web search, URL fetching, documentation, public GitHub search, and MCP requests.
+
 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.

package/RavenMcp.md

@@ -1,38 +1,43 @@
 ---
-description: Focused on-demand MCP agent that retrieves compact information through Raven's internal MCP bridge.
+description: Online research agent with web search, page fetching, local retrieval tools, and on-demand MCP access.
 mode: subagent
 hidden: true
 reasoning_effort: low
 permission:
-  "*": deny
-  read: deny
-  glob: deny
-  grep: deny
-  list: deny
+  read: allow
+  glob: allow
+  grep: allow
+  list: allow
   edit: deny
-  bash: deny
+  bash: allow
   task: deny
   raven_seek: deny
   raven_mcp: deny
   raven_mcp_bridge: allow
-  external_directory: deny
+  external_directory: allow
 ---
 
 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.
+You retrieve online evidence using web search, page fetching, globally available MCPs, and configured on-demand MCP servers. You can also read and search local files or inspect bounded command output when needed for the request.
 
-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.
+Use a matching MCP capability when available, especially when the caller names a server. Use `raven_mcp_bridge` for on-demand MCPs; use globally available MCP tools directly. Built-in websearch/webfetch tools are also available, including when no suitable MCP is available.
 
-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`.
+Never call `raven_seek` or `raven_mcp`; use your direct tools and the bridge instead. Do not edit files or delegate to other agents.
+
+Do not perform code review, auditing, correctness judgments, implementation, debugging decisions, 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.
+
+When using an on-demand MCP, 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`.
+
+When the caller provides an exact URL, fetch that page and extract the requested evidence rather than replacing it with broad search. Run independent retrievals in parallel and return compact evidence, not raw tool output.
 
 Output format:
 
 Result:
-* Short direct answer based on MCP output.
+* Short direct answer based on retrieved evidence.
 
 Sources / records:
-* MCP server, tool, resource, prompt, URLs, or records checked.
+* URLs, file paths, MCP servers, tools, resources, prompts, or records checked.
 
 Relevant evidence:
 * Small factual notes only. No long dumps.

package/mcp-guidance.md

@@ -2,18 +2,22 @@
 
 Raven performs search and information retrieval only. The calling agent must retain code review, auditing, correctness judgments, implementation, debugging decisions, planning, and final recommendations.
 
-Non-Raven agents use `raven_seek` for narrowly scoped evidence retrieval when a routed local search, filesystem discovery, URL fetch, web/docs/GitHub search, globally configured MCP, or search-like shell command is blocked. Include the original tool intent and relevant arguments. Do not delegate an entire review or general task.
+Non-Raven agents use `raven_seek` for narrowly scoped local evidence retrieval: file search, filesystem discovery, and command-output inspection. Use it when a local search tool or search-like shell command is blocked. Include the original tool intent and relevant arguments. Do not delegate an entire review or general task.
 
-Non-Raven agents use `raven_mcp` for information available through Raven's configured on-demand MCP servers. Include the target server or capability when obvious. Only the `raven-mcp` agent calls `raven_mcp_bridge`; it must use the bridge directly instead of either public delegation tool.
+Non-Raven agents use `raven_mcp` for online research: web search, URL fetching, library documentation, public GitHub search, and global or on-demand MCP requests. When `websearch`, `webfetch`, `fetch`, or a global MCP tool is blocked, retry through `raven_mcp`, not `raven_seek`. Include the target server or capability when obvious. Raven MCP can use built-in web tools and local retrieval tools as well as MCPs; an MCP is not required. Only the `raven-mcp` agent calls `raven_mcp_bridge`; it must use the bridge directly instead of either public delegation tool.
 
 When a request follows up on an earlier Raven result, pass the session ID returned by the matching tool. Omit `sessionId` for unrelated work and never pass a `raven_seek` session to `raven_mcp` or vice versa.
 
 Appropriate `raven_seek` requests:
 
 - Find definitions, references, files, or concrete code locations.
+- Inspect bounded command output or local system facts.
+
+Appropriate `raven_mcp` requests:
+
 - Fetch and extract facts from a specific URL.
 - Search current web, documentation, or public GitHub sources.
-- Inspect bounded command output or local system facts.
+- Retrieve information through global or on-demand MCP capabilities, using local files for context when needed.
 
 Inappropriate delegation:
 
@@ -26,7 +30,7 @@ Examples:
 
 `raven_seek(query="Find every caller of validateToken and return file/line locations")`
 
-`raven_seek(query="Fetch/read https://example.com and extract the documented install flags")`
+`raven_mcp(query="Fetch/read https://example.com and extract the documented install flags")`
 
 `raven_mcp(query="Use Context7 to retrieve the current API documentation for Effect Schema decoding")`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-raven",
-  "version": "2.3.2",
+  "version": "2.3.3",
   "description": "Context-saving search and on-demand MCP routing for OpenCode through focused Raven agents.",
   "main": "./index.ts",
   "exports": {

package/raven-core.ts

@@ -762,14 +762,24 @@ export default (async (input: Pick<PluginInput, "client" | "directory"> & { proj
     return config.raven_seek.excludeAgents.some((a) => a.toLowerCase() === lower)
   }
 
-  function isRouteConfigured(toolName: string): boolean {
-    if (!modelOperational("seek")) return false
+  function isGlobalMcpTool(toolName: string): boolean {
+    const tool = toolName.toLowerCase()
+    return globalMcpServers.some((server) => tool.startsWith(`${server.toLowerCase()}_`)
+      || tool.startsWith(`${server.replace(/[^a-zA-Z0-9_-]/g, "_").toLowerCase()}_`))
+  }
+
+  function routingKind(toolName: string): DelegationKind {
+    return ["websearch", "webfetch", "fetch"].includes(toolName.toLowerCase()) || isGlobalMcpTool(toolName) ? "mcp" : "seek"
+  }
+
+  function isRouteConfigured(toolName: string): boolean {
+    if (!modelOperational(routingKind(toolName))) return false
     const tool = toolName.toLowerCase()
     if (NEVER_ROUTE_TOOLS.has(tool)) return false
     const aliases = tool === "bash" || tool === "shell" ? ["bash", "shell"] : [tool]
     if (config.raven_seek.routeTools?.some((name) => aliases.includes(name.toLowerCase()))) return true
     if (config.raven_seek.routeToolKeywords?.some((keyword) => tool.includes(keyword.toLowerCase()))) return true
-    return globalMcpServers.some((server) => tool.startsWith(`${server.toLowerCase()}_`))
+    return isGlobalMcpTool(tool)
   }
 
   function compactArgs(value: any): any {
@@ -798,13 +808,14 @@ export default (async (input: Pick<PluginInput, "client" | "directory"> & { proj
     return query.length > 300 ? `${query.slice(0, 297)}...` : query
   }
 
-  function rerouteMessage(tool: string, args: any): string {
-    if (ravenProviderIssues.seek) {
-      return `Raven search is currently unavailable: ${ravenProviderIssues.seek}
-
-${ravenRecoveryInstructions("seek")}`
-    }
-    return `The '${tool}' tool call is blocked by Raven. Your next tool call should be raven_seek(query="${attemptedQuery(tool, args).replace(/"/g, "'")}").`
+  function rerouteMessage(tool: string, args: any): string {
+    const kind = routingKind(tool)
+    if (ravenProviderIssues[kind]) {
+      return `Raven ${kind === "mcp" ? "MCP" : "search"} is currently unavailable: ${ravenProviderIssues[kind]}
+
+${ravenRecoveryInstructions(kind)}`
+    }
+    return `The '${tool}' tool call is blocked by Raven. Your next tool call should be raven_${kind}(query="${attemptedQuery(tool, args).replace(/"/g, "'")}").`
   }
 
   function ravenRecoveryInstructions(kind: DelegationKind): string {
@@ -821,7 +832,7 @@ Then restart opencode for the model change to take effect. If the task can be co
   }
 
   function routeSummary(): string {
-    if (!modelOperational("seek")) return "Raven routing: inactive until the configured Search model is loaded."
+    if (!modelOperational("seek") && !modelOperational("mcp")) return "Raven routing: inactive until a configured Raven model is loaded."
     const tools = config.raven_seek.routeTools?.length ? config.raven_seek.routeTools.join(", ") : "(none)"
     const mcps = globalMcpServers.length ? `${globalMcpServers.join(", ")} (auto-detected)` : "none detected"
     const keywords = config.raven_seek.routeToolKeywords?.length ? config.raven_seek.routeToolKeywords.join(", ") : "(none)"
@@ -2092,9 +2103,9 @@ Then restart opencode for the model change to take effect. If the task can be co
     // Register raven_seek tool — lets agents with task:false still delegate through Raven
     tool: {
       "raven_seek": tool({
-        description: "Search and evidence retrieval only. Creates or resumes a Raven Search session for routed local search, filesystem discovery, URL fetching, web/docs/GitHub search, globally configured MCP searches, or command-output inspection. Do not delegate code review, auditing, correctness judgments, implementation, debugging decisions, planning, or general task execution; the calling agent must perform that work.",
+        description: "Local search and evidence retrieval only. Creates or resumes a lightweight Raven Search session for file search, filesystem discovery, or command-output inspection. Use raven_mcp instead for online research, web search, URL fetching, documentation, public GitHub search, or MCP requests. Do not delegate code review, auditing, correctness judgments, implementation, debugging decisions, planning, or general task execution; the calling agent must perform that work.",
         args: {
-          query: tool.schema.string().describe("A narrowly scoped search or evidence-retrieval request. Include original blocked tool args, exact URLs, paths, patterns, or bounded command-output checks. Do not ask Raven to review or audit code."),
+          query: tool.schema.string().describe("A narrowly scoped local search or evidence-retrieval request. Include original blocked tool args, paths, patterns, or bounded command-output checks. Do not ask Raven to review or audit code."),
           sessionId: tool.schema.string().optional().describe("Raven session ID returned by an earlier raven_seek call. Provide it only when this request should continue that session's research context."),
         },
         async execute(args, context) {
@@ -2320,7 +2331,7 @@ Then restart opencode for the model change to take effect. If the task can be co
         },
       }),
       "raven_mcp": tool({
-        description: "On-demand MCP information retrieval only. Creates or resumes a dedicated Raven MCP session that selects and calls MCPs configured under raven_mcp.onDemandMcpServers. Use for matching MCP capabilities, not local search, code review, auditing, implementation, planning, or general task delegation.",
+        description: "Online research and MCP evidence retrieval only. Creates or resumes a Raven MCP session for web search, URL fetching, documentation, public GitHub search, and global or on-demand MCP requests. Has built-in web tools and local retrieval tools plus the internal MCP bridge; an MCP is not required. Use raven_seek for purely local searches. Do not delegate code review, auditing, correctness judgments, implementation, debugging decisions, planning, or general task execution; the calling agent retains analysis and judgment.",
         args: {
           query: tool.schema.string().describe("The information to retrieve and, when known, the target MCP server or capability. The calling agent retains analysis and judgment."),
           sessionId: tool.schema.string().optional().describe("Raven MCP session ID returned by an earlier raven_mcp call. Provide it only to continue that MCP retrieval context."),

package/v2.ts

@@ -57,7 +57,8 @@ export async function setupRaven(ctx: Context): Promise<Plugin.Cleanup> {
   const controller = new AbortController()
   const background = backgroundDelegations(ctx, controller.signal)
   const location = { directory: ctx.location.directory }
-  const agents: Record<string, AgentDefinition> = {}
+  const agents: Record<string, AgentDefinition> = {}
+  const globalMcpToolPrefixes = new Set<string>()
   const activeSessions = new Set<string>()
   let emitNotice: (notice: z.infer<typeof RavenRpc.events.notice.schema>) => Promise<void> = async () => {}
   let runtime: Runtime | undefined
@@ -194,9 +195,12 @@ export async function setupRaven(ctx: Context): Promise<Plugin.Cleanup> {
       agent: agents,
       instructions: [] as string[],
     }
-    await raven.config(config)
-    registrations.push(await ctx.mcp.transform((editor) => {
-      raven.globalMcpRouting(editor.list().filter(([, server]) => !server.disabled).map(([name]) => name))
+    await raven.config(config)
+    registrations.push(await ctx.mcp.transform((editor) => {
+      const names = editor.list().filter(([, server]) => !server.disabled).map(([name]) => name)
+      raven.globalMcpRouting(names)
+      globalMcpToolPrefixes.clear()
+      for (const name of names) globalMcpToolPrefixes.add(`${name.replace(/[^a-zA-Z0-9_-]/g, "_")}_`)
     }))
 
     async function executeCommand(raw: string) {
@@ -211,12 +215,19 @@ export async function setupRaven(ctx: Context): Promise<Plugin.Cleanup> {
     registrations.push(rpc)
     emitNotice = (notice) => rpc.events.emit("notice", notice)
 
-    // Delegation needs no extra confirmation. Preserve deny rules and leave
-    // child tools and the Raven-only MCP bridge's permissions unchanged.
-    registrations.push(await ctx.permission.hook("evaluate", (event) => {
-      if (event.effect === "ask" && (event.action === "raven_seek" || event.action === "raven_mcp")) {
-        event.effect = "allow"
-      }
+    // Approve specific retrieval actions at execution time, not by adding a
+    // blanket agent allow rule that changes Raven's entire tool policy.
+    // Explicit configured denials are final and do not invoke this hook.
+    registrations.push(await ctx.permission.hook("evaluate", (event) => {
+      if (event.effect !== "ask") return
+      const delegation = event.action === "raven_seek" || event.action === "raven_mcp"
+      const retrieval = (event.agent === "raven" || event.agent === "raven-mcp") && (
+        event.action === "webfetch" || event.action === "websearch" || event.action === "fetch"
+        || [...globalMcpToolPrefixes].some((prefix) => event.action.startsWith(prefix))
+      )
+      if (delegation || retrieval) {
+        event.effect = "allow"
+      }
     }))
 
     registrations.push(await ctx.agent.transform((editor) => {