opencode-raven 1.1.1 → 1.2.1

package/README.md

@@ -5,7 +5,7 @@
 <td><img src="Raven.png" alt="Raven" width="768" /></td>
 <td>
 <strong>Search-first subagent for <a href="https://opencode.ai">opencode</a></strong><br/>
-Intercepts search tool calls and routes them to a dedicated <strong>@raven</strong> agent with Context7, Exa AI, and Grep.app MCPs.
+Intercepts search tool calls and routes them to a hidden Raven agent with Context7, Exa AI, and Grep.app MCPs.
 </td>
 </tr>
 </table>
@@ -16,7 +16,7 @@ Search is the most common thing agents do — and the most wasteful. Every searc
 
 1. **Cost** — Use a free model like `opencode/deepseek-v4-flash-free` for all search, saving your expensive model's context for actual work.
 2. **Reliability** — Hard-enforced interception. Other plugins suggest delegation; Raven *blocks* search tools for non-Raven agents and redirects them. No more agents ignoring your instructions and searching directly.
-3. **Simplicity** — One plugin, one agent, zero config. No bundled agents or features you don't need. Works with any agent or workflow. Just add it to `opencode.jsonc` and restart.
+3. **Simplicity** — One plugin, one agent, auto-configured. No bundled agents or features you don't need. Works with any agent or workflow. Just add it to `opencode.jsonc` and restart.
 
 ## Install
 
@@ -40,42 +40,49 @@ Restart opencode.
 
 | Command | Action |
 |---------|--------|
-| `/raven` | Show status — enabled/disabled, current model |
-| `/raven on` | Enable search tool redirection to @raven (default) |
+| `/raven` | Show status — enabled/disabled, current model, reasoning effort |
+| `/raven on` | Enable search tool redirection (default) |
 | `/raven off` | Disable interception — all agents can use search tools directly |
-| `/raven model <name>` | Change Raven's model (e.g. `/raven model opencode/deepseek-v4-flash-free`) |
+| `/raven model <name>` | Change Raven's model (requires restart) |
+| `/raven effort <value>` | Change Raven's reasoning effort (requires restart) |
+| `/raven stats` | Show blocked calls, context saved (session + global) |
 
-Config persists across restarts in `raven-config.json` (next to your `opencode.jsonc`).
+Config persists across restarts in `~/.config/opencode/raven-config.json` (global, shared across all projects). Auto-created on first run.
 
-## raven_seek — fallback for agents without task
+## raven_seek
 
-When search tools are blocked, agents are told to delegate to Raven via the `task` tool (`subagent_type="raven"`). This is the preferred path — the Raven subagent runs visibly in its own session, and you can see its work.
-
-Some agents have `task: deny` and can't delegate. **`raven_seek`** is the fallback for those agents — a custom tool that any agent can call directly, no `task` permission needed:
+When search tools are blocked, agents use **`raven_seek`** — a tool that creates a hidden Raven session, runs the search, and returns compact results:
 
 ```
 raven_seek(query: "how to use useEffect cleanup")
 ```
 
-The tool creates a Raven session behind the scenes, sends the query, and returns results. It's less visible than task delegation, so it's only used when task isn't available.
+The agent doesn't see Raven's internal tool calls — just the final findings. Raven parallelizes independent searches internally within a single session.
 
 ## Configuration
 
 ### raven-config.json
 
-Created automatically on first toggle. Edit manually or use `/raven` commands:
+Located at `~/.config/opencode/raven-config.json`. Auto-created on first run. Edit manually or use `/raven` commands:
 
 ```json
 {
   "enabled": true,
-  "model": "opencode/deepseek-v4-flash-free"
+  "model": "opencode/deepseek-v4-flash-free",
+  "reasoning_effort": "low",
+  "excludeAgents": [],
+  "excludeTools": []
 }
 ```
 
 | Field | Default | Description |
 |-------|---------|-------------|
 | `enabled` | `true` | Whether search tool interception is active |
