opencode-raven 1.2.5 → 1.2.6

package/README.md

@@ -66,7 +66,7 @@ This checks npm, clears Raven's opencode plugin cache when a newer version exist
 Manual alternatives:
 
 ```bash
-bun add opencode-raven@latest
+bun update --latest opencode-raven
 # or
 npm install opencode-raven@latest
 ```
@@ -87,10 +87,12 @@ You can call Raven directly with `@Raven` in any opencode chat. The Raven agent
 
 ## raven_seek
 
-When search tools are blocked, agents use **`raven_seek`** — a unified tool that handles ALL search types (local codebase, web, docs, GitHub examples). Output includes elapsed time and tokens processed.
+When search, fetch, or discovery tools are blocked, agents use **`raven_seek`** — a unified tool that handles 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.
 
 ```
 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.")
 ```
 
 The agent doesn't see Raven's internal tool calls — just the final findings. Raven parallelizes independent searches internally within a single session.
@@ -132,6 +134,8 @@ All three MCPs work without API keys. Add keys for higher rate 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 |
 
+Raven merges these MCP defaults with your existing `opencode.jsonc` settings, preserving custom headers, URLs, and `enabled: false` overrides.
+
 To add an API key, override the MCP in your `opencode.jsonc` with a `headers` field:
 
 ```jsonc
@@ -161,11 +165,11 @@ To disable an MCP entirely:
 
 | Hook | What it does |
 |------|--------------|
-| `config` | Registers Raven agent, adds Context7/Exa/Grep.app MCPs, loads MCP guidance |
+| `config` | Registers Raven agent, merges Context7/Exa/Grep.app MCP defaults, loads MCP guidance |
 | `tool` | Registers `raven_seek` — creates Raven sessions with timeout, error recovery, timing, and session tree visibility. Tracks context processed for stats (both `raven_seek` and direct `@Raven`). |
 | `chat.message` | Tracks agent ↔ session mapping for allowlist and Raven exclusion |
-| `command.execute.before` | Handles `/raven on\|off\|model\|effort\|timeout\|stats\|status` |
-| `tool.execute.before` | Blocks search tools for non-Raven, non-excluded agents (respects `excludeTools`). Injects `<raven_guidance>` into subagent prompts. |
+| `command.execute.before` | Handles `/raven on\|off\|update\|model\|effort\|timeout\|stats\|status` |
+| `tool.execute.before` | Blocks search tools for non-Raven, non-excluded agents (respects `excludeTools`). Error output gives the next `raven_seek(query="...")` call. Injects concise `<raven_guidance>` into subagent prompts. |
 | `tool.execute.after` | Counts output bytes from direct `@Raven` calls for accurate stats. |
 
 ### Blocked tools (redirected except for Raven and any agents in `excludeAgents`)
@@ -183,18 +187,22 @@ To disable an MCP entirely:
 | `exa_deep_researcher_start`, `exa_deep_researcher_check`, `exa_deep_search_exa` | Exa AI MCP |
 | `grep_app_searchGitHub` | Grep.app MCP |
 
-**Bash commands** — intercepted when the command or description matches a search pattern:
+**Bash commands** — intercepted when the command matches a primary search/discovery pattern:
 
 | Pattern | Examples |
 |---------|----------|
 | 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` |
-| Shell bypass | `cmd /c dir`, `cmd /c findstr`, `cmd /c find`, `cmd /c where`, `cmd /c tree` |
+| 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`, and non-search `bash` commands.
 
-**Unrestricted**: `read`, `task`, `subtask`, `raven_seek`, 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.
 
 **Bash quote stripping**: Quoted content in bash commands is stripped before pattern matching — `echo "use grep here"` won't falsely trigger blocking.
 
+**Comment stripping**: Shell comments are stripped before matching — `# use grep later` 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
@@ -210,6 +218,8 @@ Raven itself has access to these tools (blocked for other agents by the plugin):
 | 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.
+
 Raven returns compact findings: answer, sources, relevant details, recommended next step, and uncertainty.
 
 ## License

package/Raven.md

@@ -12,13 +12,15 @@ permission:
   edit: deny
   bash: allow
   task: deny
+  raven_seek: deny
   external_directory: allow
 ---
 
 You are Raven.
 
-You search only.
+You search, fetch, and inspect only.
 You return compact findings only.
