opencode-raven 2.2.1 → 2.3.0

package/raven-core.ts

@@ -0,0 +1,2682 @@
+import type { PluginInput } from "@opencode-ai/plugin"
+import type { tool as defineTool } from "@opencode-ai/plugin"
+import { z } from "zod"
+import { Client } from "@modelcontextprotocol/sdk/client/index.js"
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js"
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs"
+import { join } from "node:path"
+import { homedir, tmpdir } from "node:os"
+
+// ── Resolve paths relative to this package (works in node_modules/) ──
+const PKG_DIR = import.meta.dirname!
+
+// The v1 helper is an identity function. Keep schema construction independent of
+// either host SDK so a v2 install does not need the optional v1 peer at runtime.
+const tool = Object.assign(((definition) => definition) as typeof defineTool, { schema: z })
+
+const RAVEN_MD = join(PKG_DIR, "Raven.md")
+const RAVEN_MCP_MD = join(PKG_DIR, "RavenMcp.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"
+
+// ── Tools/MCPs that should be intercepted for non-Raven agents ──
+const DEFAULT_ROUTE_TOOLS = [
+  "grep",
+  "glob",
+  "webfetch",
+  "fetch",
+  "websearch",
+  "bash",
+]
+
+const DEFAULT_ROUTE_TOOL_KEYWORDS: string[] = []
+
+const DEFAULT_ON_DEMAND_MCP_SERVERS: Record<string, OnDemandMcpServer> = {
+  context7: {
+    enabled: true,
+    type: "remote",
+    url: "https://mcp.context7.com/mcp",
+    description: "Library/framework documentation lookup.",
+  },
+  exa: {
+    enabled: true,
+    type: "remote",
+    url: "https://mcp.exa.ai/mcp",
+    description: "Live web search and webpage fetching.",
+  },
+  grep_app: {
+    enabled: true,
+    type: "remote",
+    url: "https://mcp.grep.app",
+    description: "Public GitHub code search and real-world examples.",
+  },
+}
+
+const DEFAULT_ON_DEMAND_MCP_METADATA: Record<string, OnDemandMcpMetadata> = {
+  context7: {
+    autoGeneratedDescription: "Finds current library, framework, SDK, package, and API documentation; useful for implementation, configuration, and debugging with version-specific docs.",
+  },
+  exa: {
+    autoGeneratedDescription: "Searches the live web, fetches webpages, researches companies/products, and gathers current information from online sources.",
+  },
+  grep_app: {
+    autoGeneratedDescription: "Searches public GitHub repositories for real-world code examples, usage patterns, configuration snippets, and implementation references.",
+  },
+}
+
+const NEVER_ROUTE_TOOLS = new Set(["raven_seek", "raven_mcp", "raven_mcp_bridge", "task", "subtask", "subagent"])
+const RETIRED_DEFAULT_MODELS = new Set(["opencode/deepseek-v4-flash-free"])
+const MAX_TIMER_MS = 2_147_483_647
+const MAX_TIMEOUT_SECONDS = Math.floor(MAX_TIMER_MS / 1000)
+
+// ── 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)\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 stripShellComments(stripHeredocs(cmd)
+    .replace(/'[^']*'/g, "''")
+    .replace(/"[^"]*"/g, '""'))
+}
+
+function unquoteShellPayload(value: string): string {
+  const payload = value.trim()
+  const quote = payload[0]
+  return (quote === '"' || quote === "'") && payload.endsWith(quote)
+    ? payload.slice(1, -1)
+    : payload
+}
+
+function wrappedShellPayload(cmd: string): string | undefined {
+  const command = stripShellComments(stripHeredocs(cmd)).trim()
+  const match = command.match(/^(?:"([^"]+)"|'([^']+)'|(\S+))(?:\s+([\s\S]+))?$/)
+  if (!match) return undefined
+
+  const executable = (match[1] ?? match[2] ?? match[3]).replace(/\\/g, "/").split("/").pop()?.toLowerCase()
+  const rest = match[4] ?? ""
+  if (executable === "cmd" || executable === "cmd.exe") {
+    const payload = rest.match(/^(?:\/[dqs]\s+)*\/c\s+([\s\S]+)$/i)?.[1]
+    return payload === undefined ? undefined : unquoteShellPayload(payload)
+  }
+
+  if (["sh", "sh.exe", "bash", "bash.exe", "zsh", "zsh.exe", "dash", "dash.exe"].includes(executable ?? "")) {
+    const payload = rest.match(/^-[a-z]*c\s+([\s\S]+)$/i)?.[1]
+    return payload === undefined ? undefined : unquoteShellPayload(payload)
+  }
+
+  if (["powershell", "powershell.exe", "pwsh", "pwsh.exe"].includes(executable ?? "")) {
+    const payload = rest.match(/(?:^|\s)-(?:command|c)\s+([\s\S]+)$/i)?.[1]
+    if (payload === undefined) return undefined
+    const unquoted = unquoteShellPayload(payload)
+    return unquoted.replace(
+      /(^|(?:(?:&&|\|\||[;|\n{(])\s*))&\s+(?:"([^"]+)"|'([^']+)'|(\S+))/g,
+      (_match, prefix, doubleQuoted, singleQuoted, bare) => `${prefix}${doubleQuoted ?? singleQuoted ?? bare}`,
+    )
+  }
+
+  return undefined
+}
+
+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 wrapped = wrappedShellPayload(cmd)
+  if (wrapped !== undefined) return commandLooksLikeSearch(wrapped)
+
+  const stripped = stripQuotedContent(cmd)
+  const lower = stripped.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(stripped).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" && tool !== "shell") return false
+  return commandLooksLikeSearch(String(args?.command ?? ""))
+}
+
+// ── Config file shape ──
+interface OnDemandMcpToolInfo {
+  name: string
+  description?: string
+}
+
+interface BaseOnDemandMcpServer {
+  enabled?: boolean
+  timeout?: number
+  description?: string
+}
+
+interface OnDemandMcpMetadata {
+  autoGeneratedDescription?: string
+  autoGeneratedTools?: OnDemandMcpToolInfo[]
+  avoidedSchemaBytes?: number
+  status?: "pending" | "ready" | "failed"
+  lastError?: string
+  lastCheckedAt?: string
+}
+
+interface RemoteOnDemandMcpServer extends BaseOnDemandMcpServer {
+  type: "remote"
+  url: string
+  headers?: Record<string, string>
+}
+
+interface LocalOnDemandMcpServer extends BaseOnDemandMcpServer {
+  type: "local"
+  command: string[]
+  environment?: Record<string, string>
+  cwd?: string
+}
+
+type OnDemandMcpServer = RemoteOnDemandMcpServer | LocalOnDemandMcpServer
+type OnDemandMcpDescriptionDetail = "full" | "minimized"
+type RavenMcpOperation = "list_tools" | "call_tool" | "list_resources" | "read_resource" | "list_prompts" | "get_prompt"
+
+interface RavenSeekConfig {
+  model?: string
+  autoSelectedModel?: string
+  reasoning_effort?: string
+  instructions?: string
+  routeTools?: string[]
+  routeToolKeywords?: string[]
+  excludeAgents?: string[]
+  excludeTools?: string[]
+  timeout?: number
+}
+
+interface RavenMcpConfig {
+  model?: string
+  autoSelectedModel?: string
+  reasoning_effort?: string
+  instructions?: string
+  timeout?: number
+  descriptionDetail?: OnDemandMcpDescriptionDetail
+  onDemandMcpServers?: Record<string, OnDemandMcpServer>
+}
+
+interface RavenConfig {
+  raven_seek: RavenSeekConfig
+  raven_mcp: RavenMcpConfig
+  stats?: { bytes: number }
+}
+
+// ── Parse Raven.md frontmatter ──
+const ravenMd = readFileSync(RAVEN_MD, "utf-8")
+const { frontmatter: fm, prompt: ravenPrompt } = parseRavenMd(ravenMd)
+const ravenMcpMd = readFileSync(RAVEN_MCP_MD, "utf-8")
+const { frontmatter: mcpFm, prompt: ravenMcpPrompt } = parseRavenMd(ravenMcpMd)
+
+const DEFAULT_CONFIG: RavenConfig = {
+  raven_seek: {
+    model: fm.model,
+    reasoning_effort: fm.reasoning_effort,
+    instructions: "",
+    routeTools: DEFAULT_ROUTE_TOOLS,
+    routeToolKeywords: DEFAULT_ROUTE_TOOL_KEYWORDS,
+    excludeAgents: [],
+    excludeTools: [],
+    timeout: 600,
+  },
+  raven_mcp: {
+    model: mcpFm.model,
+    reasoning_effort: mcpFm.reasoning_effort,
+    instructions: "",
+    timeout: 600,
+    descriptionDetail: "full",
+    onDemandMcpServers: DEFAULT_ON_DEMAND_MCP_SERVERS,
+  },
+}
+
+function parseRavenMd(raw: string): { frontmatter: Record<string, any>; prompt: string } {
+  const parts = raw.split("---")
+  if (parts.length < 3) {
+    throw new Error("Raven.md missing frontmatter (--- delimiters)")
+  }
+  return { frontmatter: parseYaml(parts[1]), prompt: parts.slice(2).join("---").trim() }
+}
+
+// ── Minimal YAML parser (handles the structure used in Raven.md) ──
+function parseYaml(yaml: string): Record<string, any> {
+  const lines = yaml.split("\n")
+  const root: Record<string, any> = {}
+  const stack: Array<{ obj: Record<string, any>; indent: number }> = [
+    { obj: root, indent: -1 },
+  ]
+
+  for (const rawLine of lines) {
+    const line = rawLine.trimEnd()
+    if (!line.trim() || line.trim().startsWith("#")) continue
+
+    const indent = line.search(/\S/)
+    const colonIdx = line.indexOf(":")
+    if (colonIdx === -1) continue
+
+    const rawKey = line.slice(indent, colonIdx).trim()
+    const key =
+      (rawKey.startsWith('"') && rawKey.endsWith('"')) ||
+      (rawKey.startsWith("'") && rawKey.endsWith("'"))
+        ? rawKey.slice(1, -1)
+        : rawKey
+
+    const rawValue = line.slice(colonIdx + 1).trim()
+
+    while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
+      stack.pop()
+    }
+    const current = stack[stack.length - 1].obj
+
+    if (!rawValue) {
+      const nested: Record<string, any> = {}
+      current[key] = nested
+      stack.push({ obj: nested, indent })
+    } else {
+      let value: any = rawValue
+      if (
+        (value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))
+      ) {
+        value = value.slice(1, -1)
+      } else if (value === "true") {
+        value = true
+      } else if (value === "false") {
+        value = false
+      } else if (/^\d+$/.test(value)) {
+        value = parseInt(value, 10)
+      }
+      current[key] = value
+    }
+  }
+
+  return root
+}
+
+// ── Move unknown frontmatter fields into options ──
+const KNOWN_KEYS = new Set([
+  "description", "mode", "hidden", "model", "permission",
+  "prompt", "name", "color", "steps", "disable",
+  "temperature", "top_p", "variant",
+])
+
+function extractOptions(fm: Record<string, any>): Record<string, any> {
+  const options: Record<string, any> = {}
+  for (const key of Object.keys(fm)) {
+    if (!KNOWN_KEYS.has(key)) options[key] = fm[key]
+  }
+  return options
+}
+
+function uniqueStrings(value: unknown, fallback: string[] = []): string[] {
+  const source = Array.isArray(value) ? value : fallback
+  return [...new Set(source.filter((item) => typeof item === "string" && item.trim()).map((item) => item.trim()))]
+}
+
+function cloneOnDemandMcpServers(value: Record<string, OnDemandMcpServer>): Record<string, OnDemandMcpServer> {
+  return JSON.parse(JSON.stringify(value))
+}
+
+function cloneOnDemandMcpMetadata(value: Record<string, OnDemandMcpMetadata>): Record<string, OnDemandMcpMetadata> {
+  return JSON.parse(JSON.stringify(value))
+}
+
+function normalizeToolInfo(value: unknown): OnDemandMcpToolInfo[] | undefined {
+  if (!Array.isArray(value)) return undefined
+  const tools = value
+    .filter((item) => item && typeof item === "object" && typeof item.name === "string" && item.name.trim())
+    .map((item) => ({
+      name: item.name.trim(),
+      ...(typeof item.description === "string" && item.description.trim() ? { description: item.description.trim() } : {}),
+    }))
+  return tools.length ? tools : undefined
+}
+
+function normalizeStringRecord(value: unknown): Record<string, string> | undefined {
+  if (!value || typeof value !== "object") return undefined
+  const entries = Object.entries(value).filter((entry): entry is [string, string] => typeof entry[1] === "string")
+  return entries.length ? Object.fromEntries(entries) : undefined
+}
+
+function normalizeOnDemandMcpServer(value: unknown): OnDemandMcpServer | undefined {
+  if (!value || typeof value !== "object") return undefined
+  const source = value as Record<string, any>
+  const base = {
+    enabled: source.enabled !== false,
+    ...(typeof source.timeout === "number" && Number.isFinite(source.timeout) && source.timeout >= 1 && source.timeout <= MAX_TIMER_MS
+      ? { timeout: Math.floor(source.timeout) }
+      : {}),
+    ...(typeof source.description === "string" && source.description.trim() ? { description: source.description.trim() } : {}),
+  }
+
+  if (source.type === "local") {
+    const commandParts = Array.isArray(source.command)
+      ? source.command.filter((arg: unknown): arg is string => typeof arg === "string" && !!arg.trim())
+      : []
+    if (!commandParts.length) return undefined
+    const environment = normalizeStringRecord(source.environment)
+    return {
+      ...base,
+      type: "local",
+      command: commandParts,
+      ...(environment ? { environment } : {}),
+      ...(typeof source.cwd === "string" && source.cwd.trim() ? { cwd: source.cwd.trim() } : {}),
+    }
+  }
+
+  if (source.type === "remote" || typeof source.url === "string") {
+    if (typeof source.url !== "string" || !source.url.trim()) return undefined
+    const headers = normalizeStringRecord(source.headers)
+    return {
+      ...base,
+      type: "remote",
+      url: source.url.trim(),
+      ...(headers ? { headers } : {}),
+    }
+  }
+
+  return undefined
+}
+
+function normalizeOnDemandMcpMetadata(value: unknown, fallback: Record<string, OnDemandMcpMetadata> = {}): Record<string, OnDemandMcpMetadata> {
+  const source = value && typeof value === "object" ? value as Record<string, any> : fallback
+  const result: Record<string, OnDemandMcpMetadata> = {}
+  for (const [key, raw] of Object.entries(source)) {
+    if (!key.trim() || !raw || typeof raw !== "object") continue
+    const item = raw as Record<string, unknown>
+    const metadata: OnDemandMcpMetadata = {}
+    if (typeof item.autoGeneratedDescription === "string" && item.autoGeneratedDescription.trim()) {
+      metadata.autoGeneratedDescription = item.autoGeneratedDescription.trim()
+    }
+    const tools = normalizeToolInfo(item.autoGeneratedTools)
+    if (tools) metadata.autoGeneratedTools = tools
+    if (typeof item.avoidedSchemaBytes === "number" && Number.isFinite(item.avoidedSchemaBytes) && item.avoidedSchemaBytes >= 0) {
+      metadata.avoidedSchemaBytes = Math.round(item.avoidedSchemaBytes)
+    }
+    if (item.status === "pending" || item.status === "ready" || item.status === "failed") metadata.status = item.status
+    if (typeof item.lastError === "string" && item.lastError.trim()) metadata.lastError = item.lastError.trim()
+    if (typeof item.lastCheckedAt === "string" && item.lastCheckedAt.trim()) metadata.lastCheckedAt = item.lastCheckedAt.trim()
+    if (metadata.autoGeneratedDescription || metadata.autoGeneratedTools?.length || metadata.avoidedSchemaBytes || metadata.status || metadata.lastError || metadata.lastCheckedAt) result[key.trim()] = metadata
+  }
+  return result
+}
+
+function normalizeOnDemandMcpServers(value: unknown, fallback: Record<string, OnDemandMcpServer> = {}): Record<string, OnDemandMcpServer> {
+  const source = value && typeof value === "object" ? value as Record<string, unknown> : fallback
+  const result: Record<string, OnDemandMcpServer> = {}
+  for (const [key, raw] of Object.entries(source)) {
+    if (!key.trim()) continue
+    const server = normalizeOnDemandMcpServer(raw)
+    if (server) result[key.trim()] = server
+  }
+  return result
+}
+
+// ── Plugin ──
+export default (async (input: Pick<PluginInput, "client" | "directory"> & { project: Pick<PluginInput["project"], "id"> }, host: "v1" | "v2" = "v1") => {
+  const client = input.client
+
+  // Raven state lives under the global opencode config directory.
+  const opencodeConfigDir = join(homedir(), ".config", "opencode")
+  const ravenConfigDir = join(opencodeConfigDir, "opencode-raven")
+  const configFile = join(ravenConfigDir, "raven-config.json")
+  const mcpMetadataFile = join(ravenConfigDir, "autogenerated-on-demand-mcp-metadata.json")
+  const dynamicGuidanceFile = join(ravenConfigDir, "autogenerated-on-demand-guidance.md")
+
+  function normalizeConfig(raw: any): RavenConfig {
+    const source = raw && typeof raw === "object" ? raw : {}
+    const seekSource = source.raven_seek && typeof source.raven_seek === "object" ? source.raven_seek : source
+    const mcpSource = source.raven_mcp && typeof source.raven_mcp === "object" ? source.raven_mcp : source
+    const legacyInstructions = typeof source.ravenInstructions === "string" ? source.ravenInstructions : undefined
+    const normalized: RavenConfig = {
+      raven_seek: {
+        model: typeof seekSource.model === "string" ? seekSource.model : DEFAULT_CONFIG.raven_seek.model,
+        autoSelectedModel: typeof seekSource.autoSelectedModel === "string" ? seekSource.autoSelectedModel : undefined,
+        reasoning_effort: typeof seekSource.reasoning_effort === "string" ? seekSource.reasoning_effort : DEFAULT_CONFIG.raven_seek.reasoning_effort,
+        instructions: typeof seekSource.instructions === "string" ? seekSource.instructions : legacyInstructions ?? "",
+        routeTools: uniqueStrings(seekSource.routeTools, DEFAULT_ROUTE_TOOLS),
+        routeToolKeywords: uniqueStrings(seekSource.routeToolKeywords, DEFAULT_ROUTE_TOOL_KEYWORDS),
+        excludeAgents: uniqueStrings(seekSource.excludeAgents),
+        excludeTools: uniqueStrings(seekSource.excludeTools),
+        timeout: typeof seekSource.timeout === "number" && Number.isFinite(seekSource.timeout)
+          && seekSource.timeout >= 10 && seekSource.timeout <= MAX_TIMEOUT_SECONDS
+          ? Math.floor(seekSource.timeout)
+          : DEFAULT_CONFIG.raven_seek.timeout,
+      },
+      raven_mcp: {
+        model: typeof mcpSource.model === "string" ? mcpSource.model : DEFAULT_CONFIG.raven_mcp.model,
+        autoSelectedModel: typeof mcpSource.autoSelectedModel === "string" ? mcpSource.autoSelectedModel : undefined,
+        reasoning_effort: typeof mcpSource.reasoning_effort === "string" ? mcpSource.reasoning_effort : DEFAULT_CONFIG.raven_mcp.reasoning_effort,
+        instructions: typeof mcpSource.instructions === "string" ? mcpSource.instructions : legacyInstructions ?? "",
+        timeout: typeof mcpSource.timeout === "number" && Number.isFinite(mcpSource.timeout)
+          && mcpSource.timeout >= 10 && mcpSource.timeout <= MAX_TIMEOUT_SECONDS
+          ? Math.floor(mcpSource.timeout)
+          : DEFAULT_CONFIG.raven_mcp.timeout,
+        descriptionDetail: mcpSource.descriptionDetail === "minimized"
+          ? "minimized"
+          : mcpSource.descriptionDetail === "full"
+            ? "full"
+            : source.onDemandMcpDescriptionDetail === "minimized" ? "minimized" : "full",
+        onDemandMcpServers: mcpSource.onDemandMcpServers === undefined
+          ? cloneOnDemandMcpServers(DEFAULT_ON_DEMAND_MCP_SERVERS)
+          : normalizeOnDemandMcpServers(mcpSource.onDemandMcpServers),
+      },
+    }
+    normalized.stats = source.stats && typeof source.stats === "object"
+      && typeof source.stats.bytes === "number" && Number.isFinite(source.stats.bytes) && source.stats.bytes >= 0
+      ? { bytes: Math.round(source.stats.bytes) }
+      : undefined
+
+    return normalized
+  }
+
+  function loadConfig(): RavenConfig {
+    if (existsSync(configFile)) {
+      try {
+        const raw = JSON.parse(readFileSync(configFile, "utf-8"))
+        const normalized = normalizeConfig(raw)
+        if (!raw.raven_seek || !raw.raven_mcp) writeConfig(normalized)
+        return normalized
+      } catch {
+        // Preserve malformed or partially-written config so the user can repair it.
+        return { ...DEFAULT_CONFIG }
+      }
+    }
+    // Auto-create config file with defaults on first run
+    writeConfig(DEFAULT_CONFIG)
+    return { ...DEFAULT_CONFIG }
+  }
+
+  function writeConfig(config: RavenConfig) {
+    try {
+      mkdirSync(ravenConfigDir, { recursive: true })
+      writeFileSync(configFile, JSON.stringify(config, null, 2) + "\n")
+    } catch { /* non-fatal: config changes remain in-session */ }
+  }
+
+  function loadMcpMetadata(): Record<string, OnDemandMcpMetadata> {
+    const defaults = cloneOnDemandMcpMetadata(DEFAULT_ON_DEMAND_MCP_METADATA)
+    try {
+      if (existsSync(mcpMetadataFile)) {
+        return { ...defaults, ...normalizeOnDemandMcpMetadata(JSON.parse(readFileSync(mcpMetadataFile, "utf-8"))) }
+      }
+    } catch { /* ignore corruption, use defaults */ }
+    saveMcpMetadata(defaults)
+    return defaults
+  }
+
+  function saveMcpMetadata(metadata: Record<string, OnDemandMcpMetadata>) {
+    try {
+      mkdirSync(ravenConfigDir, { recursive: true })
+      writeFileSync(mcpMetadataFile, JSON.stringify(metadata, null, 2) + "\n")
+    } catch { /* non-fatal: generated metadata can be refreshed */ }
+  }
+
+  function saveDynamicGuidance() {
+    try {
+      mkdirSync(ravenConfigDir, { recursive: true })
+      writeFileSync(dynamicGuidanceFile, `## Raven on-demand MCP capabilities\n\n${onDemandMcpGuidance("delegate", dynamicGuidanceMcpOrder())}\n`, "utf-8")
+    } catch { /* non-fatal: guidance still exists in tool/subagent paths */ }
+  }
+
+  let config = loadConfig()
+  let modelDiscoveryError: string | undefined
+
+  function updateConfig(update: Partial<RavenConfig> | ((latest: RavenConfig) => Partial<RavenConfig>)): RavenConfig {
+    try {
+      const raw = existsSync(configFile) ? JSON.parse(readFileSync(configFile, "utf-8")) : config
+      const latest = normalizeConfig(raw)
+      const patch = typeof update === "function" ? update(latest) : update
+      config = normalizeConfig({
+        ...latest,
+        ...patch,
+        raven_seek: { ...latest.raven_seek, ...patch.raven_seek },
+        raven_mcp: { ...latest.raven_mcp, ...patch.raven_mcp },
+      })
+      writeConfig(config)
+    } catch {
+      // Keep malformed or partially-written external edits intact instead of replacing them.
+      const patch = typeof update === "function" ? update(config) : update
+      config = normalizeConfig({
+        ...config,
+        ...patch,
+        raven_seek: { ...config.raven_seek, ...patch.raven_seek },
+        raven_mcp: { ...config.raven_mcp, ...patch.raven_mcp },
+      })
+    }
+    return config
+  }
+
+  function modelsNeedingDiscovery(): boolean {
+    return [config.raven_seek, config.raven_mcp].some((section) =>
+      !section.model || RETIRED_DEFAULT_MODELS.has(section.model) || section.autoSelectedModel === section.model
+    )
+  }
+
+  function freeOpenCodeModels(providers: any[], connected?: string[]): string[] {
+    const connectedProviders = Array.isArray(connected) ? new Set(connected.map((id) => String(id).toLowerCase())) : undefined
+    const candidates: Array<{ id: string; status: number; released: number; context: number }> = []
+    for (const provider of providers) {
+      if (String(provider?.id ?? "").toLowerCase() !== "opencode") continue
+      if (connectedProviders && !connectedProviders.has("opencode")) continue
+      for (const [key, model] of Object.entries(provider?.models ?? {}) as Array<[string, any]>) {
+        const id = String(model?.id ?? key).trim()
+        const cost = model?.cost
+        const free = (Number(cost?.input) === 0 && Number(cost?.output) === 0) || /(?:^|-)free$/i.test(id)
+        const toolCall = model?.tool_call ?? model?.capabilities?.toolcall
+        if (!id || !free || toolCall !== true || model?.status === "deprecated") continue
+        const fullId = id.includes("/") ? id : `opencode/${id}`
+        const status = model?.status === "active" ? 3 : model?.status === "beta" || !model?.status ? 2 : 1
+        const released = Date.parse(model?.release_date ?? model?.releaseDate ?? "") || 0
+        const context = Number(model?.limit?.context) || 0
+        candidates.push({ id: fullId, status, released, context })
+      }
+    }
+    candidates.sort((left, right) =>
+      right.status - left.status || right.released - left.released || right.context - left.context || left.id.localeCompare(right.id)
+    )
+    return [...new Set(candidates.map((candidate) => candidate.id))]
+  }
+
+  async function discoverFreeOpenCodeModels(): Promise<string[] | undefined> {
+    modelDiscoveryError = undefined
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), 3000)
+    let lastError: unknown
+    try {
+      if ((client as any).provider?.list) {
+        try {
+          const response = await (client as any).provider.list({ query: { directory: input.directory }, signal: controller.signal })
+          const data = response?.data ?? response
+          if (Array.isArray(data?.all)) return freeOpenCodeModels(data.all, data.connected)
+        } catch (error) {
+          lastError = error
+        }
+      }
+      if ((client as any).config?.providers) {
+        try {
+          const response = await (client as any).config.providers({ query: { directory: input.directory }, signal: controller.signal })
+          const data = response?.data ?? response
+          if (Array.isArray(data?.providers)) return freeOpenCodeModels(data.providers)
+        } catch (error) {
+          lastError = error
+        }
+      }
+      modelDiscoveryError = lastError ? truncateText((lastError as any)?.message ?? lastError, 240) : "OpenCode's provider catalog was unavailable"
+      return undefined
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
+  async function ensureRavenModels(): Promise<boolean> {
+    if (!modelsNeedingDiscovery()) return false
+    const available = await discoverFreeOpenCodeModels()
+    const availableSet = new Set(available ?? [])
+    const selected = available?.[0]
+
+    function resolve(section: RavenSeekConfig | RavenMcpConfig) {
+      const current = section.model
+      const retired = !!current && RETIRED_DEFAULT_MODELS.has(current)
+      const managed = !!current && section.autoSelectedModel === current
+      if (available === undefined) {
+        return retired ? { model: undefined, autoSelectedModel: undefined } : { model: current, autoSelectedModel: section.autoSelectedModel }
+      }
+      if (!current || retired || (managed && !availableSet.has(current))) {
+        return { model: selected, autoSelectedModel: selected }
+      }
+      return { model: current, autoSelectedModel: section.autoSelectedModel }
+    }
+
+    const seek = resolve(config.raven_seek)
+    const mcp = resolve(config.raven_mcp)
+    if (seek.model !== config.raven_seek.model || seek.autoSelectedModel !== config.raven_seek.autoSelectedModel
+      || mcp.model !== config.raven_mcp.model || mcp.autoSelectedModel !== config.raven_mcp.autoSelectedModel) {
+      updateConfig({ raven_seek: seek, raven_mcp: mcp })
+      return true
+    }
+    return false
+  }
+
+  function clearRetiredDefaults() {
+    const seekRetired = !!config.raven_seek.model && RETIRED_DEFAULT_MODELS.has(config.raven_seek.model)
+    const mcpRetired = !!config.raven_mcp.model && RETIRED_DEFAULT_MODELS.has(config.raven_mcp.model)
+    if (!seekRetired && !mcpRetired) return
+    updateConfig({
+      ...(seekRetired ? { raven_seek: { model: undefined, autoSelectedModel: undefined } } : {}),
+      ...(mcpRetired ? { raven_mcp: { model: undefined, autoSelectedModel: undefined } } : {}),
+    })
+  }
+
+  clearRetiredDefaults()
+  const activeSeekModel = config.raven_seek.model
+  const activeMcpModel = config.raven_mcp.model
+  let modelRefreshPending = modelsNeedingDiscovery()
+  let modelRefreshPromise: Promise<void> | undefined
+
+  let mcpMetadata = loadMcpMetadata()
+  type DelegationKind = "seek" | "mcp"
+  const ravenSessions = new Set<string>()
+  const ravenSessionKinds = new Map<string, DelegationKind>()
+  const activeRavenPrompts = new Set<string>()
+  const ravenTaskCalls = new Set<string>()
+  const sessionAgents = new Map<string, string>()
+  const ravenSessionParents = new Map<string, string>()
+  const ravenErrorWaiters = new Map<string, (error: Error) => void>()
+  const ravenProgressWaiters = new Map<string, () => void>()
+  let globalMcpServers: string[] = []
+  let duplicateMcpServers: string[] = []
+  let updateInfo: { current: string; latest?: string; available: boolean } | undefined
+  let updateCheckPromise: Promise<{ current: string; latest?: string; available: boolean }> | undefined
+  let updateToastPending = false
+  let mcpFailureToastPending = false
+  let duplicateMcpToastPending = false
+  let modelSetupToastPending = false
+  let mcpRefreshScheduled = false
+  let mcpRefreshPromise: Promise<{ refreshed: string[]; failed: string[] }> | undefined
+  let mcpRefreshQueue: Promise<unknown> = Promise.resolve()
+  const mcpRefreshControllers = new Set<AbortController>()
+  let lastNotifiedMcpFailureKey = ""
+  const ravenProviderIssues: Partial<Record<DelegationKind, string>> = {}
+
+  async function refreshModelsIfPending() {
+    if (modelRefreshPromise) return modelRefreshPromise
+    if (!modelRefreshPending) return
+    modelRefreshPending = false
+    modelRefreshPromise = ensureRavenModels().then(() => {
+      modelSetupToastPending = !!modelSetupInstructions()
+    })
+    return modelRefreshPromise
+  }
+
+  // Replace generated instructions from older releases before OpenCode consumes them.
+  saveDynamicGuidance()
+  resetOnDemandMcpRuntimeStatuses()
+
+  function resetOnDemandMcpRuntimeStatuses() {
+    let changed = false
+    for (const [name] of activeOnDemandMcpEntries()) {
+      const metadata = mcpMetadata[name] ?? {}
+      if (metadata.status !== "pending" || metadata.lastError || metadata.lastCheckedAt) {
+        mcpMetadata[name] = { ...metadata, status: "pending" }
+        delete mcpMetadata[name].lastError
+        delete mcpMetadata[name].lastCheckedAt
+        changed = true
+      }
+    }
+    if (changed) saveMcpMetadata(mcpMetadata)
+  }
+
+  // ── Check if an agent is excluded from Raven enforcement (case-insensitive) ──
+  function isExcluded(agent: string | undefined): boolean {
+    if (!agent || !config.raven_seek.excludeAgents?.length) return false
+    const lower = agent.toLowerCase()
+    return config.raven_seek.excludeAgents.some((a) => a.toLowerCase() === lower)
+  }
+
+  function isRouteConfigured(toolName: string): boolean {
+    if (!modelOperational("seek")) 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()}_`))
+  }
+
+  function compactArgs(value: any): any {
+    if (Array.isArray(value)) {
+      return value.map(compactArgs).filter((item) => item !== undefined)
+    }
+    if (!value || typeof value !== "object") return value
+    const result: Record<string, any> = {}
+    for (const [key, raw] of Object.entries(value)) {
+      const item = compactArgs(raw)
+      if (item === undefined || item === null || item === "") continue
+      if (Array.isArray(item) && item.length === 0) continue
+      if (typeof item === "object" && !Array.isArray(item) && Object.keys(item).length === 0) continue
+      result[key] = item
+    }
+    return result
+  }
+
+  function attemptedQuery(tool: string, args: any): string {
+    const compact = compactArgs(args)
+    if (!compact || typeof compact !== "object") return `${tool}: ${JSON.stringify(compact)}`
+    const direct = compact.query ?? compact.pattern ?? compact.url ?? compact.urls ?? compact.command ?? compact.path ?? compact.filePath
+    const value = direct !== undefined ? direct : compact
+    const text = typeof value === "string" ? value : JSON.stringify(value)
+    const query = value === compact ? `${tool} ${text}` : `${tool}: ${text}`
+    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 ravenRecoveryInstructions(kind: DelegationKind): string {
+    const command = kind === "mcp" ? "/raven mcp model <provider/model>" : "/raven seek model <provider/model>"
+    return `Stop trying Raven-routed tools or MCPs for this request. Inform the user that Raven cannot run until its model/provider is changed or fixed.
+
+Tell the user to switch Raven's model with:
+  ${command}
+
+Example:
+  ${command.replace("<provider/model>", "openai/gpt-5.5")}
+
+Then restart opencode for the model change to take effect. If the task can be completed without Raven, continue without routed tools and clearly mention what could not be checked.`
+  }
+
+  function routeSummary(): string {
+    if (!modelOperational("seek")) return "Raven routing: inactive until the configured Search 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)"
+    const duplicates = duplicateMcpServers.length ? `\n  Duplicate MCP config: ${duplicateMcpServers.join(", ")} (configured globally and on-demand)` : ""
+    return `Raven routing:\n  Routed tools: ${tools}\n  Routed global MCPs: ${mcps}\n  Routed tool keywords: ${keywords}${duplicates}`
+  }
+
+  function modelSetupInstructions(kind?: DelegationKind): string {
+    const unavailable = [
+      ...(!modelOperational("seek") && kind !== "mcp" ? ["seek"] : []),
+      ...(!modelOperational("mcp") && kind !== "seek" ? ["mcp"] : []),
+    ] as DelegationKind[]
+    if (!unavailable.length) return ""
+    const pendingRestart = unavailable.filter((item) => item === "seek" ? !!config.raven_seek.model : !!config.raven_mcp.model)
+    const missing = unavailable.filter((item) => item === "seek" ? !config.raven_seek.model : !config.raven_mcp.model)
+    const lines: string[] = []
+    if (pendingRestart.length) {
+      const models = pendingRestart.map((item) => `${item === "seek" ? "Search" : "MCP"}: ${item === "seek" ? modelLabel(config.raven_seek) : modelLabel(config.raven_mcp)}`)
+      lines.push(`Raven model update ready (${models.join(", ")}). Restart OpenCode to load it.`)
+    }
+    if (!missing.length) return lines.join("\n")
+    const reason = modelDiscoveryError
+      ? `Automatic free-model detection failed: ${modelDiscoveryError}.`
+      : "No connected, zero-cost OpenCode model with tool support was detected."
+    const commands = missing.map((item) => item === "seek"
+      ? "  /raven seek model <provider/model>"
+      : "  /raven mcp model <provider/model>")
+    lines.push(`Raven setup required. ${reason}\nOpen OpenCode's model picker to choose an available model, then run:\n${commands.join("\n")}\nRestart OpenCode afterward. To retry automatic detection, replace <provider/model> with auto.`)
+    return lines.join("\n\n")
+  }
+
+  function modelOperational(kind: DelegationKind): boolean {
+    const active = kind === "seek" ? activeSeekModel : activeMcpModel
+    const configured = kind === "seek" ? config.raven_seek.model : config.raven_mcp.model
+    return !!active && active === configured
+  }
+
+  function modelLabel(section: RavenSeekConfig | RavenMcpConfig): string {
+    if (!section.model) return "(not configured)"
+    return section.autoSelectedModel === section.model ? `${section.model} (auto)` : section.model
+  }
+
+  function mcpSummary(): string {
+    const buckets = onDemandMcpStatusBuckets()
+    const total = buckets.loaded.length + buckets.failed.length + buckets.pending.length
+    if (!total) return `Raven on-demand MCPs (always behind Raven): none configured.\n  Guidance detail: ${config.raven_mcp.descriptionDetail ?? "full"}`
+    const lines = [
+      "Raven on-demand MCPs (always behind Raven):",
+      `  Loaded: ${buckets.loaded.length ? buckets.loaded.join(", ") : "none"}`,
+      `  Failed: ${buckets.failed.length ? buckets.failed.join(", ") : "none"}`,
+      `  Pending: ${buckets.pending.length ? buckets.pending.join(", ") : "none"}`,
+      `  Guidance detail: ${config.raven_mcp.descriptionDetail ?? "full"}`,
+    ]
+    return lines.join("\n")
+  }
+
+  function ravenAgentPrompt(): string {
+    const extra = config.raven_seek.instructions?.trim()
+    const prompt = ravenPrompt
+    return extra ? `${prompt}\n\nAdditional user instructions:\n${extra}` : prompt
+  }
+
+  function ravenMcpAgentPrompt(): string {
+    const extra = config.raven_mcp.instructions?.trim()
+    const onDemand = onDemandMcpGuidance("raven")
+    const prompt = `${ravenMcpPrompt}\n\nOn-demand MCP guidance:\n${onDemand}`
+    return extra ? `${prompt}\n\nAdditional user instructions:\n${extra}` : prompt
+  }
+
+  function compactText(value: unknown): string {
+    return String(value ?? "").replace(/\s+/g, " ").trim()
+  }
+
+  function truncateText(value: unknown, max = 240): string {
+    const text = compactText(value)
+    return text.length > max ? `${text.slice(0, Math.max(0, max - 3))}...` : text
+  }
+
+  function dynamicGuidanceMcpOrder(): string[] | undefined {
+    try {
+      if (!existsSync(dynamicGuidanceFile)) return undefined
+      const names: string[] = []
+      for (const line of readFileSync(dynamicGuidanceFile, "utf-8").split("\n")) {
+        const name = line.match(/^-\s+([^:]+):/)?.[1]?.trim()
+        if (name && !names.includes(name)) names.push(name)
+      }
+      return names
+    } catch {
+      return undefined
+    }
+  }
+
+  function orderedOnDemandMcpEntries(entries: [string, OnDemandMcpServer][], preferredOrder?: string[]): [string, OnDemandMcpServer][] {
+    if (!preferredOrder?.length) return entries
+    const order = new Map(preferredOrder.map((name, index) => [name.toLowerCase(), index]))
+    const existing = entries
+      .filter(([name]) => order.has(name.toLowerCase()))
+      .sort(([left], [right]) => order.get(left.toLowerCase())! - order.get(right.toLowerCase())!)
+    const added = entries.filter(([name]) => !order.has(name.toLowerCase()))
+    return [...existing, ...added]
+  }
+
+  function firstSentenceText(value: unknown): string {
+    const text = compactText(value)
+    const period = text.indexOf(".")
+    return period === -1 ? text : text.slice(0, period + 1)
+  }
+
+  function onDemandMcpGuidance(target: "delegate" | "raven" = "delegate", preferredOrder?: string[]): string {
+    const servers = config.raven_mcp.onDemandMcpServers ?? {}
+    const activeEntries = activeOnDemandMcpEntries()
+    const entries = orderedOnDemandMcpEntries(
+      target === "raven"
+        ? activeEntries
+        : activeEntries.filter(([name]) => onDemandMcpRuntimeStatus(name) === "ready"),
+      preferredOrder,
+    )
+    if (!Object.keys(servers).length) return "No on-demand MCPs are configured."
+    if (!activeEntries.length) return "No enabled on-demand MCPs are configured."
+    if (!entries.length) return "No loaded on-demand MCPs are available."
+
+    const detail = config.raven_mcp.descriptionDetail ?? "full"
+    const lines = entries.map(([name, server]) => {
+      const metadata = mcpMetadata[name] ?? {}
+      const userDescription = firstSentenceText(server.description)
+      const generated = firstSentenceText(metadata.autoGeneratedDescription)
+      const parts = [userDescription, generated ? `Discovered capabilities: ${generated}` : ""].filter(Boolean)
+      const summary = parts.length ? parts.join(" ") : "Description discovery pending."
+      if (detail === "minimized" || !metadata.autoGeneratedTools?.length) return `- ${name}: ${summary}`
+      const tools = metadata.autoGeneratedTools
+        .map((item) => `${item.name}${item.description ? ` - ${firstSentenceText(item.description)}` : ""}`)
+        .join("; ")
+      return `- ${name}: ${summary} Tools: ${tools}`
+    })
+    if (target === "raven") {
+      return `Use raven_mcp_bridge for these on-demand MCP capabilities:\n${lines.join("\n")}`
+    }
+    return `Non-Raven agents can use these on-demand MCP capabilities through the public raven_mcp delegator. Use raven_mcp for matching requests and include the target MCP server and likely capability when obvious. The raven-mcp agent itself must call raven_mcp_bridge directly instead:\n${lines.join("\n")}`
+  }
+
+  function resolveEnvPlaceholders(value: string): string {
+    return value.replace(/\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name) => {
+      const envValue = process.env[name]
+      if (envValue === undefined) throw new Error(`Missing environment variable ${name}`)
+      return envValue
+    })
+  }
+
+  function resolveStringRecord(value: Record<string, string> | undefined): Record<string, string> | undefined {
+    if (!value) return undefined
+    const result: Record<string, string> = {}
+    for (const [key, raw] of Object.entries(value)) {
+      result[key] = resolveEnvPlaceholders(raw)
+    }
+    return result
+  }
+
+  function cleanProcessEnv(): Record<string, string> {
+    const result: Record<string, string> = {}
+    for (const [key, value] of Object.entries(process.env)) {
+      if (typeof value === "string") result[key] = value
+    }
+    return result
+  }
+
+  function providerErrorMessage(error: any): string {
+    const name = String(error?.name ?? "")
+    const data = error?.data && typeof error.data === "object" ? error.data : {}
+    const status = typeof data.statusCode === "number" ? ` HTTP ${data.statusCode}.` : ""
+    const body = typeof data.responseBody === "string" && data.responseBody.trim() ? ` ${truncateText(data.responseBody, 500)}` : ""
+    const message = String(data.message ?? error?.message ?? error ?? "Unknown provider error")
+    return `Raven provider/API error${name ? ` (${name})` : ""}.${status} ${message}${body}`.trim()
+  }
+
+  function waitForRavenProviderError(sessionId: string): Promise<never> {
+    return new Promise((_resolve, reject) => {
+      ravenErrorWaiters.set(sessionId, reject)
+    })
+  }
+
+  function waitForRavenFirstProgress(sessionId: string, ms: number): Promise<never> {
+    return new Promise((_resolve, reject) => {
+      const timer = setTimeout(() => {
+        ravenProgressWaiters.delete(sessionId)
+        reject(new Error(`Raven did not produce an initial response within ${Math.round(ms / 1000)}s. If the Raven provider showed a retry dialog, this is likely an auth/quota/subscription issue. Check the Raven subagent/provider account, or retry after switching Raven to a working model.`))
+      }, ms)
+      ravenProgressWaiters.set(sessionId, () => {
+        clearTimeout(timer)
+        ravenProgressWaiters.delete(sessionId)
+      })
+    })
+  }
+
+  function reportRavenProviderError(sessionId: string, error: any) {
+    const waiter = ravenErrorWaiters.get(sessionId)
+    if (!waiter) return
+    waiter(new Error(providerErrorMessage(error)))
+  }
+
+  function reportRavenProgress(sessionId: string) {
+    ravenProgressWaiters.get(sessionId)?.()
+  }
+
+  function clearRavenWaiters(sessionId: string) {
+    ravenErrorWaiters.delete(sessionId)
+    ravenProgressWaiters.get(sessionId)?.()
+  }
+
+  type McpConnection = {
+    client: Client
+    transport: any
+    lastUsed: number
+    active: number
+  }
+
+  type McpConnectionAttempt = {
+    promise: Promise<McpConnection>
+    controller: AbortController
+    waiters: number
+  }
+
+  const mcpConnections = new Map<string, McpConnection>()
+  const mcpConnectionAttempts = new Map<string, McpConnectionAttempt>()
+  let mcpIdleTimer: ReturnType<typeof setInterval> | undefined
+
+  function mcpTimeoutMs(server: OnDemandMcpServer): number {
+    return server.timeout ?? (config.raven_mcp.timeout ?? 600) * 1000
+  }
+
+  async function closeMcpClient(client: Client, transport: any) {
+    try {
+      await transport?.close?.()
+    } catch { /* best-effort */ }
+    try {
+      await client.close()
+    } catch { /* best-effort */ }
+  }
+
+  async function connectMcpClient(client: Client, transport: any, timeout: number, label: string, signal?: AbortSignal) {
+    const controller = new AbortController()
+    let timedOut = false
+    const abort = () => controller.abort(signal?.reason)
+    if (signal?.aborted) abort()
+    else signal?.addEventListener("abort", abort, { once: true })
+    const timer = setTimeout(() => {
+      timedOut = true
+      controller.abort()
+    }, timeout)
+    const aborted = new Promise<never>((_resolve, reject) => {
+      const fail = () => reject(new Error(timedOut ? `${label} timed out after ${Math.round(timeout / 1000)}s` : `${label} cancelled`))
+      if (controller.signal.aborted) fail()
+      else controller.signal.addEventListener("abort", fail, { once: true })
+    })
+
+    try {
+      await Promise.race([
+        client.connect(transport, { signal: controller.signal, timeout }),
+        aborted,
+      ])
+    } catch (error) {
+      await closeMcpClient(client, transport)
+      throw error
+    } finally {
+      clearTimeout(timer)
+      signal?.removeEventListener("abort", abort)
+    }
+  }
+
+  async function closeMcpConnection(connection: McpConnection) {
+    await closeMcpClient(connection.client, connection.transport)
+  }
+
+  function stopMcpIdleTimerIfUnused() {
+    if (mcpConnections.size || mcpConnectionAttempts.size || !mcpIdleTimer) return
+    clearInterval(mcpIdleTimer)
+    mcpIdleTimer = undefined
+  }
+
+  function ensureMcpIdleTimer() {
+    if (mcpIdleTimer) return
+    mcpIdleTimer = setInterval(() => closeIdleMcpConnections(), 60_000)
+    ;(mcpIdleTimer as any).unref?.()
+  }
+
+  async function closeMcpConnectionKey(key: string, expected?: McpConnection) {
+    const existing = mcpConnections.get(key)
+    if (!existing || (expected && existing !== expected)) return
+    mcpConnections.delete(key)
+    await closeMcpConnection(existing)
+    stopMcpIdleTimerIfUnused()
+  }
+
+  function closeIdleMcpConnections(maxAgeMs = 10 * 60 * 1000) {
+    const now = Date.now()
+    for (const [key, connection] of mcpConnections) {
+      if (!connection.active && now - connection.lastUsed > maxAgeMs) {
+        void closeMcpConnectionKey(key, connection)
+      }
+    }
+  }
+
+  async function closeMcpConnectionsForSession(sessionId: string) {
+    const prefix = `${sessionId}:`
+    const pending: Promise<McpConnection>[] = []
+    for (const [key, attempt] of mcpConnectionAttempts) {
+      if (!key.startsWith(prefix)) continue
+      attempt.controller.abort()
+      pending.push(attempt.promise)
+    }
+    await Promise.allSettled(pending)
+    await Promise.all(
+      [...mcpConnections.keys()]
+        .filter((key) => key.startsWith(prefix))
+        .map((key) => closeMcpConnectionKey(key)),
+    )
+  }
+
+  function mcpConnectionKey(sessionId: string, serverName: string): string {
+    return `${sessionId}:${serverName.toLowerCase()}`
+  }
+
+  function getOnDemandMcpServer(serverName: string): [string, OnDemandMcpServer] | undefined {
+    const entries = activeOnDemandMcpEntries()
+    return entries.find(([name]) => name.toLowerCase() === serverName.toLowerCase())
+  }
+
+  function activeOnDemandMcpEntries(): [string, OnDemandMcpServer][] {
+    return Object.entries(config.raven_mcp.onDemandMcpServers ?? {}).filter(([, server]) => server.enabled !== false)
+  }
+
+  function waitForMcpConnection(attempt: McpConnectionAttempt, signal?: AbortSignal): Promise<McpConnection> {
+    if (!signal) {
+      attempt.waiters++
+      return attempt.promise.finally(() => attempt.waiters--)
+    }
+    if (signal.aborted) return Promise.reject(new Error("MCP request cancelled"))
+    attempt.waiters++
+    return new Promise((resolve, reject) => {
+      let settled = false
+      const finish = () => {
+        if (settled) return false
+        settled = true
+        attempt.waiters--
+        signal.removeEventListener("abort", abort)
+        return true
+      }
+      const abort = () => {
+        if (!finish()) return
+        if (!attempt.waiters) attempt.controller.abort(signal.reason)
+        reject(new Error("MCP request cancelled"))
+      }
+      signal.addEventListener("abort", abort, { once: true })
+      attempt.promise.then(
+        (connection) => { if (finish()) resolve(connection) },
+        (error) => { if (finish()) reject(error) },
+      )
+    })
+  }
+
+  async function connectOnDemandMcp(serverName: string, server: OnDemandMcpServer, signal?: AbortSignal): Promise<McpConnection> {
+    const timeout = mcpTimeoutMs(server)
+    const client = new Client({ name: PACKAGE_NAME, version: PACKAGE_VERSION })
+
+    if (server.type === "local") {
+      const env = { ...cleanProcessEnv(), ...resolveStringRecord(server.environment) }
+      const transport = new StdioClientTransport({
+        command: resolveEnvPlaceholders(server.command[0]),
+        args: server.command.slice(1).map((arg) => resolveEnvPlaceholders(arg)),
+        env,
+        stderr: "pipe",
+        cwd: server.cwd ? resolveEnvPlaceholders(server.cwd) : undefined,
+      })
+      transport.stderr?.on("data", () => {})
+      transport.stderr?.on("error", () => {})
+      await connectMcpClient(client, transport, timeout, `Connecting to ${serverName}`, signal)
+      return { client, transport, lastUsed: Date.now(), active: 0 }
+    }
+
+    const url = new URL(resolveEnvPlaceholders(server.url))
+    const headers = resolveStringRecord(server.headers)
+    const transport = new StreamableHTTPClientTransport(url, headers ? { requestInit: { headers } } : undefined)
+    try {
+      await connectMcpClient(client, transport, timeout, `Connecting to ${serverName}`, signal)
+      return { client, transport, lastUsed: Date.now(), active: 0 }
+    } catch (err) {
+      if (signal?.aborted) throw err
+      const fallbackClient = new Client({ name: PACKAGE_NAME, version: PACKAGE_VERSION })
+      const fallback = new SSEClientTransport(url, headers ? { requestInit: { headers } } : undefined)
+      try {
+        await connectMcpClient(fallbackClient, fallback, timeout, `Connecting to ${serverName} via SSE`, signal)
+        return { client: fallbackClient, transport: fallback, lastUsed: Date.now(), active: 0 }
+      } catch (fallbackError) {
+        throw fallbackError
+      }
+    }
+  }
+
+  async function getMcpConnection(sessionId: string, serverName: string, signal?: AbortSignal): Promise<McpConnection> {
+    if (signal?.aborted) throw new Error("MCP request cancelled")
+    closeIdleMcpConnections()
+    const match = getOnDemandMcpServer(serverName)
+    if (!match) throw new Error(`Unknown on-demand MCP server: ${serverName}`)
+    const [canonicalName, server] = match
+    const key = mcpConnectionKey(sessionId, canonicalName)
+    const existing = mcpConnections.get(key)
+    if (existing) {
+      existing.lastUsed = Date.now()
+      return existing
+    }
+
+    const pending = mcpConnectionAttempts.get(key)
+    if (pending && !pending.controller.signal.aborted) return waitForMcpConnection(pending, signal)
+    if (pending) mcpConnectionAttempts.delete(key)
+
+    const controller = new AbortController()
+    const attempt = { controller, waiters: 0 } as McpConnectionAttempt
+    attempt.promise = connectOnDemandMcp(canonicalName, server, controller.signal)
+      .then(async (connection) => {
+        if (controller.signal.aborted || mcpConnectionAttempts.get(key) !== attempt) {
+          await closeMcpConnection(connection)
+          throw new Error("MCP connection attempt cancelled")
+        }
+        mcpConnections.set(key, connection)
+        connection.client.onclose = () => {
+          if (mcpConnections.get(key) === connection) mcpConnections.delete(key)
+          stopMcpIdleTimerIfUnused()
+        }
+        ensureMcpIdleTimer()
+        return connection
+      })
+      .finally(() => {
+        if (mcpConnectionAttempts.get(key) === attempt) mcpConnectionAttempts.delete(key)
+        stopMcpIdleTimerIfUnused()
+      })
+    mcpConnectionAttempts.set(key, attempt)
+    ensureMcpIdleTimer()
+    return waitForMcpConnection(attempt, signal)
+  }
+
+  async function listAllMcpTools(client: Client, options?: { signal?: AbortSignal; timeout?: number }): Promise<any[]> {
+    const tools: any[] = []
+    let cursor: string | undefined
+    do {
+      const result: any = await client.listTools(cursor ? { cursor } : undefined as any, options)
+      tools.push(...(result.tools ?? []))
+      cursor = result.nextCursor
+    } while (cursor)
+    return tools
+  }
+
+  async function listAllMcpResources(client: Client, options?: { signal?: AbortSignal; timeout?: number }): Promise<any[]> {
+    const resources: any[] = []
+    let cursor: string | undefined
+    do {
+      const result: any = await client.listResources(cursor ? { cursor } : undefined as any, options)
+      resources.push(...(result.resources ?? []))
+      cursor = result.nextCursor
+    } while (cursor)
+    return resources
+  }
+
+  async function listAllMcpPrompts(client: Client, options?: { signal?: AbortSignal; timeout?: number }): Promise<any[]> {
+    const prompts: any[] = []
+    let cursor: string | undefined
+    do {
+      const result: any = await client.listPrompts(cursor ? { cursor } : undefined as any, options)
+      prompts.push(...(result.prompts ?? []))
+      cursor = result.nextCursor
+    } while (cursor)
+    return prompts
+  }
+
+  function generatedToolsFromMcpTools(tools: any[]): OnDemandMcpToolInfo[] {
+    return tools
+      .filter((item) => item?.name)
+      .map((item) => ({
+        name: String(item.name),
+        ...(item.description ? { description: compactText(item.description) } : {}),
+      }))
+  }
+
+  function estimateAvoidedMcpSchemaBytes(tools: any[]): number {
+    if (!tools.length) return 0
+    return JSON.stringify(tools).length
+  }
+
+  function synthesizeMcpDescription(serverName: string, tools: OnDemandMcpToolInfo[]): string {
+    if (!tools.length) return `${serverName} exposes on-demand MCP capabilities. Use list_tools for available operations.`
+    const descriptions = tools.map((item) => item.description || item.name).filter(Boolean)
+    const joined = descriptions.slice(0, 6).join("; ")
+    return compactText(`${serverName} provides on-demand MCP tools for ${joined}.`)
+  }
+
+  async function refreshOnDemandMcpDescriptions(force = false, serverName?: string, signal?: AbortSignal): Promise<{ refreshed: string[]; failed: string[] }> {
+    if (signal?.aborted) return { refreshed: [], failed: [] }
+    const entries = activeOnDemandMcpEntries()
+      .filter(([name]) => !serverName || name.toLowerCase() === serverName.toLowerCase())
+      .filter(([name]) => {
+        const metadata = mcpMetadata[name]
+        return force || metadata?.status === "pending" || metadata?.status === "failed" || !metadata?.autoGeneratedDescription || !metadata.autoGeneratedTools?.length || metadata.avoidedSchemaBytes === undefined
+      })
+    const refreshed: string[] = []
+    const failed: string[] = []
+    if (!entries.length) return { refreshed, failed }
+    let changed = false
+    for (const [name, server] of entries) {
+      if (signal?.aborted) break
+      let connection: McpConnection | undefined
+      const checkedAt = new Date().toISOString()
+      try {
+        connection = await connectOnDemandMcp(name, server, signal)
+        const rawTools = await listAllMcpTools(connection.client, { signal, timeout: mcpTimeoutMs(server) })
+        const tools = generatedToolsFromMcpTools(rawTools)
+        mcpMetadata[name] = {
+          autoGeneratedTools: tools,
+          autoGeneratedDescription: synthesizeMcpDescription(name, tools),
+          avoidedSchemaBytes: estimateAvoidedMcpSchemaBytes(rawTools),
+          status: "ready",
+          lastCheckedAt: checkedAt,
+        }
+        changed = true
+        refreshed.push(name)
+      } catch (err: any) {
+        if (signal?.aborted) break
+        mcpMetadata[name] = {
+          ...(mcpMetadata[name] ?? {}),
+          status: "failed",
+          lastError: truncateText(err?.message ?? err, 500),
+          lastCheckedAt: checkedAt,
+        }
+        changed = true
+        failed.push(name)
+        // Keep startup/discovery best-effort; /raven mcp exposes failures.
+      } finally {
+        if (connection) await closeMcpConnection(connection)
+      }
+    }
+    if (changed) {
+      saveMcpMetadata(mcpMetadata)
+      saveDynamicGuidance()
+    }
+    return { refreshed, failed }
+  }
+
+  function waitForRefreshDelay(ms: number, signal: AbortSignal): Promise<void> {
+    if (signal.aborted) return Promise.resolve()
+    return new Promise((resolve) => {
+      const timer = setTimeout(done, ms)
+      function done() {
+        clearTimeout(timer)
+        signal.removeEventListener("abort", done)
+        resolve()
+      }
+      signal.addEventListener("abort", done, { once: true })
+    })
+  }
+
+  function queueOnDemandMcpRefresh(force = false, serverName?: string, delay = 0): Promise<{ refreshed: string[]; failed: string[] }> {
+    const controller = new AbortController()
+    mcpRefreshControllers.add(controller)
+    const run = mcpRefreshQueue
+      .catch(() => undefined)
+      .then(async () => {
+        if (delay) await waitForRefreshDelay(delay, controller.signal)
+        return refreshOnDemandMcpDescriptions(force, serverName, controller.signal)
+      })
+      .finally(() => mcpRefreshControllers.delete(controller))
+    mcpRefreshQueue = run
+    return run
+  }
+
+  function scheduleOnDemandMcpRefresh(): Promise<{ refreshed: string[]; failed: string[] }> {
+    if (mcpRefreshScheduled) return mcpRefreshPromise!
+    mcpRefreshScheduled = true
+    mcpRefreshPromise = queueOnDemandMcpRefresh(false, undefined, 1000)
+    return mcpRefreshPromise
+  }
+
+  function onDemandMcpRuntimeStatus(name: string): "pending" | "ready" | "failed" {
+    const metadata = mcpMetadata[name]
+    if (metadata?.status) return metadata.status
+    return "pending"
+  }
+
+  function displayMcpStatus(status: "pending" | "ready" | "failed"): "pending" | "loaded" | "failed" {
+    return status === "ready" ? "loaded" : status
+  }
+
+  function onDemandMcpStatusBuckets(): { loaded: string[]; failed: string[]; pending: string[] } {
+    const buckets = { loaded: [] as string[], failed: [] as string[], pending: [] as string[] }
+    for (const [name] of activeOnDemandMcpEntries()) {
+      const status = onDemandMcpRuntimeStatus(name)
+      if (status === "ready") buckets.loaded.push(name)
+      else if (status === "failed") buckets.failed.push(name)
+      else buckets.pending.push(name)
+    }
+    return buckets
+  }
+
+  function failedOnDemandMcpNames(names?: string[]): string[] {
+    const configured = activeOnDemandMcpEntries().map(([name]) => name)
+    const wanted = names?.length ? names : configured
+    return wanted.filter((name) => configured.includes(name) && onDemandMcpRuntimeStatus(name) === "failed")
+  }
+
+  function setOnDemandMcpHealth(serverName: string, status: "ready" | "failed", error?: unknown) {
+    const match = getOnDemandMcpServer(serverName)
+    if (!match) return undefined
+    const [name] = match
+    const next: OnDemandMcpMetadata = {
+      ...(mcpMetadata[name] ?? {}),
+      status,
+      lastCheckedAt: new Date().toISOString(),
+    }
+    if (status === "failed") next.lastError = truncateText(error, 500)
+    else delete next.lastError
+    mcpMetadata[name] = next
+    saveMcpMetadata(mcpMetadata)
+    saveDynamicGuidance()
+    return name
+  }
+
+  function onDemandMcpStatus(): string {
+    const entries = activeOnDemandMcpEntries()
+    if (!Object.keys(config.raven_mcp.onDemandMcpServers ?? {}).length) return "Raven on-demand MCPs: none configured."
+    if (!entries.length) return "Raven on-demand MCPs: none enabled."
+    const buckets = onDemandMcpStatusBuckets()
+    const lines = entries.map(([name, server]) => {
+      const metadata = mcpMetadata[name]
+      const source = server.description ? "user description" : "no user description"
+      const generated = metadata?.autoGeneratedDescription ? "generated" : "missing generated description"
+      const tools = metadata?.autoGeneratedTools?.length ? `${metadata.autoGeneratedTools.length} tools` : "tools pending"
+      const status = onDemandMcpRuntimeStatus(name)
+      const avoided = status === "ready" && metadata?.avoidedSchemaBytes ? `, ${formatBytes(metadata.avoidedSchemaBytes)} avoided schema` : ""
+      const error = status === "failed" && metadata?.lastError ? `, error: ${metadata.lastError}` : ""
+      return `- ${name} (${server.type}): ${displayMcpStatus(status)}, ${source}, ${generated}, ${tools}${avoided}${error}`
+    })
+    return `Raven on-demand MCPs (${config.raven_mcp.descriptionDetail ?? "full"} guidance):\n  Loaded: ${buckets.loaded.length ? buckets.loaded.join(", ") : "none"}\n  Failed: ${buckets.failed.length ? buckets.failed.join(", ") : "none"}\n  Pending: ${buckets.pending.length ? buckets.pending.join(", ") : "none"}\n${lines.join("\n")}`
+  }
+
+  function avoidedMcpSchemaBytes(): number {
+    return activeOnDemandMcpEntries().reduce((sum, [name]) => {
+      const metadata = mcpMetadata[name]
+      if (onDemandMcpRuntimeStatus(name) !== "ready") return sum
+      return sum + Math.max(0, metadata?.avoidedSchemaBytes ?? 0)
+    }, 0)
+  }
+
+  function statsText(): string {
+    const avoided = avoidedMcpSchemaBytes()
+    return `Raven context saved:\n  Avoided MCP schema load: ${formatBytes(avoided)} (~${formatTokens(avoided)} context)\n  This session: ${formatBytes(sessionBytes)} (~${formatTokens(sessionBytes)} context)\n  All time: ${formatBytes(totalBytes)} (~${formatTokens(totalBytes)} context)`
+  }
+
+  function helpText(): string {
+    return `Raven commands:\n  /raven help - show this help\n  /raven route - show or edit routed tools/keywords\n  /raven seek model <provider/model>|auto - change or auto-detect the search model (requires restart)\n  /raven seek effort <value> - change search reasoning effort (requires restart)\n  /raven seek timeout <seconds> - change search timeout\n  /raven mcp - show on-demand MCP metadata\n  /raven mcp refresh [server] - refresh MCP metadata\n  /raven mcp detail full|minimized - change MCP guidance detail\n  /raven mcp model <provider/model>|auto - change or auto-detect the MCP model (requires restart)\n  /raven mcp effort <value> - change MCP reasoning effort (requires restart)\n  /raven mcp timeout <seconds> - change MCP delegation timeout\n  /raven update - check for an update\n  /raven stats - show context saved`
+  }
+
+  function formatMcpList(title: string, items: any[], fields: string[] = ["name", "description"]): string {
+    if (!items.length) return `${title}: none found.`
+    const lines = items.map((item) => {
+      const primary = fields.map((field) => item?.[field]).find(Boolean) ?? JSON.stringify(item)
+      const description = item?.description && primary !== item.description ? ` - ${truncateText(item.description, 300)}` : ""
+      return `- ${truncateText(primary, 180)}${description}`
+    })
+    return `${title}:\n${lines.join("\n")}`
+  }
+
+  function formatMcpToolsForRaven(serverName: string, tools: any[]): string {
+    if (!tools.length) return `Tools for ${serverName}: none found.`
+    const lines = tools.map((item) => {
+      const description = item?.description ? `\n  Description: ${truncateText(item.description, 600)}` : ""
+      const schema = item?.inputSchema ? `\n  Input schema: ${truncateText(JSON.stringify(item.inputSchema), 3000)}` : ""
+      return `- ${item?.name ?? "(unnamed)"}${description}${schema}`
+    })
+    return `Tools for ${serverName}:\n${lines.join("\n")}`
+  }
+
+  function formatMcpResult(result: any): string {
+    if (!result) return "No result."
+    if (Array.isArray(result.content)) {
+      const parts = result.content.map((part: any) => {
+        if (part?.type === "text") return part.text
+        return JSON.stringify(part)
+      })
+      return parts.join("\n") || JSON.stringify(result)
+    }
+    return typeof result === "string" ? result : JSON.stringify(result, null, 2)
+  }
+
+  function parseMcpArguments(raw: string | undefined): Record<string, any> {
+    if (!raw?.trim()) return {}
+    const parsed = JSON.parse(raw)
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("argumentsJson must be a JSON object")
+    }
+    return parsed
+  }
+
+  // ── Context saved by Raven delegation ──
+  let sessionBytes = 0
+  let totalBytes = config.stats?.bytes ?? 0
+
+  function addBytes(bytes: number) {
+    sessionBytes += bytes
+    const updated = updateConfig((latest) => ({
+      stats: { bytes: Math.max(totalBytes, latest.stats?.bytes ?? 0) + bytes },
+    }))
+    totalBytes = updated.stats?.bytes ?? totalBytes + bytes
+  }
+
+  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 >= 1_000_000 ? `${(tokens / 1_000_000).toFixed(1)}M`
+      : 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 controller = new AbortController()
+    const timeout = setTimeout(() => controller.abort(), 5000)
+    try {
+      const res = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, {
+        headers: { accept: "application/json" },
+        signal: controller.signal,
+      })
+      if (!res.ok) return undefined
+      const data = await res.json() as { version?: string }
+      return data.version
+    } finally {
+      clearTimeout(timeout)
+    }
+  }
+
+  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 estimateRavenSavedCandidateBytes(messages: any[]): number {
+    const assistantMessages = messages.filter((m: any) =>
+      m?.info?.role === "assistant" && m?.info?.tokens?.output > 0
+    )
+    const first = assistantMessages[0]
+    const last = assistantMessages[assistantMessages.length - 1]
+    const t = last?.info?.tokens
+    const firstTokens = first?.info?.tokens
+    if (!t) return 0
+
+    // Balanced estimate: total Raven context minus the first-turn prompt/schema/cache baseline.
+    const totalTokens = (t.input ?? 0) + (t.output ?? 0) + (t.reasoning ?? 0) + (t.cache?.read ?? 0) + (t.cache?.write ?? 0)
+    const baselineTokens = firstTokens
+      ? (firstTokens.input ?? 0) + (firstTokens.cache?.read ?? 0) + (firstTokens.cache?.write ?? 0)
+      : 0
+    const savedCandidateTokens = Math.max(0, totalTokens - baselineTokens)
+    return savedCandidateTokens * 4
+  }
+
+  async function countRavenSavedCandidateBytes(sessionId: string, signal?: AbortSignal): Promise<number> {
+    const messagesResp = await client.session.messages({ path: { id: sessionId }, signal })
+    const messages = (messagesResp as any)?.data ?? []
+    return estimateRavenSavedCandidateBytes(messages)
+  }
+
+  async function getUpdateInfo(): Promise<{ current: string; latest?: string; available: boolean }> {
+    if (updateInfo) return updateInfo
+    if (!updateCheckPromise) {
+      updateCheckPromise = checkForUpdate()
+        .then((info) => {
+          updateInfo = info
+          return info
+        })
+        .catch((err) => {
+          updateCheckPromise = undefined
+          throw err
+        })
+    }
+    return updateCheckPromise
+  }
+
+  async function refreshUpdateInfo(): Promise<{ current: string; latest?: string; available: boolean }> {
+    updateInfo = undefined
+    updateCheckPromise = checkForUpdate()
+      .then((info) => {
+        updateInfo = info
+        return info
+      })
+      .catch((err) => {
+        updateCheckPromise = undefined
+        throw err
+      })
+    return updateCheckPromise
+  }
+
+  function clearPluginCache(): string[] {
+    if (host === "v2") return []
+    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 {
+    if (host === "v2") return `Quit and restart OpenCode 2 to reload Raven. If the package is pinned in plugins, update its version to ${PACKAGE_NAME}@${latest} first. OpenCode 2 manages its own plugin cache.`
+    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 getUpdateInfo()
+      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 */ }
+  }
+
+  async function notifyIfMcpFailures(names?: string[]) {
+    try {
+      const failed = failedOnDemandMcpNames(names)
+      if (!failed.length) {
+        lastNotifiedMcpFailureKey = ""
+        return
+      }
+      const key = failed.sort().join("|")
+      if (key === lastNotifiedMcpFailureKey) return
+      lastNotifiedMcpFailureKey = key
+      const label = failed.length === 1 ? failed[0] : `${failed.length} on-demand MCPs`
+      await (client as any).tui?.showToast?.({
+        body: {
+          title: "Raven MCP warning",
+          message: `${label} failed to load. Run /raven mcp for details.`,
+          variant: "warning",
+          duration: 12000,
+        },
+      })
+    } catch { /* MCP failure notifications are best-effort */ }
+  }
+
+  async function notifyIfDuplicateMcps() {
+    try {
+      if (!duplicateMcpServers.length) return
+      const label = duplicateMcpServers.length === 1 ? duplicateMcpServers[0] : `${duplicateMcpServers.length} MCPs`
+      await (client as any).tui?.showToast?.({
+        body: {
+          title: "Raven MCP duplicate config",
+          message: `${label} configured both globally and on-demand. Prefer one location to avoid duplicate schema/connection behavior.`,
+          variant: "warning",
+          duration: 12000,
+        },
+      })
+    } catch { /* duplicate MCP notifications are best-effort */ }
+  }
+
+  async function notifyIfModelSetupRequired() {
+    const message = modelSetupInstructions()
+    if (!message) return
+    const updateReady = (!!config.raven_seek.model && activeSeekModel !== config.raven_seek.model)
+      || (!!config.raven_mcp.model && activeMcpModel !== config.raven_mcp.model)
+    try {
+      await (client as any).tui?.showToast?.({
+        body: {
+          title: updateReady ? "Raven model selected" : "Raven first-time setup",
+          message: updateReady
+            ? "A free Raven model was selected. Restart OpenCode to load it."
+            : "No free Raven model was detected. Run /raven for setup instructions; routing is inactive until configured.",
+          variant: updateReady ? "info" : "warning",
+          duration: 15000,
+        },
+      })
+    } catch { /* model setup remains visible in /raven */ }
+  }
+
+  function delegationAgent(kind: DelegationKind): "raven" | "raven-mcp" {
+    return kind === "mcp" ? "raven-mcp" : "raven"
+  }
+
+  function delegationToolName(kind: DelegationKind): "raven_seek" | "raven_mcp" {
+    return kind === "mcp" ? "raven_mcp" : "raven_seek"
+  }
+
+  function delegationTitle(kind: DelegationKind): string {
+    return kind === "mcp" ? "Raven MCP" : "Raven Seek"
+  }
+
+  async function rootSessionId(sessionId: string, signal?: AbortSignal): Promise<string> {
+    let current = sessionId
+    const seen = new Set<string>()
+    while (!seen.has(current)) {
+      seen.add(current)
+      const response = await client.session.get({ path: { id: current }, signal })
+      const session = (response as any)?.data ?? response
+      if (!session?.parentID) return current
+      current = session.parentID
+    }
+    return sessionId
+  }
+
+  async function syncCreatedSession(sessionId: string, title: string, signal?: AbortSignal) {
+    try {
+      await client.session.update({
+        path: { id: sessionId },
+        body: { title },
+        signal,
+      })
+    } catch (error) {
+      if (signal?.aborted) throw error
+      // Delegation still works if an older or disconnected TUI misses the sync event.
+    }
+  }
+
+  async function executeRavenDelegation(kind: DelegationKind, args: { query: string; sessionId?: string }, context: any) {
+    const started = Date.now()
+    const agent = delegationAgent(kind)
+    const toolName = delegationToolName(kind)
+    const title = delegationTitle(kind)
+    await refreshModelsIfPending()
+    if (!modelOperational(kind)) {
+      return { title, output: modelSetupInstructions(kind) }
+    }
+    const timeout = (kind === "mcp" ? config.raven_mcp.timeout : config.raven_seek.timeout) ?? 600
+    const timeoutMs = timeout * 1000
+    let sessionId: string | undefined
+    let resumed = false
+    let previousSavedCandidate = 0
+
+    try {
+      const requestedSessionId = args.sessionId?.trim()
+      if (args.sessionId !== undefined && !requestedSessionId) {
+        return { title, output: "Cannot resume Raven: sessionId must not be empty." }
+      }
+
+      let rootId = context.sessionID
+      try {
+        rootId = await rootSessionId(context.sessionID, context.abort)
+      } catch (error) {
+        if (context.abort.aborted) throw error
+        // Falling back preserves delegation if an older OpenCode build cannot read the caller session.
+      }
+
+      if (requestedSessionId) {
+        const knownKind = ravenSessionKinds.get(requestedSessionId)
+        const knownRavenSession = knownKind === kind || sessionAgents.get(requestedSessionId) === agent
+        let existingSession: any
+        try {
+          const sessionResp = await client.session.get({ path: { id: requestedSessionId }, signal: context.abort })
+          existingSession = (sessionResp as any)?.data ?? sessionResp
+        } catch (error) {
+          if (context.abort.aborted) throw error
+          return { title, output: `Cannot resume Raven session ${requestedSessionId}: the session was not found or could not be read.` }
+        }
+
+        if (!existingSession?.id || existingSession.id !== requestedSessionId) {
+          return { title, output: `Cannot resume Raven session ${requestedSessionId}: the session was not found or could not be read.` }
+        }
+        const validParent = existingSession.parentID === rootId || existingSession.parentID === context.sessionID
+        if (!validParent || existingSession.projectID !== input.project.id) {
+          return { title, output: "Cannot resume Raven: sessionId is not part of this main session's Raven tree." }
+        }
+
+        let messages: any[]
+        try {
+          const messagesResp = await client.session.messages({ path: { id: requestedSessionId }, signal: context.abort })
+          const messageData = (messagesResp as any)?.data
+          if (!Array.isArray(messageData)) {
+            return { title, output: `Cannot resume Raven session ${requestedSessionId}: its message history could not be read.` }
+          }
+          messages = messageData
+        } catch (error) {
+          if (context.abort.aborted) throw error
+          return { title, output: `Cannot resume Raven session ${requestedSessionId}: its message history could not be read.` }
+        }
+
+        const userMessages = messages.filter((message: any) => message?.info?.role === "user")
+        const persistedRavenSession = (userMessages.length > 0 || (host === "v2"
+          && existingSession.agent === agent && existingSession.metadata?.opencodeRavenAgent === agent))
+          && userMessages.every((message: any) => message.info.agent === agent)
+        if (!persistedRavenSession && !(knownRavenSession && userMessages.length === 0)) {
+          return { title, output: `Cannot resume Raven: sessionId does not belong to the ${agent} agent.` }
+        }
+
+        sessionId = requestedSessionId
+        resumed = true
+        previousSavedCandidate = estimateRavenSavedCandidateBytes(messages)
+      } else {
+        const sessionTitle = `${toolName}: ${args.query.slice(0, 80)}`
+        const session = await client.session.create({
+          body: {
+            parentID: rootId,
+            title: sessionTitle,
+            ...(host === "v2" ? { agent } : {}),
+          },
+          signal: context.abort,
+        })
+        sessionId = (session as any)?.data?.id ?? (session as any)?.id
+        if (!sessionId) return { title, output: "Failed to create Raven session." }
+        await syncCreatedSession(sessionId, sessionTitle, context.abort)
+      }
+
+      ravenSessions.add(sessionId)
+      ravenSessionKinds.set(sessionId, kind)
+      const activeSessionId = sessionId
+      context.metadata({ metadata: { sessionId } })
+
+      try {
+        writeFileSync(join(tmpdir(), "raven-sessions.log"), `${new Date().toISOString()} ${sessionId}\n`)
+      } catch { /* non-fatal */ }
+
+      if (activeRavenPrompts.has(activeSessionId)) {
+        return {
+          title,
+          metadata: { sessionId: activeSessionId },
+          output: `Raven session \`${activeSessionId}\` is already handling a request. Wait for it to finish before sending another follow-up.`,
+        }
+      }
+      activeRavenPrompts.add(activeSessionId)
+
+      let timer: ReturnType<typeof setTimeout> | undefined
+      let promptCompleted = false
+      let sessionAbort: Promise<unknown> | undefined
+      const promptController = new AbortController()
+      const abortPrompt = () => {
+        if (promptController.signal.aborted) return
+        promptController.abort(context.abort.reason)
+        const abortController = new AbortController()
+        const abortTimer = setTimeout(() => abortController.abort(), Math.min(timeoutMs, 5_000))
+        sessionAbort = client.session.abort({
+          path: { id: activeSessionId },
+          signal: abortController.signal,
+          throwOnError: true,
+        }).catch(() => undefined).finally(() => clearTimeout(abortTimer))
+      }
+      if (context.abort.aborted) abortPrompt()
+      else context.abort.addEventListener("abort", abortPrompt, { once: true })
+      const providerError = waitForRavenProviderError(sessionId)
+      const firstProgress = waitForRavenFirstProgress(sessionId, Math.min(timeoutMs, 30_000))
+
+      try {
+        const result = await Promise.race([
+          client.session.prompt({
+            path: { id: sessionId },
+            body: { agent, parts: [{ type: "text", text: args.query }] },
+            signal: promptController.signal,
+            throwOnError: true,
+          }),
+          providerError,
+          firstProgress,
+          new Promise<never>((_, reject) => {
+            timer = setTimeout(() => {
+              abortPrompt()
+              reject(new Error(`Raven timed out after ${timeout}s - child session retained: ${sessionId}`))
+            }, timeoutMs)
+          }),
+        ])
+        promptCompleted = true
+        if (timer) clearTimeout(timer)
+        clearRavenWaiters(sessionId)
+        if ((result as any)?.error) throw new Error(providerErrorMessage((result as any).error))
+
+        const elapsed = ((Date.now() - started) / 1000).toFixed(1)
+        const parts = (result as any)?.data?.parts ?? []
+        const output = parts
+          .filter((part: any) => part.type === "text" && part.text)
+          .map((part: any) => part.text)
+          .join("\n") || "Raven returned no results."
+
+        let savedCandidate = 0
+        const statsController = new AbortController()
+        const abortStats = () => statsController.abort(context.abort.reason)
+        const statsTimer = setTimeout(() => statsController.abort(), Math.min(timeoutMs, 5_000))
+        if (context.abort.aborted) abortStats()
+        else context.abort.addEventListener("abort", abortStats, { once: true })
+        try {
+          const totalSavedCandidate = await countRavenSavedCandidateBytes(sessionId, statsController.signal)
+          savedCandidate = Math.max(0, totalSavedCandidate - previousSavedCandidate)
+        } catch { /* best-effort */ }
+        finally {
+          clearTimeout(statsTimer)
+          context.abort.removeEventListener("abort", abortStats)
+        }
+        if (savedCandidate <= 0) {
+          for (const part of parts) {
+            if (part.args) savedCandidate += JSON.stringify(part.args).length
+            if (part.content) savedCandidate += typeof part.content === "string" ? part.content.length : JSON.stringify(part.content).length
+          }
+        }
+
+        const continuation = `Raven session: \`${sessionId}\`${resumed ? " (continued)" : ""}. Pass this as \`sessionId\` in a later \`${toolName}\` call to continue the same retrieval.`
+        const activity = kind === "mcp" ? "used MCPs" : "searched"
+        const resultOutput = `${output}\n\n*Raven ${activity} for ${elapsed}s - ${formatBytes(savedCandidate)} handled, ${formatTokens(savedCandidate)} tokens*\n\n${continuation}`
+        addBytes(Math.max(0, savedCandidate - resultOutput.length))
+        delete ravenProviderIssues[kind]
+        return { title, metadata: { sessionId }, output: resultOutput }
+      } finally {
+        context.abort.removeEventListener("abort", abortPrompt)
+        if (!promptCompleted) abortPrompt()
+        if (sessionAbort) await sessionAbort
+        if (timer) clearTimeout(timer)
+        clearRavenWaiters(sessionId)
+        activeRavenPrompts.delete(activeSessionId)
+      }
+    } catch (error: any) {
+      const elapsed = ((Date.now() - started) / 1000).toFixed(1)
+      const message = String(error?.message ?? error ?? "").toLowerCase()
+      const missingSession = /session.*not found|not found.*session/i.test(message)
+      const activity = kind === "mcp" ? "MCP retrieval" : "search"
+      const hint =
+        context.abort.aborted ? `Raven ${activity} cancelled.`
+        : /rate.?limit|too many requests|429/i.test(message) ? "Raven rate limited - wait 30s, then retry with a narrower query."
+        : /quota|usage.?limit|usage exceeded|free usage|subscribe to go|subscription|billing|insufficient.*(?:credit|balance|quota)/i.test(message) ? "Raven API quota/subscription exhausted - proceed without Raven and mention what information may be missing."
+        : /auth|unauthorized|forbidden|401|403|api key|login/i.test(message) ? "Raven provider authentication failed - proceed without Raven and check the configured provider login or API key."
+        : /token|context.?length|too large|too long/i.test(message) ? "Raven query too large - shorten your query and retry."
+        : missingSession ? `The Raven session is no longer available - retry without sessionId to start a new ${activity}.`
+        : /model|unavailable|down|not found/i.test(message) ? "Raven model unavailable - retry later, or proceed without the missing information."
+        : /did not produce an initial response|retry dialog|timeout|timed.?out|session retained/i.test(message) ? error.message
+        : `Raven ${activity} failed. Note the resulting information gap. [${error.message || error}]`
+      if (!missingSession && /quota|usage.?limit|usage exceeded|free usage|subscribe to go|subscription|billing|auth|unauthorized|forbidden|401|403|api key|login|model|unavailable|down|not found|did not produce an initial response|retry dialog/i.test(message)) {
+        ravenProviderIssues[kind] = hint
+      }
+      const recovery = ravenProviderIssues[kind] ? `\n\n${ravenRecoveryInstructions(kind)}` : ""
+      const continuation = sessionId && !missingSession
+        ? `\n\nRaven session: \`${sessionId}\`. Pass this as \`sessionId\` in a later \`${toolName}\` call to retry or continue.`
+        : ""
+      return { title, metadata: sessionId ? { sessionId } : undefined, output: `${hint}${recovery}\n\n*Attempt took ${elapsed}s*${continuation}` }
+    }
+  }
+
+  return {
+    globalMcpRouting(names: string[]) {
+      globalMcpServers = uniqueStrings(names)
+      const onDemandNames = new Set(activeOnDemandMcpEntries().map(([name]) => name.toLowerCase()))
+      duplicateMcpServers = globalMcpServers.filter((name) => onDemandNames.has(name.toLowerCase()))
+      duplicateMcpToastPending = duplicateMcpServers.length > 0
+    },
+    // V2 injects these texts at model-request time instead of using config.instructions.
+    guidance() {
+      return `${readFileSync(MCP_GUIDANCE_MD, "utf-8")}\n\n${onDemandMcpGuidance("delegate")}`
+    },
+    async dispose() {
+      for (const controller of mcpRefreshControllers) controller.abort()
+      for (const attempt of mcpConnectionAttempts.values()) attempt.controller.abort()
+      await Promise.allSettled([
+        ...[...mcpConnectionAttempts.values()].map((attempt) => attempt.promise),
+        mcpRefreshQueue,
+      ])
+      await Promise.all([...mcpConnections.keys()].map((key) => closeMcpConnectionKey(key)))
+      if (mcpIdleTimer) clearInterval(mcpIdleTimer)
+      mcpIdleTimer = undefined
+      for (const sessionId of ravenProgressWaiters.keys()) clearRavenWaiters(sessionId)
+      ravenErrorWaiters.clear()
+    },
+
+    async config(configInput: any) {
+      globalMcpServers = uniqueStrings(Object.entries(configInput.mcp ?? {})
+        .filter(([, value]) => !value || typeof value !== "object" || (value as any).enabled !== false)
+        .map(([name]) => name))
+      const onDemandNames = new Set(activeOnDemandMcpEntries().map(([name]) => name.toLowerCase()))
+      duplicateMcpServers = globalMcpServers.filter((name) => onDemandNames.has(name.toLowerCase()))
+
+      // Inject MCP guidance as a startup instruction file (absolute path for npm compat).
+      // The file is regenerated after MCP health checks, not during the startup pending reset.
+      configInput.instructions = configInput.instructions || []
+      if (!configInput.instructions.includes(MCP_GUIDANCE_MD)) {
+        configInput.instructions.push(MCP_GUIDANCE_MD)
+      }
+      if (!configInput.instructions.includes(dynamicGuidanceFile)) {
+        configInput.instructions.push(dynamicGuidanceFile)
+      }
+
+      // Register Raven from Raven.md, with config file overrides
+      configInput.agent = configInput.agent || {}
+      const seekModel = activeSeekModel || fm.model
+      const mcpModel = activeMcpModel || mcpFm.model
+      configInput.agent.raven = {
+        description: fm.description || "",
+        mode: fm.mode || "subagent",
+        hidden: fm.hidden !== undefined ? fm.hidden : false,
+        disable: !seekModel,
+        ...(seekModel ? { model: seekModel } : {}),
+        options: {
+          ...extractOptions(fm),
+          ...(config.raven_seek.reasoning_effort ? { reasoning_effort: config.raven_seek.reasoning_effort } : {}),
+        },
+        permission: fm.permission || {},
+        prompt: ravenAgentPrompt(),
+      }
+      configInput.agent["raven-mcp"] = {
+        description: mcpFm.description || "",
+        mode: mcpFm.mode || "subagent",
+        hidden: mcpFm.hidden !== undefined ? mcpFm.hidden : true,
+        disable: !mcpModel,
+        ...(mcpModel ? { model: mcpModel } : {}),
+        options: {
+          ...extractOptions(mcpFm),
+          ...(config.raven_mcp.reasoning_effort ? { reasoning_effort: config.raven_mcp.reasoning_effort } : {}),
+        },
+        permission: mcpFm.permission || {},
+        prompt: ravenMcpAgentPrompt(),
+      }
+
+      // Register /raven command
+      configInput.command = configInput.command || {}
+      if (!configInput.command.raven) {
+        configInput.command.raven = {
+          template: "Manage Raven search routing, on-demand MCPs, models, timeouts, updates, and status",
+          description: "Manage Raven search routing, on-demand MCPs, and per-agent models",
+        }
+      }
+
+      scheduleOnDemandMcpRefresh()
+      updateToastPending = true
+      mcpFailureToastPending = true
+      duplicateMcpToastPending = duplicateMcpServers.length > 0
+      modelSetupToastPending = !!modelSetupInstructions()
+    },
+
+    // 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.",
+        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."),
+          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) {
+          const started = Date.now()
+          await refreshModelsIfPending()
+          if (!modelOperational("seek")) {
+            return { title: "Raven Seek", output: modelSetupInstructions("seek") }
+          }
+          const timeout = (config.raven_seek.timeout ?? 600) * 1000
+          let sessionId: string | undefined
+          let resumed = false
+          let previousSavedCandidate = 0
+          try {
+            const requestedSessionId = args.sessionId?.trim()
+            if (args.sessionId !== undefined && !requestedSessionId) {
+              return { title: "Raven Seek", output: "Cannot resume Raven: sessionId must not be empty." }
+            }
+
+            let rootId = context.sessionID
+            try {
+              rootId = await rootSessionId(context.sessionID, context.abort)
+            } catch (error) {
+              if (context.abort.aborted) throw error
+            }
+
+            if (requestedSessionId) {
+              const knownRavenSession = ravenSessionKinds.get(requestedSessionId) === "seek" || sessionAgents.get(requestedSessionId) === "raven"
+              let existingSession: any
+              try {
+                const sessionResp = await client.session.get({ path: { id: requestedSessionId }, signal: context.abort })
+                existingSession = (sessionResp as any)?.data ?? sessionResp
+              } catch (err) {
+                if (context.abort.aborted) throw err
+                return { title: "Raven Seek", output: `Cannot resume Raven session ${requestedSessionId}: the session was not found or could not be read.` }
+              }
+
+              if (!existingSession?.id || existingSession.id !== requestedSessionId) {
+                return { title: "Raven Seek", output: `Cannot resume Raven session ${requestedSessionId}: the session was not found or could not be read.` }
+              }
+              if ((existingSession.parentID !== rootId && existingSession.parentID !== context.sessionID) || existingSession.projectID !== input.project.id) {
+                return { title: "Raven Seek", output: "Cannot resume Raven: sessionId is not a Raven child of this main session." }
+              }
+
+              let messages: any[]
+              try {
+                const messagesResp = await client.session.messages({ path: { id: requestedSessionId }, signal: context.abort })
+                const messageData = (messagesResp as any)?.data
+                if (!Array.isArray(messageData)) {
+                  return { title: "Raven Seek", output: `Cannot resume Raven session ${requestedSessionId}: its message history could not be read.` }
+                }
+                messages = messageData
+              } catch (err) {
+                if (context.abort.aborted) throw err
+                return { title: "Raven Seek", output: `Cannot resume Raven session ${requestedSessionId}: its message history could not be read.` }
+              }
+
+              const userMessages = messages.filter((message: any) => message?.info?.role === "user")
+              const persistedRavenSession = (userMessages.length > 0 || (host === "v2"
+                && existingSession.agent === "raven" && existingSession.metadata?.opencodeRavenAgent === "raven"))
+                && userMessages.every((message: any) => message.info.agent === "raven")
+              if (!persistedRavenSession && !(knownRavenSession && userMessages.length === 0)) {
+                return { title: "Raven Seek", output: "Cannot resume Raven: sessionId is not a Raven child of this main session." }
+              }
+
+              sessionId = requestedSessionId
+              resumed = true
+              previousSavedCandidate = estimateRavenSavedCandidateBytes(messages)
+            } else {
+              const sessionTitle = `raven_seek: ${args.query.slice(0, 80)}`
+              const session = await client.session.create({
+                body: {
+                    parentID: rootId,
+                    title: sessionTitle,
+                    ...(host === "v2" ? { agent: "raven" } : {}),
+                },
+                signal: context.abort,
+              })
+
+              sessionId = (session as any)?.data?.id ?? (session as any)?.id
+              if (!sessionId) {
+                return { title: "Raven Seek", output: "Failed to create Raven session." }
+              }
+              await syncCreatedSession(sessionId, sessionTitle, context.abort)
+            }
+
+            ravenSessions.add(sessionId)
+            ravenSessionKinds.set(sessionId, "seek")
+            const activeSessionId = sessionId
+
+            // Preserve the child session link for TUI clients that render it.
+            context.metadata({ metadata: { sessionId } })
+
+            // Log session for debugging
+            try {
+              const logFile = join(tmpdir(), "raven-sessions.log")
+              const ts = new Date().toISOString()
+              writeFileSync(logFile, `${ts} ${sessionId}\n`)
+            } catch { /* non-fatal */ }
+
+            if (activeRavenPrompts.has(activeSessionId)) {
+              return {
+                title: "Raven Seek",
+                metadata: { sessionId: activeSessionId },
+                output: `Raven session \`${activeSessionId}\` is already handling a request. Wait for it to finish before sending another follow-up.`,
+              }
+            }
+            activeRavenPrompts.add(activeSessionId)
+
+            // Send the query to Raven with timeout. Provider/API errors are also
+            // surfaced through message.updated events; fail as soon as one lands
+            // so the caller does not wait for the full timeout on quota/auth issues.
+            let timer: ReturnType<typeof setTimeout> | undefined
+            let promptCompleted = false
+            let sessionAbort: Promise<unknown> | undefined
+            const promptController = new AbortController()
+            const abortPrompt = () => {
+              if (promptController.signal.aborted) return
+              promptController.abort(context.abort.reason)
+              const abortController = new AbortController()
+              const abortTimer = setTimeout(() => abortController.abort(), Math.min(timeout, 5_000))
+              sessionAbort = client.session.abort({
+                path: { id: activeSessionId },
+                signal: abortController.signal,
+                throwOnError: true,
+              }).catch(() => undefined).finally(() => clearTimeout(abortTimer))
+            }
+            if (context.abort.aborted) abortPrompt()
+            else context.abort.addEventListener("abort", abortPrompt, { once: true })
+            const providerError = waitForRavenProviderError(sessionId)
+            const firstProgress = waitForRavenFirstProgress(sessionId, Math.min(timeout, 30_000))
+            try {
+              const result = await Promise.race([
+                client.session.prompt({
+                  path: { id: sessionId },
+                  body: {
+                    agent: "raven",
+                    parts: [{ type: "text", text: args.query }],
+                  },
+                  signal: promptController.signal,
+                  throwOnError: true,
+                }),
+                providerError,
+                firstProgress,
+                new Promise<never>((_, reject) => {
+                  timer = setTimeout(() => {
+                    abortPrompt()
+                    reject(new Error(`Raven timed out after ${timeout / 1000}s — child session retained: ${sessionId}`))
+                  }, timeout)
+                }),
+              ])
+              promptCompleted = true
+              if (timer) clearTimeout(timer)
+              clearRavenWaiters(sessionId)
+              if ((result as any)?.error) throw new Error(providerErrorMessage((result as any).error))
+
+              const elapsed = ((Date.now() - started) / 1000).toFixed(1)
+
+              // Extract text from the response
+              const parts = (result as any)?.data?.parts ?? []
+              const textParts = parts
+                .filter((p: any) => p.type === "text" && p.text)
+                .map((p: any) => p.text)
+              const output = textParts.join("\n") || "Raven returned no results."
+
+              // Context saved = Raven output/reasoning/cache context - compact answer returned to main session.
+              let savedCandidate = 0
+              const statsController = new AbortController()
+              const abortStats = () => statsController.abort(context.abort.reason)
+              const statsTimer = setTimeout(() => statsController.abort(), Math.min(timeout, 5_000))
+              if (context.abort.aborted) abortStats()
+              else context.abort.addEventListener("abort", abortStats, { once: true })
+              try {
+                const totalSavedCandidate = await countRavenSavedCandidateBytes(sessionId, statsController.signal)
+                savedCandidate = Math.max(0, totalSavedCandidate - previousSavedCandidate)
+              } catch { /* best-effort */ }
+              finally {
+                clearTimeout(statsTimer)
+                context.abort.removeEventListener("abort", abortStats)
+              }
+              if (savedCandidate <= 0) {
+                for (const part of parts) {
+                  if (part.args) savedCandidate += JSON.stringify(part.args).length
+                  if (part.content) savedCandidate += typeof part.content === "string" ? part.content.length : JSON.stringify(part.content).length
+                }
+              }
+              const continuation = `Raven session: \`${sessionId}\`${resumed ? " (continued)" : ""}. Pass this as \`sessionId\` in a later \`raven_seek\` call to continue the same research.`
+              const resultOutput = `${output}\n\n*Raven searched for ${elapsed}s — ${formatBytes(savedCandidate)} handled, ${formatTokens(savedCandidate)} tokens*\n\n${continuation}`
+              addBytes(Math.max(0, savedCandidate - resultOutput.length))
+              delete ravenProviderIssues.seek
+
+              return { title: "Raven Seek", metadata: { sessionId }, output: resultOutput }
+            } finally {
+              context.abort.removeEventListener("abort", abortPrompt)
+              if (!promptCompleted) abortPrompt()
+              if (sessionAbort) await sessionAbort
+              if (timer) clearTimeout(timer)
+              clearRavenWaiters(sessionId)
+              activeRavenPrompts.delete(activeSessionId)
+            }
+          } catch (err: any) {
+            const elapsed = ((Date.now() - started) / 1000).toFixed(1)
+            const msg = String(err?.message ?? err ?? "").toLowerCase()
+            const missingSession = /session.*not found|not found.*session/i.test(msg)
+            const hint =
+              context.abort.aborted ? "Raven search cancelled."
+              : /rate.?limit|too many requests|429/i.test(msg) ? "Raven rate limited — wait 30s then retry with a narrower query."
+              : /quota|usage.?limit|usage exceeded|free usage|subscribe to go|subscription|billing|insufficient.*(?:credit|balance|quota)/i.test(msg) ? "Raven API quota/subscription exhausted — proceed without Raven, tell the user Raven could not run, and mention what information may be missing."
+              : /auth|unauthorized|forbidden|401|403|api key|login/i.test(msg) ? "Raven provider authentication failed — proceed without Raven and tell the user to check the Raven model/provider login or API key."
+              : /token|context.?length|too large|too long/i.test(msg) ? "Raven query too large — shorten your query and retry."
+              : missingSession ? "The Raven session is no longer available — retry without sessionId to start a new Raven search."
+              : /model|unavailable|down|not found/i.test(msg) ? "Raven model unavailable — retry later, or proceed without search."
+              : /did not produce an initial response|retry dialog/i.test(msg) ? err.message
+              : /timeout|timed.?out|session kept/i.test(msg) ? err.message
+              : `Raven search failed. Proceed without search — note gaps for the user. [${err.message || err}]`
+            if (!missingSession && /quota|usage.?limit|usage exceeded|free usage|subscribe to go|subscription|billing|auth|unauthorized|forbidden|401|403|api key|login|model|unavailable|down|not found|did not produce an initial response|retry dialog/i.test(msg)) {
+              ravenProviderIssues.seek = hint
+            }
+            const recovery = ravenProviderIssues.seek ? `\n\n${ravenRecoveryInstructions("seek")}` : ""
+            const continuation = sessionId && !missingSession
+              ? `\n\nRaven session: \`${sessionId}\`. Pass this as \`sessionId\` in a later \`raven_seek\` call to retry or continue.`
+              : ""
+            return { title: "Raven Seek", metadata: sessionId ? { sessionId } : undefined, output: `${hint}${recovery}\n\n*Attempt took ${elapsed}s*${continuation}` }
+          }
+        },
+      }),
+      "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.",
+        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."),
+        },
+        async execute(args, context) {
+          return executeRavenDelegation("mcp", args, context)
+        },
+      }),
+      "raven_mcp_bridge": tool({
+        description: "Internal bridge for the Raven MCP agent. Other agents must not call this tool. Lists and calls tools, resources, and prompts from configured on-demand MCP servers without globally exposing their schemas.",
+        args: {
+          server: tool.schema.string().describe("On-demand MCP server name from Raven config, e.g. context7, exa, grep_app, unityMCP."),
+          operation: tool.schema.enum(["list_tools", "call_tool", "list_resources", "read_resource", "list_prompts", "get_prompt"]).describe("MCP operation to perform."),
+          name: tool.schema.string().optional().describe("Tool name for call_tool, resource URI for read_resource, or prompt name for get_prompt."),
+          argumentsJson: tool.schema.string().optional().describe("JSON object string with arguments for call_tool or get_prompt, e.g. {\"query\":\"latest AI news\"}. Omit for no arguments."),
+        },
+        async execute(args, context) {
+          if (ravenSessionKinds.get(context.sessionID) !== "mcp" && sessionAgents.get(context.sessionID) !== "raven-mcp") {
+            return { title: "Raven MCP Bridge", output: "raven_mcp_bridge is only available inside the Raven MCP agent. Use raven_mcp for on-demand MCP requests." }
+          }
+
+          const operation = args.operation as RavenMcpOperation
+          const server = getOnDemandMcpServer(args.server)?.[1]
+          const timeout = server ? mcpTimeoutMs(server) : (config.raven_mcp.timeout ?? 600) * 1000
+          const requestOptions = { signal: context.abort, timeout }
+          let connected = false
+          let connection: McpConnection | undefined
+          try {
+            connection = await getMcpConnection(context.sessionID, args.server, context.abort)
+            connected = true
+            connection.active++
+            connection.lastUsed = Date.now()
+            const client = connection.client
+
+            if (operation === "list_tools") {
+              const tools = await listAllMcpTools(client, requestOptions)
+              const match = getOnDemandMcpServer(args.server)
+              if (match) {
+                const [name] = match
+                const generatedTools = generatedToolsFromMcpTools(tools)
+                mcpMetadata[name] = {
+                  autoGeneratedTools: generatedTools,
+                  autoGeneratedDescription: mcpMetadata[name]?.autoGeneratedDescription || synthesizeMcpDescription(name, generatedTools),
+                  avoidedSchemaBytes: estimateAvoidedMcpSchemaBytes(tools),
+                  status: "ready",
+                  lastCheckedAt: new Date().toISOString(),
+                }
+                saveMcpMetadata(mcpMetadata)
+                saveDynamicGuidance()
+              }
+              return { title: `Raven MCP: ${args.server}`, output: formatMcpToolsForRaven(args.server, tools) }
+            }
+
+            if (operation === "call_tool") {
+              if (!args.name) return { title: `Raven MCP: ${args.server}`, output: "call_tool requires name." }
+              const result = await client.callTool({ name: args.name, arguments: parseMcpArguments(args.argumentsJson) }, undefined, requestOptions)
+              setOnDemandMcpHealth(args.server, "ready")
+              return { title: `Raven MCP: ${args.server}.${args.name}`, output: formatMcpResult(result) }
+            }
+
+            if (operation === "list_resources") {
+              const resources = await listAllMcpResources(client, requestOptions)
+              setOnDemandMcpHealth(args.server, "ready")
+              return { title: `Raven MCP: ${args.server}`, output: formatMcpList(`Resources for ${args.server}`, resources, ["uri", "name", "description"]) }
+            }
+
+            if (operation === "read_resource") {
+              if (!args.name) return { title: `Raven MCP: ${args.server}`, output: "read_resource requires name as the resource URI." }
+              const result = await client.readResource({ uri: args.name }, requestOptions)
+              setOnDemandMcpHealth(args.server, "ready")
+              return { title: `Raven MCP: ${args.server}`, output: formatMcpResult(result) }
+            }
+
+            if (operation === "list_prompts") {
+              const prompts = await listAllMcpPrompts(client, requestOptions)
+              setOnDemandMcpHealth(args.server, "ready")
+              return { title: `Raven MCP: ${args.server}`, output: formatMcpList(`Prompts for ${args.server}`, prompts) }
+            }
+
+            if (operation === "get_prompt") {
+              if (!args.name) return { title: `Raven MCP: ${args.server}`, output: "get_prompt requires name." }
+              const result = await client.getPrompt({ name: args.name, arguments: parseMcpArguments(args.argumentsJson) }, requestOptions)
+              setOnDemandMcpHealth(args.server, "ready")
+              return { title: `Raven MCP: ${args.server}.${args.name}`, output: formatMcpResult(result) }
+            }
+
+            return { title: `Raven MCP: ${args.server}`, output: `Unsupported operation: ${operation}` }
+          } catch (err: any) {
+            if (!connected && !context.abort.aborted) {
+              const name = setOnDemandMcpHealth(args.server, "failed", err?.message ?? err)
+              if (name) await notifyIfMcpFailures([name])
+            }
+            return { title: `Raven MCP: ${args.server}`, output: `MCP call failed: ${err?.message ?? err}` }
+          } finally {
+            if (connection) {
+              connection.active = Math.max(0, connection.active - 1)
+              connection.lastUsed = Date.now()
+            }
+          }
+        },
+      }),
+    },
+
+    // Track agent ↔ session mapping for allowlist + Raven exclusion
+    async "chat.message"(input: any, _output: any) {
+      if (input.agent) {
+        sessionAgents.set(input.sessionID, input.agent)
+        if (input.agent === "raven") {
+          ravenSessions.add(input.sessionID)
+          ravenSessionKinds.set(input.sessionID, "seek")
+        } else if (input.agent === "raven-mcp") {
+          ravenSessions.add(input.sessionID)
+          ravenSessionKinds.set(input.sessionID, "mcp")
+        }
+      }
+    },
+
+    async event(input: { event: any }) {
+      // Track subagent session → parent mapping for accurate context counting
+      const evt = input.event
+      if (evt?.type === "session.created") {
+        const info = evt.properties?.info
+        if (info?.parentID && info?.id) ravenSessionParents.set(info.parentID, info.id)
+      }
+      if (evt?.type === "session.deleted") {
+        const sessionId = evt.properties?.info?.id
+        if (sessionId) {
+          ravenSessions.delete(sessionId)
+          ravenSessionKinds.delete(sessionId)
+          activeRavenPrompts.delete(sessionId)
+          sessionAgents.delete(sessionId)
+          clearRavenWaiters(sessionId)
+          for (const [parentId, childId] of ravenSessionParents) {
+            if (parentId === sessionId || childId === sessionId) ravenSessionParents.delete(parentId)
+          }
+          await closeMcpConnectionsForSession(sessionId)
+        }
+      }
+      if (evt?.type === "message.updated") {
+        const info = evt.properties?.info
+        if (info?.role === "assistant" && info?.sessionID && info.error && ravenSessions.has(info.sessionID)) {
+          reportRavenProviderError(info.sessionID, info.error)
+        }
+      }
+      if (evt?.type === "message.part.updated") {
+        const part = evt.properties?.part
+        if (part?.sessionID && ravenSessions.has(part.sessionID)) {
+          if (part.type === "retry" && part.error) {
+            reportRavenProviderError(part.sessionID, part.error)
+          } else {
+            reportRavenProgress(part.sessionID)
+          }
+        }
+      }
+      if (evt?.type === "session.status") {
+        const sessionId = evt.properties?.sessionID
+        const status = evt.properties?.status
+        if (sessionId && ravenSessions.has(sessionId)) {
+          if (status?.type === "retry") {
+            reportRavenProviderError(sessionId, { name: "RetryError", data: { message: status.message } })
+          }
+        }
+      }
+      if (evt?.type === "session.error") {
+        const sessionId = evt.properties?.sessionID
+        if (sessionId && evt.properties?.error && ravenSessions.has(sessionId)) {
+          reportRavenProviderError(sessionId, evt.properties.error)
+        }
+      }
+
+      await refreshModelsIfPending()
+
+      if (updateToastPending) {
+        updateToastPending = false
+        setTimeout(() => void notifyIfUpdateAvailable(), 500)
+      }
+      if (mcpFailureToastPending) {
+        mcpFailureToastPending = false
+        void scheduleOnDemandMcpRefresh().then((result) => notifyIfMcpFailures(result.failed))
+      }
+      if (duplicateMcpToastPending) {
+        duplicateMcpToastPending = false
+        setTimeout(() => void notifyIfDuplicateMcps(), 700)
+      }
+      if (modelSetupToastPending) {
+        modelSetupToastPending = false
+        setTimeout(() => void notifyIfModelSetupRequired(), 300)
+      }
+    },
+
+    // /raven help|route|seek ...|mcp ...|update|stats|status
+    async "command.execute.before"(input: any, output: any) {
+      if (input.command !== "raven") return
+      output.parts.length = 0
+      const raw = input.arguments.trim()
+      const arg = raw.toLowerCase()
+      if (!arg) await refreshModelsIfPending()
+
+      if (arg === "help") {
+        output.parts.push({ type: "text", text: helpText() })
+      } else if (arg === "stats") {
+        output.parts.push({ type: "text", text: statsText() })
+      } else if (arg === "route") {
+        output.parts.push({ type: "text", text: `${routeSummary()}\n\nUsage:\n  /raven route tool add <tool_name>\n  /raven route tool remove <tool_name>\n  /raven route keyword add <keyword>\n  /raven route keyword remove <keyword>\n\nGlobal MCPs are auto-routed by detected OpenCode MCP server name.` })
+      } else if (arg.startsWith("route ")) {
+        const parts = raw.split(/\s+/)
+        const kind = parts[1]?.toLowerCase()
+        const action = parts[2]?.toLowerCase()
+        const name = parts.slice(3).join(" ").trim()
+        const key = kind === "tool" ? "routeTools" : kind === "keyword" ? "routeToolKeywords" : undefined
+
+        if (!key || !["add", "remove", "rm"].includes(action) || !name) {
+          output.parts.push({ type: "text", text: "Usage:\n  /raven route tool add <tool_name>\n  /raven route tool remove <tool_name>\n  /raven route keyword add <keyword>\n  /raven route keyword remove <keyword>\n\nGlobal MCPs are auto-routed by detected OpenCode MCP server name." })
+        } else {
+          updateConfig((latest) => {
+            const values = uniqueStrings(latest.raven_seek[key])
+            const exists = values.some((value) => value.toLowerCase() === name.toLowerCase())
+            const next = action === "add"
+              ? exists ? values : [...values, name]
+              : values.filter((value) => value.toLowerCase() !== name.toLowerCase())
+            return { raven_seek: key === "routeTools" ? { routeTools: next } : { routeToolKeywords: next } }
+          })
+          output.parts.push({ type: "text", text: routeSummary() })
+        }
+      } else if (arg.startsWith("seek ")) {
+        const parts = raw.split(/\s+/)
+        const action = parts[1]?.toLowerCase()
+        const value = parts.slice(2).join(" ").trim()
+        if (action === "model" && value) {
+          if (value.toLowerCase() === "auto") {
+            updateConfig({ raven_seek: { model: undefined, autoSelectedModel: undefined } })
+            await ensureRavenModels()
+          } else {
+            updateConfig({ raven_seek: { model: value, autoSelectedModel: undefined } })
+          }
+          delete ravenProviderIssues.seek
+          output.parts.push({ type: "text", text: config.raven_seek.model
+            ? `Raven Search model set to: ${modelLabel(config.raven_seek)}\nRestart opencode for the change to take effect.`
+            : modelSetupInstructions("seek") })
+        } else if (action === "effort" && value) {
+          updateConfig({ raven_seek: { reasoning_effort: value } })
+          output.parts.push({ type: "text", text: `Raven Search reasoning effort set to: ${value}\nRestart opencode for the change to take effect.` })
+        } else if (action === "timeout") {
+          const seconds = Number(value)
+          if (!Number.isInteger(seconds) || seconds < 10 || seconds > MAX_TIMEOUT_SECONDS) {
+            output.parts.push({ type: "text", text: `Usage: /raven seek timeout <seconds>\nMust be between 10 and ${MAX_TIMEOUT_SECONDS}. Current: ${config.raven_seek.timeout ?? 600}s` })
+          } else {
+            updateConfig({ raven_seek: { timeout: seconds } })
+            output.parts.push({ type: "text", text: `Raven Search timeout set to ${seconds}s. Takes effect immediately.` })
+          }
+        } else {
+          output.parts.push({ type: "text", text: "Usage:\n  /raven seek model <provider/model>\n  /raven seek effort <value>\n  /raven seek timeout <seconds>" })
+        }
+      } else if (arg === "mcp") {
+        output.parts.push({ type: "text", text: `${onDemandMcpStatus()}\n\nUsage:\n  /raven mcp refresh [server_name]\n  /raven mcp detail full\n  /raven mcp detail minimized` })
+      } else if (arg.startsWith("mcp ")) {
+        const parts = raw.split(/\s+/)
+        const action = parts[1]?.toLowerCase()
+        if (action === "refresh") {
+          const serverName = parts.slice(2).join(" ").trim() || undefined
+          const result = await queueOnDemandMcpRefresh(true, serverName)
+          await notifyIfMcpFailures(result.failed)
+          output.parts.push({
+            type: "text",
+            text: `On-demand MCP refresh complete.\n  Refreshed: ${result.refreshed.length ? result.refreshed.join(", ") : "none"}\n  Failed: ${result.failed.length ? result.failed.join(", ") : "none"}`,
+          })
+        } else if (action === "detail") {
+          const detail = parts[2]?.toLowerCase()
+          if (detail !== "full" && detail !== "minimized") {
+            output.parts.push({ type: "text", text: `Usage: /raven mcp detail full|minimized\nCurrent: ${config.raven_mcp.descriptionDetail ?? "full"}` })
+          } else {
+            updateConfig({ raven_mcp: { descriptionDetail: detail } })
+            output.parts.push({ type: "text", text: `On-demand MCP guidance detail set to: ${detail}\nRestart opencode for startup instructions/tool descriptions to fully refresh.` })
+          }
+        } else if (action === "model" && parts.slice(2).join(" ").trim()) {
+          const model = parts.slice(2).join(" ").trim()
+          if (model.toLowerCase() === "auto") {
+            updateConfig({ raven_mcp: { model: undefined, autoSelectedModel: undefined } })
+            await ensureRavenModels()
+          } else {
+            updateConfig({ raven_mcp: { model, autoSelectedModel: undefined } })
+          }
+          delete ravenProviderIssues.mcp
+          output.parts.push({ type: "text", text: config.raven_mcp.model
+            ? `Raven MCP model set to: ${modelLabel(config.raven_mcp)}\nRestart opencode for the change to take effect.`
+            : modelSetupInstructions("mcp") })
+        } else if (action === "effort" && parts.slice(2).join(" ").trim()) {
+          const effort = parts.slice(2).join(" ").trim()
+          updateConfig({ raven_mcp: { reasoning_effort: effort } })
+          output.parts.push({ type: "text", text: `Raven MCP reasoning effort set to: ${effort}\nRestart opencode for the change to take effect.` })
+        } else if (action === "timeout") {
+          const seconds = Number(parts[2])
+          if (!Number.isInteger(seconds) || seconds < 10 || seconds > MAX_TIMEOUT_SECONDS) {
+            output.parts.push({ type: "text", text: `Usage: /raven mcp timeout <seconds>\nMust be between 10 and ${MAX_TIMEOUT_SECONDS}. Current: ${config.raven_mcp.timeout ?? 600}s` })
+          } else {
+            updateConfig({ raven_mcp: { timeout: seconds } })
+            output.parts.push({ type: "text", text: `Raven MCP timeout set to ${seconds}s. Takes effect immediately.` })
+          }
+        } else {
+          output.parts.push({ type: "text", text: "Usage:\n  /raven mcp\n  /raven mcp refresh [server_name]\n  /raven mcp detail full|minimized\n  /raven mcp model <provider/model>\n  /raven mcp effort <value>\n  /raven mcp timeout <seconds>" })
+        }
+      } else if (arg === "update") {
+        try {
+          const info = await refreshUpdateInfo()
+          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\n${host === "v1" ? `Cleared ${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 {
+        const seek = config.raven_seek
+        const mcp = config.raven_mcp
+        const seekIssue = ravenProviderIssues.seek ? `\n  Provider issue: ${ravenProviderIssues.seek}` : ""
+        const mcpIssue = ravenProviderIssues.mcp ? `\n  Provider issue: ${ravenProviderIssues.mcp}` : ""
+        let update = "Update: unable to check npm."
+        try {
+          const info = await getUpdateInfo()
+          update = info.available && info.latest
+            ? `Update: ${info.latest} available. Run /raven update, then restart opencode.`
+            : info.latest
+              ? `Update: up to date (latest ${info.latest}).`
+              : "Update: unable to check npm."
+        } catch { /* keep fallback */ }
+        const setup = modelSetupInstructions()
+        output.parts.push({ type: "text", text: `Raven version: ${PACKAGE_VERSION}.\nSearch agent: ${modelLabel(seek)}. Reasoning: ${seek.reasoning_effort || fm.reasoning_effort || "(default)"}. Timeout: ${seek.timeout ?? 600}s.${seekIssue}\nMCP agent: ${modelLabel(mcp)}. Reasoning: ${mcp.reasoning_effort || mcpFm.reasoning_effort || "(default)"}. Timeout: ${mcp.timeout ?? 600}s.${mcpIssue}\n${update}${setup ? `\n\n${setup}` : ""}\n\n${routeSummary()}\n\n${mcpSummary()}\n\n${statsText()}\n\nRun /raven help for commands.` })
+      }
+    },
+
+    async "tool.execute.before"(input: any, output: any) {
+      if ((input.tool === "raven_seek" || input.tool === "raven_mcp") && ravenSessions.has(input.sessionID)) {
+        throw new Error(`${input.tool} cannot be called from inside a Raven agent. Use that agent's direct tools instead.`)
+      }
+
+      if (input.tool === "raven_mcp_bridge" && ravenSessionKinds.get(input.sessionID) !== "mcp" && sessionAgents.get(input.sessionID) !== "raven-mcp") {
+        throw new Error("raven_mcp_bridge is only available inside the Raven MCP agent. Use raven_mcp for on-demand MCP requests.")
+      }
+
+      if (ravenSessions.has(input.sessionID)) return
+      if (isExcluded(sessionAgents.get(input.sessionID))) return
+      if (config.raven_seek.excludeTools?.some((name) => name.toLowerCase() === input.tool.toLowerCase())) return
+
+      if ((input.tool === "task" || input.tool === "subagent") && (output.args?.subagent_type ?? output.args?.agent) === "raven") {
+        ravenTaskCalls.add(input.callID)
+      }
+
+      // ── Block routed tools/MCPs for non-Raven agents ──
+      const shouldRouteTool = input.tool === "bash" || input.tool === "shell" ? false : isRouteConfigured(input.tool)
+      const isSearchBashCmd = isRouteConfigured(input.tool) && isSearchBash(input.tool, output.args || input.args)
+
+      if (shouldRouteTool || isSearchBashCmd) {
+        const args = compactArgs(output.args || input.args)
+        if (output.args && typeof output.args === "object") output.args = args
+        throw new Error(rerouteMessage(input.tool, args))
+      }
+    },
+
+    async "tool.execute.after"(input: any, output: any) {
+      if (ravenTaskCalls.has(input.callID)) {
+        ravenTaskCalls.delete(input.callID)
+        // Try task metadata first (built-in tools preserve metadata)
+        const ravenSessionId = output.metadata?.sessionId ?? ravenSessionParents.get(input.sessionID)
+        if (ravenSessionId) {
+          if (ravenSessionParents.has(input.sessionID)) ravenSessionParents.delete(input.sessionID)
+          void countRavenSavedCandidateBytes(ravenSessionId)
+            .then((total) => {
+              const saved = Math.max(0, total - String(output.output ?? "").length)
+              if (saved > 0) addBytes(saved)
+            })
+            .catch(() => {
+              // Without token metadata we cannot separate saved context from the compact answer.
+            })
+        }
+      }
+    },
+  }
+})