-| `model` | *(built-in default)* | Override Raven's model without editing package files |
+| `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"`) |
+| `excludeAgents` | `[]` | Agents that bypass search tool blocking (case-insensitive). e.g. `["librarian", "explorer"]` |
+| `excludeTools` | `[]` | Tools that never get blocked. e.g. `["glob", "webfetch"]` |
+| `stats` | *(auto)* | Global blocked call count and context saved. Managed automatically. |
 
 ### MCP servers
 
@@ -117,19 +124,18 @@ To disable an MCP entirely:
 | Hook | What it does |
 |------|--------------|
 | `config` | Registers Raven agent, adds Context7/Exa/Grep.app MCPs, loads MCP guidance |
-| `tool` | Registers `raven_seek` — fallback tool for agents that can't use `task` |
-| `chat.message` | Tracks Raven's session IDs so its own tools aren't blocked |
-| `command.execute.before` | Handles `/raven on\|off\|model\|status` |
-| `tool.execute.before` | Throws to abort disabled tools before they execute — no wasted API calls |
-| `tool.execute.after` | Safety net: replaces output if the tool somehow still ran |
+| `tool` | Registers `raven_seek` — hidden Raven sessions with error recovery for API failures |
+| `chat.message` | Tracks agent ↔ session mapping for allowlist and Raven exclusion |
+| `command.execute.before` | Handles `/raven on\|off\|model\|effort\|status` |
+| `tool.execute.before` | Blocks search tools for non-Raven, non-excluded agents. Injects `<raven_guidance>` into subagent prompts. Throttled: full message once per session, silent after. Tracks blocked calls + context saved. |
 
-### Blocked tools (redirected for all agents except Raven itself)
+### Blocked tools (redirected except for Raven and any agents in `excludeAgents`)
 
 **Dedicated search tools:**
 
 | Tool | Source |
 |------|--------|
-| `grep`, `glob` | Built-in |
+| `grep`, `glob`, `webfetch`, `fetch` | Built-in |
 | `websearch_web_search_exa` | WebSearch MCP |
 | `context7_resolve-library-id`, `context7_query-docs` | Context7 MCP |
 | `exa_web_search_exa`, `exa_web_fetch_exa`, `exa_web_search_advanced_exa` | Exa AI MCP |
@@ -145,7 +151,11 @@ To disable an MCP entirely:
 | Content search | `rg`, `grep`, `egrep`, `fgrep`, `git grep`, `ack`, `ag`, `findstr`, `Select-String` |
 | Filesystem exploration | `Get-ChildItem`, `gci`, `find -name`, `find -type`, `ls -R`, `dir /s` |
 
-**Unrestricted**: `webfetch`, `read`, `task`, `raven_seek`, and non-search `bash` commands.
+**Unrestricted**: `read`, `task`, `subtask`, `raven_seek`, and non-search `bash` commands.
+
+**Bash quote stripping**: Quoted content in bash commands is stripped before pattern matching — `echo "use grep here"` won't falsely trigger blocking.
+
+**Subagent guidance**: Every non-Raven, non-excluded subagent gets `<raven_guidance>` injected into its prompt at spawn time.
 
 ## Agent capabilities
 

package/Raven.md

@@ -25,6 +25,8 @@ You are Raven.
 You search only.
 You return compact findings only.
 
+When a query implies multiple independent searches, run tools in parallel (single turn) for speed.
+
 Use tools/MCPs like this:
 
 **Local code search:** use rg, grep, glob, list, and read only small relevant sections.

package/index.ts

@@ -1,7 +1,8 @@
 import type { Plugin, PluginInput } from "@opencode-ai/plugin"
 import { tool } from "@opencode-ai/plugin"
-import { readFileSync, writeFileSync, existsSync } from "node:fs"
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs"
 import { join } from "node:path"
+import { homedir } from "node:os"
 
 // ── Resolve paths relative to this package (works in node_modules/) ──
 const PKG_DIR = import.meta.dirname!