+Never call `raven_seek`; you are Raven. Use your direct tools and MCPs instead.
 
 When a query implies multiple independent searches, run tools in parallel (single turn) for speed.
 
@@ -26,6 +28,10 @@ Use tools/MCPs like this:
 
 **Local code search:** use rg, grep, glob, list, and read only small relevant sections.
 
+**Specific URLs/pages:** when the caller gives a URL, fetch/read that exact URL and extract the requested information. Do not replace an exact URL request with only broad web search unless the page is unavailable.
+
+**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:**
 
 *Context7:*

package/index.ts

@@ -43,26 +43,73 @@ 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/i
+const SEARCH_BASH_RE = /\b(?:rg|ripgrep|grep|egrep|fgrep|git\s+grep|ack|ag\b|findstr|Select-String)\b|\b(?:Get-ChildItem|gci)\b(?=[^|;&\n]*(?:-Recurse|-Filter|-Include|\s-[A-Za-z]*r[A-Za-z]*\b))|\bdir\b(?=[^|;&\n]*(?:[/-][sS]\b|-Recurse|-Filter|-Include))|\bls\b(?=[^|;&\n]*(?:\s-[A-Za-z]*R[A-Za-z]*\b|--recursive\b))|\bfind\b\s+.*(?:-name|-type)\b/i
 
 // 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 stripShellComments(cmd: string): string {
