opencode-raven 1.2.4 → 1.2.6

package/README.md

@@ -43,6 +43,7 @@ Restart opencode.
 | `/raven` | Show status — enabled/disabled, model, reasoning effort, timeout |
 | `/raven on` | Enable search tool redirection (default) |
 | `/raven off` | Disable interception — all agents can use search tools directly |
+| `/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) |
@@ -50,16 +51,48 @@ Restart opencode.
 
 Config persists across restarts in `~/.config/opencode/raven-config.json` (global, shared across all projects). Auto-created on first run.
 
+## Updates
+
+opencode caches npm plugins, so `"opencode-raven"` / `"opencode-raven@latest"` may not automatically refresh after a new npm release.
+
+Raven checks npm at startup. If an update is available, it shows a TUI notification. To update:
+
+```txt
+/raven update
+```
+
+This checks npm, clears Raven's opencode plugin cache when a newer version exists, and tells you to restart opencode.
+
+Manual alternatives:
+
+```bash
+bun update --latest opencode-raven
+# or
+npm install opencode-raven@latest
+```
+
+If opencode still loads the old cached plugin, clear the opencode plugin cache and restart:
+
+```powershell
+Remove-Item -Recurse -Force "$HOME\.cache\opencode\packages\opencode-raven*"
+```
+
+```bash
+rm -rf ~/.cache/opencode/packages/opencode-raven*
+```
+
 ## Direct access
 
 You can call Raven directly with `@Raven` in any opencode chat. The Raven agent runs with full filesystem and MCP access — no permission prompts.
 
 ## 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.
@@ -68,7 +101,7 @@ The agent doesn't see Raven's internal tool calls — just the final findings. R
 
 ### raven-config.json
 
-Located at `~/.config/opencode/raven-config.json`. Auto-created on first run. Edit manually or use `/raven` commands:
+Located at `~/.config/opencode/raven-config.json`. Auto-created on first run and auto-migrated on startup when new default fields are added. Edit manually or use `/raven` commands:
 
 ```json
 {
@@ -101,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
@@ -130,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`)
@@ -152,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
@@ -179,8 +218,10 @@ 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
 
-MIT
+MIT

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

@@ -1,6 +1,6 @@
 import type { Plugin, PluginInput } from "@opencode-ai/plugin"
 import { tool } from "@opencode-ai/plugin"
-import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from "node:fs"
+import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync, readdirSync, rmSync } from "node:fs"
 import { join } from "node:path"
 import { homedir, tmpdir } from "node:os"
 
@@ -9,6 +9,9 @@ const PKG_DIR = import.meta.dirname!
 
 const RAVEN_MD = join(PKG_DIR, "Raven.md")
 const MCP_GUIDANCE_MD = join(PKG_DIR, "mcp-guidance.md")
+const PACKAGE_JSON = JSON.parse(readFileSync(join(PKG_DIR, "package.json"), "utf-8"))
+const PACKAGE_NAME = PACKAGE_JSON.name || "opencode-raven"
+const PACKAGE_VERSION = PACKAGE_JSON.version || "0.0.0"
 
 // ── Search tools that should be intercepted for non-Raven agents ──
 const SEARCH_TOOLS = [
@@ -40,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 ──
@@ -171,19 +221,30 @@ export default ((input: PluginInput) => {
   // Config file lives in the global opencode config directory
   const configFile = join(homedir(), ".config", "opencode", "raven-config.json")
 
+  function normalizeConfig(raw: any): RavenConfig {
+    const source = raw && typeof raw === "object" ? raw : {}
+    const normalized: RavenConfig = { ...DEFAULT_CONFIG, ...source }
+
+    normalized.enabled = source.enabled !== false
+    normalized.model = typeof source.model === "string" ? source.model : DEFAULT_CONFIG.model
+    normalized.reasoning_effort = typeof source.reasoning_effort === "string" ? source.reasoning_effort : DEFAULT_CONFIG.reasoning_effort
+    normalized.excludeAgents = Array.isArray(source.excludeAgents) ? source.excludeAgents : []
+    normalized.excludeTools = Array.isArray(source.excludeTools) ? source.excludeTools : []
+    normalized.timeout = typeof source.timeout === "number" ? source.timeout : DEFAULT_CONFIG.timeout
+    normalized.stats = source.stats || undefined
+
+    return normalized
+  }
+
   function loadConfig(): RavenConfig {
     try {
       if (existsSync(configFile)) {
         const raw = JSON.parse(readFileSync(configFile, "utf-8"))
-        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 : [],
-          timeout: typeof raw.timeout === "number" ? raw.timeout : undefined,
-          stats: raw.stats || undefined,
+        const normalized = normalizeConfig(raw)
+        if (JSON.stringify(raw) !== JSON.stringify(normalized)) {
+          saveConfig(normalized)
         }
+        return normalized
       }
     } catch { /* ignore corruption, use defaults */ }
     // Auto-create config file with defaults on first run
@@ -210,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
@@ -234,19 +307,85 @@ export default ((input: PluginInput) => {
     return tokens >= 1000 ? `${(tokens / 1000).toFixed(1)}K` : `${tokens}`
   }
 
+  function compareVersions(a: string, b: string): number {
+    const parse = (v: string) => v.replace(/^v/, "").split(/[.-]/).map((part) => Number.parseInt(part, 10) || 0)
+    const left = parse(a)
+    const right = parse(b)
+    const len = Math.max(left.length, right.length)
+    for (let i = 0; i < len; i++) {
+      const diff = (left[i] ?? 0) - (right[i] ?? 0)
+      if (diff !== 0) return diff
+    }
+    return 0
+  }
+
+  async function fetchLatestVersion(): Promise<string | undefined> {
+    const res = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, {
+      headers: { accept: "application/json" },
+    })
+    if (!res.ok) return undefined
+    const data = await res.json() as { version?: string }
+    return data.version
+  }
+
+  async function checkForUpdate(): Promise<{ current: string; latest?: string; available: boolean }> {
+    const latest = await fetchLatestVersion()
+    return { current: PACKAGE_VERSION, latest, available: !!latest && compareVersions(latest, PACKAGE_VERSION) > 0 }
+  }
+
+  function clearPluginCache(): string[] {
+    const packagesDir = join(homedir(), ".cache", "opencode", "packages")
+    if (!existsSync(packagesDir)) return []
+
+    const removed: string[] = []
+    for (const entry of readdirSync(packagesDir)) {
+      if (entry !== PACKAGE_NAME && !entry.startsWith(`${PACKAGE_NAME}@`)) continue
+      const target = join(packagesDir, entry)
+      rmSync(target, { recursive: true, force: true })
+      removed.push(target)
+    }
+    return removed
+  }
+
+  function manualUpdateText(latest = "latest"): string {
+    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() {
+    try {
+      const info = await checkForUpdate()
+      if (!info.available || !info.latest) return
+      await (client as any).tui?.showToast?.({
+        body: {
+          title: "Raven update available",
+          message: `${PACKAGE_NAME} ${info.current} → ${info.latest}. Run /raven update, then restart opencode.`,
+          variant: "info",
+          duration: 10000,
+        },
+      })
+    } 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 || []
@@ -273,18 +412,20 @@ export default ((input: PluginInput) => {
       configInput.command = configInput.command || {}
       if (!configInput.command.raven) {
         configInput.command.raven = {
-          template: "Manage Raven: /raven on|off|model <name>|status",
+          template: "Manage Raven: /raven on|off|update|model <name>|status",
           description: "Toggle search interception or change Raven's model",
         }
       }
+
+      void notifyIfUpdateAvailable()
     },
 
     // 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()
@@ -303,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 } })
 
@@ -368,7 +511,7 @@ export default ((input: PluginInput) => {
     },
 
     // /raven on|off|model <name>|effort <value>|timeout <seconds>|stats|status
-    "command.execute.before"(input: any, output: any) {
+    async "command.execute.before"(input: any, output: any) {
       if (input.command !== "raven") return
       output.parts.length = 0
       const raw = input.arguments.trim()
@@ -384,6 +527,20 @@ export default ((input: PluginInput) => {
         output.parts.push({ type: "text", text: "Raven search interception disabled. All agents can use search tools directly." })
       } else if (arg === "stats") {
         output.parts.push({ type: "text", text: `Raven context processed:\n  This session: ${formatBytes(sessionBytes)} (~${formatTokens(sessionBytes)} tokens)\n  All time: ${formatBytes(totalBytes)} (~${formatTokens(totalBytes)} tokens)` })
+      } else if (arg === "update") {
+        try {
+          const info = await checkForUpdate()
+          if (!info.latest) {
+            output.parts.push({ type: "text", text: `Could not check npm for ${PACKAGE_NAME}. Try again later.\n\n${manualUpdateText()}` })
+          } else if (!info.available) {
+            output.parts.push({ type: "text", text: `Raven is up to date (${info.current}). Latest on npm: ${info.latest}.` })
+          } else {
+            const removed = clearPluginCache()
+            output.parts.push({ type: "text", text: `Raven update available: ${info.current} → ${info.latest}.\n\nCleared ${removed.length} opencode plugin cache entr${removed.length === 1 ? "y" : "ies"}. ${manualUpdateText(info.latest)}` })
+          }
+        } catch (err: any) {
+          output.parts.push({ type: "text", text: `Raven update check failed: ${err?.message ?? err}\n\n${manualUpdateText()}` })
+        }
       } else if (arg.startsWith("model ")) {
         const model = raw.slice(6).trim()
         if (!model) {
@@ -416,11 +573,15 @@ export default ((input: PluginInput) => {
         const model = config.model || fm.model || "(default)"
         const effort = config.reasoning_effort || fm.reasoning_effort || "(default)"
         const timeout = config.timeout ?? 180
-        output.parts.push({ type: "text", text: `Raven is ${enabled}. Model: ${model}. Reasoning: ${effort}. Timeout: ${timeout}s\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 timeout <seconds> — change raven_seek timeout\n  /raven stats   — show blocked calls and context saved` })
+        output.parts.push({ type: "text", text: `Raven is ${enabled}. Model: ${model}. Reasoning: ${effort}. Timeout: ${timeout}s\n\nCommands:\n  /raven on      — enable search interception\n  /raven off     — disable search interception\n  /raven update  — check npm, clear plugin cache if newer, then restart opencode\n  /raven model <name> — change Raven's model (requires restart)\n  /raven effort <value> — change Raven's reasoning effort (requires restart)\n  /raven timeout <seconds> — change raven_seek timeout\n  /raven stats   — show blocked calls and context saved` })
       }
     },
 
     "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
@@ -436,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>`
         }
       }
 
@@ -445,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))
       }
     },
 
@@ -457,4 +618,4 @@ export default ((input: PluginInput) => {
       }
     },
   }
-}) satisfies Plugin
+}) satisfies Plugin

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.4",
+  "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": {
@@ -31,4 +31,4 @@
   "engines": {
     "bun": ">=1.0.0"
   }
-}
+}