@@ -14,6 +15,8 @@ const SEARCH_TOOLS = [
   // Built-in tools
   "grep",
   "glob",
+  "webfetch",
+  "fetch",
   // WebSearch MCP
   "websearch_web_search_exa",
   // Context7 MCP
@@ -38,10 +41,21 @@ const SEARCH_TOOLS = [
 // ── Bash commands that look like search workarounds ──
 const SEARCH_BASH_RE = /\b(rg|ripgrep|grep|egrep|fgrep|git\s+grep|ack|ag\b|findstr|Select-String|Get-ChildItem|gci\b|dir\b\s+[/-][sS]|ls\b\s+-[rR]|find\b\s+.*-name|find\b\s+.*-type)\b/
 
+// Strip quoted content to avoid false positives (e.g. echo "use grep here")
+function stripHeredocs(cmd: string): string {
+  return cmd.replace(/<<-?\s*["']?(\w+)["']?[\s\S]*?\n\s*\1/g, "")
+}
+
+function stripQuotedContent(cmd: string): string {
+  return stripHeredocs(cmd)
+    .replace(/'[^']*'/g, "''")
+    .replace(/"[^"]*"/g, '""')
+}
+
 function isSearchBash(tool: string, args: any): boolean {
   if (tool !== "bash") return false
-  const cmd = String(args?.command ?? "")
-  const desc = String(args?.description ?? "")
+  const cmd = stripQuotedContent(String(args?.command ?? ""))
+  const desc = stripQuotedContent(String(args?.description ?? ""))
   return SEARCH_BASH_RE.test(cmd) || SEARCH_BASH_RE.test(desc)
 }
 
@@ -49,14 +63,24 @@ function isSearchBash(tool: string, args: any): boolean {
 interface RavenConfig {
   enabled: boolean
   model?: string
+  reasoning_effort?: string
+  excludeAgents?: string[]
+  excludeTools?: string[]
+  stats?: { blocked: number; bytesSaved: number; tools: Record<string, number> }
 }
 
-const DEFAULT_CONFIG: RavenConfig = { enabled: true }
-
 // ── Parse Raven.md frontmatter ──
 const ravenMd = readFileSync(RAVEN_MD, "utf-8")
 const { frontmatter: fm, prompt: ravenPrompt } = parseRavenMd(ravenMd)
 
+const DEFAULT_CONFIG: RavenConfig = {
+  enabled: true,
+  model: fm.model,
+  reasoning_effort: fm.reasoning_effort,
+  excludeAgents: [],
+  excludeTools: [],
+}
+
 function parseRavenMd(raw: string): { frontmatter: Record<string, any>; prompt: string } {
   const parts = raw.split("---")
   if (parts.length < 3) {
@@ -137,8 +161,8 @@ function extractOptions(fm: Record<string, any>): Record<string, any> {
 export default ((input: PluginInput) => {
   const client = input.client
 
-  // Config file lives in the project directory (next to opencode.jsonc)
-  const configFile = join(input.directory, "raven-config.json")
+  // Config file lives in the global opencode config directory
+  const configFile = join(homedir(), ".config", "opencode", "raven-config.json")
 
   function loadConfig(): RavenConfig {
     try {
@@ -147,20 +171,98 @@ export default ((input: PluginInput) => {
         return {
           enabled: raw.enabled !== false,
           model: raw.model,
+          reasoning_effort: raw.reasoning_effort,
+          excludeAgents: Array.isArray(raw.excludeAgents) ? raw.excludeAgents : [],
+          excludeTools: Array.isArray(raw.excludeTools) ? raw.excludeTools : [],
+          stats: raw.stats || undefined,
         }
       }
     } catch { /* ignore corruption, use defaults */ }
+    // Auto-create config file with defaults on first run
+    saveConfig(DEFAULT_CONFIG)
     return { ...DEFAULT_CONFIG }
   }
 
   function saveConfig(config: RavenConfig) {
     try {
+      mkdirSync(join(homedir(), ".config", "opencode"), { recursive: true })
       writeFileSync(configFile, JSON.stringify(config, null, 2) + "\n")
     } catch { /* non-fatal: config won't persist but toggle still works in-session */ }
   }
 
   let config = loadConfig()
   const ravenSessions = new Set<string>()
+  const sessionAgents = new Map<string, string>()
+
+  // ── Check if an agent is excluded from Raven enforcement (case-insensitive) ──
+  function isExcluded(agent: string | undefined): boolean {
+    if (!agent || !config.excludeAgents?.length) return false
+    const lower = agent.toLowerCase()
+    return config.excludeAgents.some((a) => a.toLowerCase() === lower)
+  }
+
+  // Throttle: show the full error message once per session, then silent
+  const throttledSessions = new Set<string>()
+  const REROUTE_MSG = "Search tools are blocked. Use raven_seek(query=\"...\") to search through Raven."
+
+  // ── Session stats: track blocked calls + estimated context saved ──
+  const sessionStats = new Map<string, { blocked: number; tools: Map<string, number>; bytesSaved: number }>()
+  const globalStats = { blocked: 0, tools: new Map<string, number>(), bytesSaved: 0 }
+  // Restore global stats from config
+  if (config.stats) {
+    globalStats.blocked = config.stats.blocked ?? 0
+    globalStats.bytesSaved = config.stats.bytesSaved ?? 0
+    for (const [t, n] of Object.entries(config.stats.tools ?? {})) {
+      globalStats.tools.set(t, n)
+    }
+  }
+
+  function getBytesEstimate(tool: string): number {
+    const ESTIMATES: Record<string, number> = {
+      grep: 2000, glob: 2000,
+      webfetch: 16000, fetch: 16000,
+      websearch_web_search_exa: 8000,
+      context7_resolve_library_id: 1000, context7_query_docs: 4000,
+      exa_web_search_exa: 8000, exa_web_fetch_exa: 16000,
+      exa_web_search_advanced_exa: 8000, exa_company_research_exa: 8000,
+      exa_crawling_exa: 12000, exa_people_search_exa: 6000,
+      exa_linkedin_search_exa: 6000, exa_get_code_context_exa: 4000,
+      exa_deep_researcher_start: 8000, exa_deep_researcher_check: 2000,
+      exa_deep_search_exa: 8000,
+      grep_app_searchGitHub: 4000,
+    }
+    return ESTIMATES[tool] ?? 2000 // default for bash search / unknown
+  }
+
+  function trackBlock(sessionID: string, tool: string) {
+    // Session stats
+    let stats = sessionStats.get(sessionID)
+    if (!stats) {
+      stats = { blocked: 0, tools: new Map(), bytesSaved: 0 }
+      sessionStats.set(sessionID, stats)
+    }
+    stats.blocked++
+    stats.tools.set(tool, (stats.tools.get(tool) ?? 0) + 1)
+    stats.bytesSaved += getBytesEstimate(tool)
+    // Global stats
+    globalStats.blocked++
+    globalStats.tools.set(tool, (globalStats.tools.get(tool) ?? 0) + 1)
+    globalStats.bytesSaved += getBytesEstimate(tool)
+    // Persist to config
+    config.stats = { blocked: globalStats.blocked, bytesSaved: globalStats.bytesSaved, tools: Object.fromEntries(globalStats.tools) }
+    saveConfig(config)
+  }
+
+  function formatBytes(bytes: number): string {
+    return bytes >= 1_000_000 ? `${(bytes / 1_000_000).toFixed(1)}MB`
+      : bytes >= 1000 ? `${(bytes / 1000).toFixed(1)}KB`
+      : `${bytes}B`
+  }
+
+  function formatTokens(bytes: number): string {
+    const tokens = Math.round(bytes / 4)
+    return tokens >= 1000 ? `${(tokens / 1000).toFixed(1)}K` : `${tokens}`
+  }
 
   return {
     config(configInput: any) {
@@ -189,7 +291,10 @@ export default ((input: PluginInput) => {
         mode: fm.mode || "subagent",
         hidden: fm.hidden !== undefined ? fm.hidden : false,
         model: config.model || fm.model,
-        options: extractOptions(fm),
+        options: {
+          ...extractOptions(fm),
+          ...(config.reasoning_effort ? { reasoning_effort: config.reasoning_effort } : {}),
+        },
         permission: fm.permission || {},
         prompt: ravenPrompt,
       }
@@ -246,16 +351,27 @@ export default ((input: PluginInput) => {
 
             return { title: "Raven Seek", output }
           } catch (err: any) {
-            return { title: "Raven Seek", output: `Raven search failed: ${err.message || err}` }
+            const msg = String(err?.message ?? err ?? "").toLowerCase()
+            const hint =
+              /rate.?limit|too many requests|429/i.test(msg) ? "Raven rate limited — wait 30s then retry with a narrower query."
+              : /quota|usage.?limit|billing|insufficient.*(?:credit|balance|quota)/i.test(msg) ? "Raven API quota exhausted — proceed without search, tell user what's missing."
+              : /token|context.?length|too large|too long/i.test(msg) ? "Raven query too large — shorten your query and retry."
+              : /model|unavailable|down|not found/i.test(msg) ? "Raven model unavailable — retry later, or proceed without search."
+              : /timeout|timed.?out|econnrefused/i.test(msg) ? "Raven timed out — retry with a narrower query."
+              : `Raven search failed. Proceed without search — note gaps for the user. [${err.message || err}]`
+            return { title: "Raven Seek", output: hint }
           }
         },
       }),
     },
 
-    // Track Raven sessions so we don't block its own tools
+    // Track agent ↔ session mapping for allowlist + Raven exclusion
     "chat.message"(input: any, _output: any) {
-      if (input.agent === "raven") {
-        ravenSessions.add(input.sessionID)
+      if (input.agent) {
+        sessionAgents.set(input.sessionID, input.agent)
+        if (input.agent === "raven") {
+          ravenSessions.add(input.sessionID)
+        }
       }
     },
 
@@ -274,6 +390,15 @@ export default ((input: PluginInput) => {
         config.enabled = false
         saveConfig(config)
         output.parts.push({ type: "text", text: "Raven search interception disabled. All agents can use search tools directly." })
+      } else if (arg === "stats") {
+        const session = sessionStats.get(input.sessionID)
+        const sessionStr = !session || session.blocked === 0
+          ? "  No blocks this session."
+          : `  Session: ${session.blocked} blocked, ~${formatBytes(session.bytesSaved)} (~${formatTokens(session.bytesSaved)} tokens)`
+        const globalStr = globalStats.blocked === 0
+          ? "  Global: no blocks yet."
+          : `  Global: ${globalStats.blocked} blocked, ~${formatBytes(globalStats.bytesSaved)} (~${formatTokens(globalStats.bytesSaved)} tokens)`
+        output.parts.push({ type: "text", text: `Raven stats:\n${sessionStr}\n${globalStr}` })
       } else if (arg.startsWith("model ")) {
         const model = raw.slice(6).trim()
         if (!model) {
@@ -283,42 +408,56 @@ export default ((input: PluginInput) => {
           saveConfig(config)
           output.parts.push({ type: "text", text: `Raven model set to: ${model}\nRestart opencode for the change to take effect.` })
         }
+      } else if (arg.startsWith("effort ")) {
+        const effort = raw.slice(7).trim()
+        if (!effort) {
+          output.parts.push({ type: "text", text: `Usage: /raven effort <value>\nCurrent: ${config.reasoning_effort || fm.reasoning_effort || "(default)"}` })
+        } else {
+          config.reasoning_effort = effort
+          saveConfig(config)
+          output.parts.push({ type: "text", text: `Raven reasoning effort set to: ${effort}\nRestart opencode for the change to take effect.` })
+        }
       } else {
         const enabled = config.enabled ? "enabled" : "disabled"
         const model = config.model || fm.model || "(default)"
-        output.parts.push({ type: "text", text: `Raven is ${enabled}. Model: ${model}\n\nCommands:\n  /raven on      — enable search interception\n  /raven off     — disable search interception\n  /raven model <name> — change Raven's model (requires restart)` })
+        const effort = config.reasoning_effort || fm.reasoning_effort || "(default)"
+        output.parts.push({ type: "text", text: `Raven is ${enabled}. Model: ${model}. Reasoning: ${effort}\n\nCommands:\n  /raven on      — enable search interception\n  /raven off     — disable search interception\n  /raven model <name> — change Raven's model (requires restart)\n  /raven effort <value> — change Raven's reasoning effort (requires restart)\n  /raven stats   — show blocked calls and context saved` })
       }
     },
 
     "tool.execute.before"(input: any, output: any) {
       if (!config.enabled) return
       if (ravenSessions.has(input.sessionID)) return
+      if (isExcluded(sessionAgents.get(input.sessionID))) return
+      if (config.excludeTools?.includes(input.tool)) return
+
+      // ── Subagent prompt injection: inject Raven guidance into every subagent ──
+      if ((input.tool === "task" || input.tool === "subtask") && output.args) {
+        const subagentType = input.tool === "task" ? (output.args.subagent_type ?? "") : ""
+        if (subagentType !== "raven" && !isExcluded(subagentType)) {
+          const field = ["prompt", "description", "request", "objective", "query"].find(
+            (f) => f in output.args
+          ) ?? "prompt"
+          output.args[field] = `${output.args[field] ?? ""}\n\n<raven_guidance>\nSearch tools (grep, glob, Context7, Exa, Grep.app, bash search) are blocked. Use raven_seek(query="...") to search through Raven.\n</raven_guidance>`
+        }
+      }
 
+      // ── Block search tools for non-Raven agents ──
       const isSearchTool = SEARCH_TOOLS.includes(input.tool)
       const isSearchBashCmd = isSearchBash(input.tool, output.args || input.args)
 
-      if (!isSearchTool && !isSearchBashCmd) return
-
-      throw new Error(
-        "Search tool disabled — delegate to Raven via the task tool (subagent_type=\"raven\")"
-      )
+      if (isSearchTool || isSearchBashCmd) {
+        trackBlock(input.sessionID, isSearchBashCmd ? "bash(search)" : input.tool)
+        if (throttledSessions.has(input.sessionID)) {
+          throw new Error("")
+        }
+        throttledSessions.add(input.sessionID)
+        throw new Error(REROUTE_MSG)
+      }
     },
 
     "tool.execute.after"(input: any, output: any) {
-      if (!config.enabled) return
-      if (ravenSessions.has(input.sessionID)) return
-
-      const isSearchTool = SEARCH_TOOLS.includes(input.tool)
-      const isSearchBashCmd = isSearchBash(input.tool, input.args || output.args)
-
-      if (!isSearchTool && !isSearchBashCmd) return
-
-      const msg = "Search tool disabled — delegate to Raven via the task tool (subagent_type=\"raven\")"
-      output.output = msg
-      try {
-        const raw = output as any
-        if (raw.content?.[0]?.text) raw.content[0].text = msg
-      } catch {}
+      // Reserved for future analytics / redirect tracking (#5)
     },
   }
 }) satisfies Plugin

package/mcp-guidance.md

@@ -6,4 +6,4 @@
 
 ## Built-in search tools (grep, glob, search-like bash) are blocked and routed to Raven automatically.
 
-If task delegation is unavailable, use the raven_seek tool as a fallback.
+Use raven_seek(query="...") to search through Raven.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-raven",
-  "version": "1.1.1",
-  "description": "Search-first subagent for opencode — intercepts search tools and routes them to a dedicated @raven agent with Context7, Exa AI, and Grep.app MCPs",
+  "version": "1.2.1",
+  "description": "Search-first subagent for opencode — intercepts search tools and routes them through a hidden Raven agent with Context7, Exa AI, and Grep.app MCPs",
   "main": "./index.ts",
   "exports": {
     ".": "./index.ts"