+  return cmd
+    .split("\n")
+    .map((line) => line.replace(/(^|\s)#.*$/, "$1").trimEnd())
+    .join("\n")
+}
+
 function stripQuotedContent(cmd: string): string {
-  return stripHeredocs(cmd)
+  return stripShellComments(stripHeredocs(cmd)
     .replace(/'[^']*'/g, "''")
-    .replace(/"[^"]*"/g, '""')
+    .replace(/"[^"]*"/g, '""'))
+}
+
+function splitPipelineSegments(cmd: string): string[] {
+  const segments: string[] = []
+  let current = ""
+  for (let i = 0; i < cmd.length; i++) {
+    const char = cmd[i]
+    const prev = cmd[i - 1]
+    const next = cmd[i + 1]
+    if (char === "|" && prev !== "|" && next !== "|") {
+      segments.push(current)
+      current = ""
+    } else {
+      current += char
+    }
+  }
+  segments.push(current)
+  return segments
+}
+
+function isOutputFilterSegment(segment: string): boolean {
+  return /^\s*(?:grep|ripgrep|rg|egrep|fgrep|findstr|Select-String|head|tail)\b/i.test(segment)
+}
+
+function hasSearchAfterCommandSeparator(segment: string): boolean {
+  const separator = segment.search(/;|&&|\|\|/)
+  return separator !== -1 && SEARCH_BASH_RE.test(segment.slice(separator))
+}
+
+function commandLooksLikeSearch(cmd: string): boolean {
+  const lower = cmd.toLowerCase().trim()
+  if (/^cmd\s+\/c\s+"?(?:findstr|find|tree)\b/.test(lower)) return true
+  if (/^cmd\s+\/c\s+"?dir\b[^\n]*\s\/s\b/.test(lower)) return true
+
+  return splitPipelineSegments(cmd).some((segment, index) => {
+    // Allow bounded filters over output already produced by the previous command:
+    //   pacman -Qi libarchive | head -15
+    //   7z i | grep -i udf
+    // These are not Raven-worthy filesystem/web/doc searches.
+    if (index > 0 && isOutputFilterSegment(segment)) return hasSearchAfterCommandSeparator(segment)
+    return SEARCH_BASH_RE.test(segment)
+  })
 }
 
 function isSearchBash(tool: string, args: any): boolean {
   if (tool !== "bash") return false
   const raw = String(args?.command ?? "")
   const cmd = stripQuotedContent(raw)
-  const desc = stripQuotedContent(String(args?.description ?? ""))
-  const lower = raw.toLowerCase().trim()
-  return SEARCH_BASH_RE.test(cmd) || SEARCH_BASH_RE.test(desc) || /^cmd\s+\/c\s+"?(dir|findstr|find|where|tree)\b/.test(lower)
+  return commandLooksLikeSearch(cmd)
 }
 
 // ── Config file shape ──
@@ -224,7 +271,19 @@ export default ((input: PluginInput) => {
     return config.excludeAgents.some((a) => a.toLowerCase() === lower)
   }
 
-  const REROUTE_MSG = "Search tools are blocked. Use raven_seek(query=\"...\") for all searches — local codebase, web, docs, and GitHub examples."
+  const RAVEN_GUIDANCE = `Search/fetch tools are blocked by Raven. If one is blocked, your next tool call should be raven_seek(query="<same search/fetch request>").`
+
+  function attemptedQuery(tool: string, args: any): string {
+    if (!args || typeof args !== "object") return `${tool}: ${JSON.stringify(args)}`
+    const direct = args.query ?? args.pattern ?? args.url ?? args.urls ?? args.command ?? args.path ?? args.filePath
+    const value = direct !== undefined ? direct : args
+    const text = typeof value === "string" ? value : JSON.stringify(value)
+    return text.length > 500 ? `${text.slice(0, 497)}...` : text
+  }
+
+  function rerouteMessage(tool: string, args: any): string {
+    return `The '${tool}' tool call is blocked by Raven. Your next tool call should be raven_seek(query="${attemptedQuery(tool, args).replace(/"/g, "'")}").`
+  }
 
   // ── Context processed by raven_seek ──
   let sessionBytes = 0
@@ -289,7 +348,7 @@ export default ((input: PluginInput) => {
   }
 
   function manualUpdateText(latest = "latest"): string {
-    return `Restart opencode to load the update.\n\nManual alternatives:\n  bun add ${PACKAGE_NAME}@${latest}\n  npm install ${PACKAGE_NAME}@${latest}\n\nIf opencode still loads the old version, clear its plugin cache and restart:\n  PowerShell: Remove-Item -Recurse -Force "$HOME\\.cache\\opencode\\packages\\${PACKAGE_NAME}*"\n  macOS/Linux: rm -rf ~/.cache/opencode/packages/${PACKAGE_NAME}*`
+    return `Restart opencode to load the update.\n\nManual alternatives:\n  bun update --latest ${PACKAGE_NAME}\n  npm install ${PACKAGE_NAME}@${latest}\n\nIf opencode still loads the old version, clear its plugin cache and restart:\n  PowerShell: Remove-Item -Recurse -Force "$HOME\\.cache\\opencode\\packages\\${PACKAGE_NAME}*"\n  macOS/Linux: rm -rf ~/.cache/opencode/packages/${PACKAGE_NAME}*`
   }
 
   async function notifyIfUpdateAvailable() {
@@ -307,19 +366,26 @@ export default ((input: PluginInput) => {
     } catch { /* update checks are best-effort */ }
   }
 
+  function ensureRemoteMcp(configInput: any, key: string, url: string) {
+    const existing = configInput.mcp?.[key] && typeof configInput.mcp[key] === "object"
+      ? configInput.mcp[key]
+      : {}
+    const type = existing.type ?? "remote"
+    configInput.mcp[key] = {
+      ...existing,
+      type,
+      ...(type === "local" ? {} : { url: existing.url ?? url }),
+      enabled: existing.enabled ?? true,
+    }
+  }
+
   return {
     config(configInput: any) {
       // MCP servers
       configInput.mcp = configInput.mcp || {}
-      configInput.mcp.context7 = {
-        type: "remote", url: "https://mcp.context7.com/mcp", enabled: true,
-      }
-      configInput.mcp.exa = {
-        type: "remote", url: "https://mcp.exa.ai/mcp", enabled: true,
-      }
-      configInput.mcp.grep_app = {
-        type: "remote", url: "https://mcp.grep.app", enabled: true,
-      }
+      ensureRemoteMcp(configInput, "context7", "https://mcp.context7.com/mcp")
+      ensureRemoteMcp(configInput, "exa", "https://mcp.exa.ai/mcp")
+      ensureRemoteMcp(configInput, "grep_app", "https://mcp.grep.app")
 
       // Inject MCP guidance as a startup instruction file (absolute path for npm compat)
       configInput.instructions = configInput.instructions || []
@@ -357,9 +423,9 @@ export default ((input: PluginInput) => {
     // Register raven_seek tool — lets agents with task:false still search through Raven
     tool: {
       "raven_seek": tool({
-        description: "Unified search tool — use only when task delegation to Raven (subagent_type=\"raven\") is unavailable. Handles ALL searches: local codebase, web, docs, and GitHub examples via Context7, Exa AI, and Grep.app.",
+        description: "Unified Raven search/fetch/inspection tool. Use this whenever grep, glob, WebFetch/fetch, websearch, docs lookup, GitHub search, or search-like bash would be used. Handles local codebase search, filesystem discovery, specific URL/page reads, web/docs research, GitHub examples, and command-output/system inspection via Raven.",
         args: {
-          query: tool.schema.string().describe("What to search for — be specific about what you need (docs, code examples, web info, etc.)"),
+          query: tool.schema.string().describe("What Raven should search, fetch, read, or inspect. Include exact URLs when replacing WebFetch. Include commands/output checks when replacing grep/rg/head over command output."),
         },
         async execute(args, context) {
           const started = Date.now()
@@ -378,6 +444,8 @@ export default ((input: PluginInput) => {
               return { title: "Raven Seek", output: "Failed to create Raven session." }
             }
 
+            ravenSessions.add(sessionId)
+
             // Emit sessionId so the TUI renders a clickable delegation box
             context.metadata({ metadata: { sessionId } })
 
@@ -510,6 +578,10 @@ export default ((input: PluginInput) => {
     },
 
     "tool.execute.before"(input: any, output: any) {
+      if (input.tool === "raven_seek" && (ravenSessions.has(input.sessionID) || sessionAgents.get(input.sessionID) === "raven")) {
+        throw new Error("raven_seek is disabled inside Raven. Use Raven's direct search/fetch tools instead.")
+      }
+
       if (!config.enabled) return
       if (ravenSessions.has(input.sessionID)) return
       if (isExcluded(sessionAgents.get(input.sessionID))) return
@@ -525,7 +597,7 @@ export default ((input: PluginInput) => {
           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, ls, dir, bash search commands) are blocked. Use raven_seek(query=\"...\") for ALL searches — local codebase, web, docs, and GitHub examples.\n</raven_guidance>`
+          output.args[field] = `${output.args[field] ?? ""}\n\n<raven_guidance>\n${RAVEN_GUIDANCE}\n</raven_guidance>`
         }
       }
 
@@ -534,7 +606,7 @@ export default ((input: PluginInput) => {
       const isSearchBashCmd = isSearchBash(input.tool, output.args || input.args)
 
       if (isSearchTool || isSearchBashCmd) {
-        throw new Error(REROUTE_MSG)
+        throw new Error(rerouteMessage(input.tool, output.args || input.args))
       }
     },
 

package/mcp-guidance.md

@@ -1,9 +1,23 @@
-## MCP usage guidance — delegate to Raven (subagent_type="raven") for these:
+## Raven search/fetch guidance
 
-- **Context7** — library/framework/SDK/API docs. Prefer over memory when docs may be version-specific or recently changed.
-- **Exa AI** — live web search, news, company/product research, webpages, tool comparisons. Use when answers depend on recent updates, pricing, releases, or online sources.
-- **Grep.app** — public GitHub code examples, real-world usage patterns, config examples. Use when docs are unclear or implementation examples would help.
+Do not call grep, glob, WebFetch/fetch, websearch, Context7, Exa, Grep.app, or search-like bash discovery commands directly.
 
-## Built-in search tools (grep, glob, search-like bash) are blocked and routed to Raven automatically.
+Use `raven_seek(query="...")` as the next tool call for ALL search/fetch/research tasks:
 
-Use raven_seek(query="...") for ALL searches — local codebase, web, docs, and GitHub examples.
+- local codebase search
+- filesystem discovery
+- reading a specific URL or webpage
+- web search and current information
+- docs/library/API lookup
+- public GitHub examples
+- command-output or local system inspection that would otherwise use grep/rg/head over command output
+
+Examples:
+
+`raven_seek(query="Search the repo for where auth tokens are validated")`
+
+`raven_seek(query="Fetch/read https://example.com and summarize the install instructions")`
+
+`raven_seek(query="Check whether archivemount/libarchive supports ISO or UDF. Use docs, web, or command output as needed.")`
+
+Simple piped output filters like `command | grep ...`, `command | rg ...`, `command | findstr ...`, or `command | head ...` are allowed when they only filter bounded output from the immediately preceding command.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-raven",
-  "version": "1.2.5",
+  "version": "1.2.6",
   "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": {