opencode-raven 2.3.0 → 2.3.1

package/v2.ts

@@ -1,331 +1,353 @@
-import type { Plugin, Agent } from "@opencode/plugin"
-import type { PluginInput, Hooks, ToolContext as V1ToolContext } from "@opencode-ai/plugin"
-import type { SessionMessageInfo, SessionInfo } from "@opencode/client"
-import { z } from "zod"
-import createRavenRuntime from "./raven-core"
-import { RavenRpc } from "./rpc"
-
-type Context = Plugin.Context
-type RequestOptions = NonNullable<Parameters<Context["session"]["get"]>[1]>
-type Runtime = Awaited<ReturnType<typeof createRavenRuntime>>
-type Registration = { dispose(): Promise<void> }
-type Call = { path?: { id: string }; body?: Record<string, any>; signal?: AbortSignal }
-type AgentDefinition = {
-  description: string
-  mode: "subagent"
-  hidden: boolean
-  disable: boolean
-  model?: string
-  options: Record<string, unknown>
-  permission: Record<string, "allow" | "deny" | "ask">
-  prompt: string
-}
-
-function modelRef(value: string): NonNullable<Agent.Info["model"]> {
-  const slash = value.indexOf("/")
-  if (slash < 1 || slash === value.length - 1) throw new Error(`Invalid Raven model: ${value}`)
-  const [id, variant] = value.slice(slash + 1).split("#")
-  if (!id || value.slice(0, slash).includes("#") || value.split("#").length > 2 || (variant !== undefined && !variant)) throw new Error(`Invalid Raven model: ${value}`)
-  return { providerID: value.slice(0, slash), id, ...(variant ? { variant } : {}) } as NonNullable<Agent.Info["model"]>
-}
-
-function legacyError(error: { type: string; message: string; status?: number; response?: { body: string } }) {
-  return { name: error.type, data: { message: error.message, statusCode: error.status, responseBody: error.response?.body } }
-}
-
-// V2 projects messages directly, rather than wrapping them in { info, parts }.
-// Preserve agent switches when validating persisted continuation history.
-function legacyMessages(messages: readonly SessionMessageInfo[], session: SessionInfo) {
-  let agent = typeof session.metadata?.opencodeRavenAgent === "string"
-    ? session.metadata.opencodeRavenAgent : session.agent
-  const currentAgentMatches = session.agent === agent
-  return messages.map((message) => {
-    if (message.type === "agent-switched") agent = message.agent
-    if (message.type === "assistant") {
-      return { info: { ...message, role: "assistant" }, parts: message.content }
-    }
-    return {
-      info: { ...message, role: message.type, agent: currentAgentMatches ? agent : session.agent },
-      parts: message.type === "user" ? [{ type: "text", text: message.text }] : [],
-    }
-  })
-}
-
-export async function setupRaven(ctx: Context): Promise<Plugin.Cleanup> {
-  const registrations: Registration[] = []
-  const controller = new AbortController()
-  const location = { directory: ctx.location.directory }
-  const agents: Record<string, AgentDefinition> = {}
-  const activeSessions = new Set<string>()
-  let emitNotice: (notice: z.infer<typeof RavenRpc.events.notice.schema>) => Promise<void> = async () => {}
-  let runtime: Runtime | undefined
-  let startupTimer: ReturnType<typeof setTimeout> | undefined
-  let eventPump: Promise<void> | undefined
-  let disposed = false
-
-  const requestOptions = (call: Call): RequestOptions => ({ signal: call.signal ? AbortSignal.any([call.signal, controller.signal]) : controller.signal })
-
-  // Adapt only the host boundary. Raven's MCP transports, state, timeout logic,
-  // command parser, and continuation validation remain shared with v1.
-  const client = {
-    provider: {
-      async list(call: Call) {
-        const response = await ctx.model.list({ location }, requestOptions(call))
-        const models = response.data.filter((model) => model.providerID === "opencode" && model.enabled)
-        return { data: {
-          connected: models.length ? ["opencode"] : [],
-          all: [{ id: "opencode", models: Object.fromEntries(models.map((model) => [model.id, {
-            id: model.id,
-            status: model.status,
-            release_date: new Date(model.time.released).toISOString(),
-            tool_call: model.capabilities.tools,
-            cost: model.cost.length && model.cost.every((tier) => tier.input === 0 && tier.output === 0)
-              ? { input: 0, output: 0 } : { input: 1, output: 1 },
-            limit: model.limit,
-          }])) }],
-        } }
-      },
-    },
-    session: {
-      async get(call: Call) {
-        return { data: await ctx.session.get({ sessionID: call.path!.id }, requestOptions(call)) }
-      },
-      async create(call: Call) {
-        const agent = String(call.body!.agent)
-        const definition = agents[agent]
-        if (!definition?.model) throw new Error(`Raven agent ${agent} has no configured model`)
-        return { data: await ctx.session.create({
-          parentID: call.body!.parentID,
-          title: call.body!.title,
-          agent,
-          model: modelRef(definition.model),
-          location,
-          metadata: { opencodeRavenAgent: agent },
-        }, requestOptions(call)) }
-      },
-      async update(call: Call) {
-        await ctx.session.update({ sessionID: call.path!.id, title: call.body!.title }, requestOptions(call))
-      },
-      async messages(call: Call) {
-        const sessionID = call.path!.id
-        const options = requestOptions(call)
-        const [messages, session] = await Promise.all([
-          ctx.session.context({ sessionID }, options), ctx.session.get({ sessionID }, options),
-        ])
-        return { data: legacyMessages(messages, session) }
-      },
-      async abort(call: Call) {
-        await ctx.session.interrupt({ sessionID: call.path!.id, resume: false }, requestOptions(call))
-      },
-      async prompt(call: Call) {
-        const sessionID = call.path!.id
-        const options = requestOptions(call)
-        const session = await ctx.session.get({ sessionID }, options)
-        if (session.agent !== call.body!.agent) throw new Error("Raven session agent changed; start a new retrieval")
-        activeSessions.add(sessionID)
-        try {
-          const previousIDs = new Set((await ctx.session.context({ sessionID }, options)).map((message) => message.id))
-          const admitted = await ctx.session.prompt({
-            sessionID,
-            text: call.body!.parts.map((part: { text: string }) => part.text).join("\n"),
-            delivery: "queue",
-          }, options)
-          // Admission is not completion. Wait for idle, then read only this turn's
-          // final assistant message; a follow-up must never return an older answer.
-          await ctx.session.wait({ sessionID }, options)
-          options.signal?.throwIfAborted()
-          const [messages, completed] = await Promise.all([
-            ctx.session.context({ sessionID }, options), ctx.session.get({ sessionID }, options),
-          ])
-          const boundary = messages.findIndex((message) => message.id === admitted.id)
-          // Compaction may remove the admitted user message from active context.
-          // In that case, only newly projected messages can belong to this turn.
-          const candidates = boundary >= 0 ? messages.slice(boundary + 1) : messages.filter((message) => !previousIDs.has(message.id))
-          const nextUser = candidates.findIndex((message) => message.type === "user")
-          const turn = nextUser < 0 ? candidates : candidates.slice(0, nextUser)
-          const failed = turn.find((message) => message.type === "assistant" && (message.error || message.retry))
-          if (failed?.type === "assistant") throw new Error(JSON.stringify(legacyError(failed.error ?? failed.retry!.error)))
-          if (completed.outcome === "failed" || completed.outcome === "interrupted") {
-            throw new Error(`Raven execution ${completed.outcome}; no completed answer is available`)
-          }
-          const answer = turn.filter((message) => message.type === "assistant").at(-1)
-          if (answer?.type !== "assistant") {
-            throw new Error(`Raven finished without an assistant answer (${completed.outcome ?? "unknown outcome"})`)
-          }
-          return { data: { parts: answer.content } }
-        } finally {
-          activeSessions.delete(sessionID)
-        }
-      },
-    },
-    tui: {
-      async showToast({ body }: { body: { title?: string; message: string; variant?: "info" | "warning"; duration?: number } }) {
-        if (disposed) return
-        await emitNotice({ kind: "toast", ...body })
-      },
-    },
-  }
-
-  const cleanup = async () => {
-    if (disposed) return
-    disposed = true
-    const running = [...activeSessions]
-    controller.abort()
-    if (startupTimer) clearTimeout(startupTimer)
-    await Promise.allSettled(running.map((sessionID) => ctx.session.interrupt({ sessionID, resume: false }, { signal: AbortSignal.timeout(5000) })))
-    await Promise.allSettled(registrations.reverse().map((registration) => registration.dispose()))
-    await runtime?.dispose()
-    await eventPump
-  }
-
-  try {
-    runtime = await createRavenRuntime({
-      client: client as unknown as PluginInput["client"],
-      directory: ctx.location.directory,
-      project: { id: ctx.location.project.id },
-    }, "v2")
-    const raven = runtime
-    const mcp = await ctx.mcp.list({ location }, { signal: controller.signal })
-    const config = {
-      mcp: Object.fromEntries(mcp.data.map((server) => [server.name, { enabled: server.status.status !== "disabled" }])),
-      agent: agents,
-      instructions: [] as string[],
-    }
-    await raven.config(config)
-    registrations.push(await ctx.mcp.transform((editor) => {
-      raven.globalMcpRouting(editor.list().filter(([, server]) => !server.disabled).map(([name]) => name))
-    }))
-
-    async function executeCommand(raw: string) {
-      const output = { parts: [] as Array<{ type: string; text: string }> }
-      await raven["command.execute.before"]({ command: "raven", arguments: raw, sessionID: "" }, output)
-      return { text: output.parts.map((part) => part.text).join("\n") }
-    }
-    const rpc = await ctx.rpc.register(RavenRpc, { command: async ({ arguments: raw }) => executeCommand(raw) })
-    registrations.push(rpc)
+import type { Plugin, Agent } from "@opencode/plugin"
+import type { PluginInput, Hooks, ToolContext as V1ToolContext } from "@opencode-ai/plugin"
+import type { SessionMessageInfo, SessionInfo } from "@opencode/client"
+import { z } from "zod"
+import createRavenRuntime from "./raven-core"
+import { RavenRpc, mcpRefreshArguments, mcpRefreshToast } from "./rpc"
+
+type Context = Plugin.Context
+type RequestOptions = NonNullable<Parameters<Context["session"]["get"]>[1]>
+type Runtime = Awaited<ReturnType<typeof createRavenRuntime>>
+type Registration = { dispose(): Promise<void> }
+type Call = { path?: { id: string }; body?: Record<string, any>; signal?: AbortSignal }
+type AgentDefinition = {
+  description: string
+  mode: "subagent"
+  hidden: boolean
+  disable: boolean
+  model?: string
+  options: Record<string, unknown>
+  permission: Record<string, "allow" | "deny" | "ask">
+  prompt: string
+}
+
+function modelRef(value: string): NonNullable<Agent.Info["model"]> {
+  const slash = value.indexOf("/")
+  if (slash < 1 || slash === value.length - 1) throw new Error(`Invalid Raven model: ${value}`)
+  const [id, variant] = value.slice(slash + 1).split("#")
+  if (!id || value.slice(0, slash).includes("#") || value.split("#").length > 2 || (variant !== undefined && !variant)) throw new Error(`Invalid Raven model: ${value}`)
+  return { providerID: value.slice(0, slash), id, ...(variant ? { variant } : {}) } as NonNullable<Agent.Info["model"]>
+}
+
+function legacyError(error: { type: string; message: string; status?: number; response?: { body: string } }) {
+  return { name: error.type, data: { message: error.message, statusCode: error.status, responseBody: error.response?.body } }
+}
+
+// V2 projects messages directly, rather than wrapping them in { info, parts }.
+// Preserve agent switches when validating persisted continuation history.
+function legacyMessages(messages: readonly SessionMessageInfo[], session: SessionInfo) {
+  let agent = typeof session.metadata?.opencodeRavenAgent === "string"
+    ? session.metadata.opencodeRavenAgent : session.agent
+  const currentAgentMatches = session.agent === agent
+  return messages.map((message) => {
+    if (message.type === "agent-switched") agent = message.agent
+    if (message.type === "assistant") {
+      return { info: { ...message, role: "assistant" }, parts: message.content }
+    }
+    return {
+      info: { ...message, role: message.type, agent: currentAgentMatches ? agent : session.agent },
+      parts: message.type === "user" ? [{ type: "text", text: message.text }] : [],
+    }
+  })
+}
+
+export async function setupRaven(ctx: Context): Promise<Plugin.Cleanup> {
+  const registrations: Registration[] = []
+  const controller = new AbortController()
+  const location = { directory: ctx.location.directory }
+  const agents: Record<string, AgentDefinition> = {}
+  const activeSessions = new Set<string>()
+  let emitNotice: (notice: z.infer<typeof RavenRpc.events.notice.schema>) => Promise<void> = async () => {}
+  let runtime: Runtime | undefined
+  let startupTimer: ReturnType<typeof setTimeout> | undefined
+  let eventPump: Promise<void> | undefined
+  let disposed = false
+
+  const requestOptions = (call: Call): RequestOptions => ({ signal: call.signal ? AbortSignal.any([call.signal, controller.signal]) : controller.signal })
+
+  // Adapt only the host boundary. Raven's MCP transports, state, timeout logic,
+  // command parser, and continuation validation remain shared with v1.
+  const client = {
+    provider: {
+      async list(call: Call) {
+        const response = await ctx.model.list({ location }, requestOptions(call))
+        const models = response.data.filter((model) => model.providerID === "opencode" && model.enabled)
+        return { data: {
+          connected: models.length ? ["opencode"] : [],
+          all: [{ id: "opencode", models: Object.fromEntries(models.map((model) => [model.id, {
+            id: model.id,
+            status: model.status,
+            release_date: new Date(model.time.released).toISOString(),
+            tool_call: model.capabilities.tools,
+            cost: model.cost.length && model.cost.every((tier) => tier.input === 0 && tier.output === 0)
+              ? { input: 0, output: 0 } : { input: 1, output: 1 },
+            limit: model.limit,
+          }])) }],
+        } }
+      },
+    },
+    session: {
+      async get(call: Call) {
+        return { data: await ctx.session.get({ sessionID: call.path!.id }, requestOptions(call)) }
+      },
+      async create(call: Call) {
+        const agent = String(call.body!.agent)
+        const definition = agents[agent]
+        if (!definition?.model) throw new Error(`Raven agent ${agent} has no configured model`)
+        return { data: await ctx.session.create({
+          parentID: call.body!.parentID,
+          title: call.body!.title,
+          agent,
+          model: modelRef(definition.model),
+          location,
+          metadata: { opencodeRavenAgent: agent },
+        }, requestOptions(call)) }
+      },
+      async update(call: Call) {
+        await ctx.session.update({ sessionID: call.path!.id, title: call.body!.title }, requestOptions(call))
+      },
+      async messages(call: Call) {
+        const sessionID = call.path!.id
+        const options = requestOptions(call)
+        const [messages, session] = await Promise.all([
+          ctx.session.context({ sessionID }, options), ctx.session.get({ sessionID }, options),
+        ])
+        return { data: legacyMessages(messages, session) }
+      },
+      async abort(call: Call) {
+        await ctx.session.interrupt({ sessionID: call.path!.id, resume: false }, requestOptions(call))
+      },
+      async prompt(call: Call) {
+        const sessionID = call.path!.id
+        const options = requestOptions(call)
+        const session = await ctx.session.get({ sessionID }, options)
+        if (session.agent !== call.body!.agent) throw new Error("Raven session agent changed; start a new retrieval")
+        activeSessions.add(sessionID)
+        try {
+          const previousIDs = new Set((await ctx.session.context({ sessionID }, options)).map((message) => message.id))
+          const admitted = await ctx.session.prompt({
+            sessionID,
+            text: call.body!.parts.map((part: { text: string }) => part.text).join("\n"),
+            delivery: "queue",
+          }, options)
+          // Admission is not completion. Wait for idle, then read only this turn's
+          // final assistant message; a follow-up must never return an older answer.
+          await ctx.session.wait({ sessionID }, options)
+          options.signal?.throwIfAborted()
+          const [messages, completed] = await Promise.all([
+            ctx.session.context({ sessionID }, options), ctx.session.get({ sessionID }, options),
+          ])
+          const boundary = messages.findIndex((message) => message.id === admitted.id)
+          // Compaction may remove the admitted user message from active context.
+          // In that case, only newly projected messages can belong to this turn.
+          const candidates = boundary >= 0 ? messages.slice(boundary + 1) : messages.filter((message) => !previousIDs.has(message.id))
+          const nextUser = candidates.findIndex((message) => message.type === "user")
+          const turn = nextUser < 0 ? candidates : candidates.slice(0, nextUser)
+          const failed = turn.find((message) => message.type === "assistant" && (message.error || message.retry))
+          if (failed?.type === "assistant") throw new Error(JSON.stringify(legacyError(failed.error ?? failed.retry!.error)))
+          if (completed.outcome === "failed" || completed.outcome === "interrupted") {
+            throw new Error(`Raven execution ${completed.outcome}; no completed answer is available`)
+          }
+          const answer = turn.filter((message) => message.type === "assistant").at(-1)
+          if (answer?.type !== "assistant") {
+            throw new Error(`Raven finished without an assistant answer (${completed.outcome ?? "unknown outcome"})`)
+          }
+          return { data: { parts: answer.content } }
+        } finally {
+          activeSessions.delete(sessionID)
+        }
+      },
+    },
+    tui: {
+      async showToast({ body }: { body: { title?: string; message: string; variant?: "info" | "warning"; duration?: number } }) {
+        if (disposed) return
+        await emitNotice({ kind: "toast", ...body })
+      },
+    },
+  }
+
+  const cleanup = async () => {
+    if (disposed) return
+    disposed = true
+    const running = [...activeSessions]
+    controller.abort()
+    if (startupTimer) clearTimeout(startupTimer)
+    await Promise.allSettled(running.map((sessionID) => ctx.session.interrupt({ sessionID, resume: false }, { signal: AbortSignal.timeout(5000) })))
+    await Promise.allSettled(registrations.reverse().map((registration) => registration.dispose()))
+    await runtime?.dispose()
+    await eventPump
+  }
+
+  try {
+    runtime = await createRavenRuntime({
+      client: client as unknown as PluginInput["client"],
+      directory: ctx.location.directory,
+      project: { id: ctx.location.project.id },
+    }, "v2")
+    const raven = runtime
+    const mcp = await ctx.mcp.list({ location }, { signal: controller.signal })
+    const config = {
+      mcp: Object.fromEntries(mcp.data.map((server) => [server.name, { enabled: server.status.status !== "disabled" }])),
+      agent: agents,
+      instructions: [] as string[],
+    }
+    await raven.config(config)
+    registrations.push(await ctx.mcp.transform((editor) => {
+      raven.globalMcpRouting(editor.list().filter(([, server]) => !server.disabled).map(([name]) => name))
+    }))
+
+    async function executeCommand(raw: string) {
+      const output = { parts: [] as Array<{ type: string; text: string }> }
+      await raven["command.execute.before"]({ command: "raven", arguments: raw, sessionID: "" }, output)
+      return { text: output.parts.map((part) => part.text).join("\n") }
+    }
+    const rpc = await ctx.rpc.register(RavenRpc, {
+      command: async ({ arguments: raw }) => executeCommand(raw),
+      refreshMcps: async ({ serverName }) => raven.refreshMcps(serverName),
+    })
+    registrations.push(rpc)
     emitNotice = (notice) => rpc.events.emit("notice", notice)
 
-    registrations.push(await ctx.agent.transform((editor) => {
-      for (const [id, definition] of Object.entries(agents)) {
-        if (definition.disable) { editor.remove(id); continue }
-        // The shipped registry upserts on update, including previously absent IDs.
-        editor.update(id, (agent) => {
-          agent.name = id as Agent.Name
-          agent.description = definition.description
-          agent.mode = definition.mode
-          agent.hidden = definition.hidden
-          agent.model = definition.model ? modelRef(definition.model) : undefined
-          agent.system = definition.prompt
-          agent.request.body = { ...definition.options }
-          agent.permissions = Object.entries(definition.permission).map(([action, effect]) => ({
-            action: action === "bash" ? "shell" : action === "task" ? "subagent" : action,
-            resource: "*", effect,
-          }))
-        })
-      }
-    }))
-
-    const tools: NonNullable<Hooks["tool"]> = raven.tool
-    registrations.push(await ctx.tool.transform((editor) => {
-      for (const [name, definition] of Object.entries(tools)) {
-        const schema = z.object(definition.args)
-        editor.add({
-          name, description: definition.description,
-          input: z.toJSONSchema(schema),
-          options: { permission: name, codemode: false },
-          async execute(input, context) {
-            await raven["chat.message"]({ sessionID: context.sessionID, agent: context.agent }, {})
-            await raven["tool.execute.before"]({ tool: name, sessionID: context.sessionID, callID: context.id }, { args: input })
-            let metadata: Record<string, unknown> = {}
-            let progress = Promise.resolve()
-            const legacyContext: V1ToolContext = {
-              sessionID: context.sessionID, messageID: context.messageID, agent: context.agent,
-              directory: ctx.location.directory, worktree: ctx.location.project.directory,
-              abort: AbortSignal.any([context.signal, controller.signal]),
-              metadata(update) {
-                metadata = { ...metadata, ...update.metadata, ...(update.title ? { title: update.title } : {}) }
-                progress = progress.then(() => context.progress(metadata)).catch(() => {})
-              },
-              async ask() { throw new Error("Raven tools do not request additional permissions") },
-            }
-            const result = await definition.execute(schema.parse(input), legacyContext)
-            await progress
-            return typeof result === "string" ? { content: result } : {
-              content: result.output,
-              metadata: { ...metadata, ...result.metadata, ...(result.title ? { title: result.title } : {}) },
-            }
-          },
-        })
+    // Delegation needs no extra confirmation. Preserve deny rules and leave
+    // child tools and the Raven-only MCP bridge's permissions unchanged.
+    registrations.push(await ctx.permission.hook("evaluate", (event) => {
+      if (event.effect === "ask" && (event.action === "raven_seek" || event.action === "raven_mcp")) {
+        event.effect = "allow"
       }
     }))
 
-    registrations.push(await ctx.tool.hook("execute.before", async (event) => {
-      await raven["chat.message"]({ sessionID: event.sessionID, agent: event.agent }, {})
-      const output = { args: event.input }
-      await raven["tool.execute.before"]({
-        ...event,
-        callID: event.id,
-      }, output)
-      event.input = output.args
-    }))
-    registrations.push(await ctx.tool.hook("execute.after", async (event) => {
-      if (event.status !== "completed") return
-      await raven["tool.execute.after"]({ ...event, callID: event.id }, {
-        metadata: event.result.metadata, output: event.result.content ?? "",
-      })
-    }))
-    registrations.push(await ctx.session.hook("context", async (event) => {
-      await raven["chat.message"]({ sessionID: event.sessionID, agent: event.agent }, {})
-      if (event.agent === "raven" || event.agent === "raven-mcp") return
-      event.system.push({ type: "text", text: raven.guidance() })
-    }))
-    registrations.push(await ctx.session.hook("retry", async (event) => {
-      await raven.event({ event: {
-        type: "session.error", properties: { sessionID: event.sessionID, error: legacyError(event.error) },
-      } })
-    }))
-    registrations.push(await ctx.command.transform((editor) => {
-      editor.add({
+    registrations.push(await ctx.agent.transform((editor) => {
+      for (const [id, definition] of Object.entries(agents)) {
+        if (definition.disable) { editor.remove(id); continue }
+        // The shipped registry upserts on update, including previously absent IDs.
+        editor.update(id, (agent) => {
+          agent.name = id as Agent.Name
+          agent.description = definition.description
+          agent.mode = definition.mode
+          agent.hidden = definition.hidden
+          agent.model = definition.model ? modelRef(definition.model) : undefined
+          agent.system = definition.prompt
+          agent.request.body = { ...definition.options }
+          agent.permissions = Object.entries(definition.permission).map(([action, effect]) => ({
+            action: action === "bash" ? "shell" : action === "task" ? "subagent" : action,
+            resource: "*", effect,
+          }))
+        })
+      }
+    }))
+
+    const tools: NonNullable<Hooks["tool"]> = raven.tool
+    registrations.push(await ctx.tool.transform((editor) => {
+      for (const [name, definition] of Object.entries(tools)) {
+        const schema = z.object(definition.args)
+        editor.add({
+          name, description: definition.description,
+          input: z.toJSONSchema(schema),
+          options: { permission: name, codemode: false },
+          async execute(input, context) {
+            await raven["chat.message"]({ sessionID: context.sessionID, agent: context.agent }, {})
+            await raven["tool.execute.before"]({ tool: name, sessionID: context.sessionID, callID: context.id }, { args: input })
+            let metadata: Record<string, unknown> = {}
+            let progress = Promise.resolve()
+            const legacyContext: V1ToolContext = {
+              sessionID: context.sessionID, messageID: context.messageID, agent: context.agent,
+              directory: ctx.location.directory, worktree: ctx.location.project.directory,
+              abort: AbortSignal.any([context.signal, controller.signal]),
+              metadata(update) {
+                metadata = { ...metadata, ...update.metadata, ...(update.title ? { title: update.title } : {}) }
+                progress = progress.then(() => context.progress(metadata)).catch(() => {})
+              },
+              async ask() { throw new Error("Raven tools do not request additional permissions") },
+            }
+            const result = await definition.execute(schema.parse(input), legacyContext)
+            await progress
+            return typeof result === "string" ? { content: result } : {
+              content: result.output,
+              metadata: { ...metadata, ...result.metadata, ...(result.title ? { title: result.title } : {}) },
+            }
+          },
+        })
+      }
+    }))
+
+    registrations.push(await ctx.tool.hook("execute.before", async (event) => {
+      await raven["chat.message"]({ sessionID: event.sessionID, agent: event.agent }, {})
+      const output = { args: event.input }
+      await raven["tool.execute.before"]({
+        ...event,
+        callID: event.id,
+      }, output)
+      event.input = output.args
+    }))
+    registrations.push(await ctx.tool.hook("execute.after", async (event) => {
+      if (event.status !== "completed") return
+      await raven["tool.execute.after"]({ ...event, callID: event.id }, {
+        metadata: event.result.metadata, output: event.result.content ?? "",
+      })
+    }))
+    registrations.push(await ctx.session.hook("context", async (event) => {
+      await raven["chat.message"]({ sessionID: event.sessionID, agent: event.agent }, {})
+      if (event.agent === "raven") return
+      event.system.push({ type: "text", text: event.agent === "raven-mcp" ? raven.mcpGuidance() : raven.guidance() })
+    }))
+    registrations.push(await ctx.session.hook("retry", async (event) => {
+      await raven.event({ event: {
+        type: "session.error", properties: { sessionID: event.sessionID, error: legacyError(event.error) },
+      } })
+    }))
+    registrations.push(await ctx.command.transform((editor) => {
+      editor.add({
         name: "raven", description: "Manage Raven routing, MCPs, models, timeouts, updates, and status",
         async execute({ sessionID, prompt }) {
-          const { text } = await executeCommand(prompt.text)
-          await emitNotice({ kind: "command", sessionID, message: text, title: "Raven" })
-        },
-      })
-    }))
-
-    eventPump = (async () => {
-      try {
-        for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
-          if (event.type === "model.updated") {
-            await raven.event({ event: { type: "raven.models.ready" } })
-          } else if (event.type === "session.created") {
-            const data = event.data
-            await raven.event({ event: { type: event.type, properties: { info: { ...data, id: data.sessionID } } } })
-          } else if (event.type === "session.deleted") {
-            const data = event.data
-            await raven.event({ event: { type: event.type, properties: { info: { id: data.sessionID } } } })
-          } else if (event.type === "session.execution.failed" || event.type === "session.retry.scheduled") {
-            const data = event.data
-            await raven.event({ event: { type: "session.error", properties: { sessionID: data.sessionID, error: legacyError(data.error) } } })
-          } else if (event.type === "session.text.delta" || event.type === "session.reasoning.delta" || event.type === "session.tool.input.delta" || event.type === "session.text.started" || event.type === "session.reasoning.started" || event.type === "session.tool.input.started") {
-            const data = event.data
-            await raven.event({ event: { type: "message.part.updated", properties: { part: { sessionID: data.sessionID, type: "text" } } } })
+          const refresh = mcpRefreshArguments(prompt.text)
+          if (refresh) {
+            await emitNotice({ kind: "toast", sessionID, title: "Raven MCP", message: `Refreshing ${refresh.serverName ?? "on-demand MCPs"}…`, variant: "info" })
+            try {
+              const result = await raven.refreshMcps(refresh.serverName)
+              await emitNotice({ kind: "toast", sessionID, ...mcpRefreshToast(result) })
+            } catch (error) {
+              await emitNotice({ kind: "toast", sessionID, title: "Raven MCP", message: `Refresh failed: ${String(error)}`, variant: "error" })
+            }
+            return
           }
-        }
-      } catch (error) {
-        if (!controller.signal.aborted) console.error("Raven event subscription failed:", error)
-      }
-    })()
-    await ctx.agent.reload()
-    await ctx.tool.reload()
-    await ctx.command.reload()
-    startupTimer = setTimeout(() => {
-      void raven.event({ event: { type: "raven.ready" } }).catch((error) => console.error("Raven startup failed:", error))
-    }, 3000)
-    return cleanup
-  } catch (error) {
-    await cleanup()
-    throw error
-  }
-}
+          const { text } = await executeCommand(prompt.text)
+          await emitNotice({ kind: "command", sessionID, message: text, title: "Raven" })
+        },
+      })
+    }))
+
+    eventPump = (async () => {
+      try {
+        for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+          if (event.type === "model.updated") {
+            await raven.event({ event: { type: "raven.models.ready" } })
+          } else if (event.type === "session.created") {
+            const data = event.data
+            await raven.event({ event: { type: event.type, properties: { info: { ...data, id: data.sessionID } } } })
+          } else if (event.type === "session.deleted") {
+            const data = event.data
+            await raven.event({ event: { type: event.type, properties: { info: { id: data.sessionID } } } })
+          } else if (event.type === "session.execution.failed" || event.type === "session.retry.scheduled") {
+            const data = event.data
+            await raven.event({ event: { type: "session.error", properties: { sessionID: data.sessionID, error: legacyError(data.error) } } })
+          } else if (event.type === "session.text.delta" || event.type === "session.reasoning.delta" || event.type === "session.tool.input.delta" || event.type === "session.text.started" || event.type === "session.reasoning.started" || event.type === "session.tool.input.started") {
+            const data = event.data
+            await raven.event({ event: { type: "message.part.updated", properties: { part: { sessionID: data.sessionID, type: "text" } } } })
+          }
+        }
+      } catch (error) {
+        if (!controller.signal.aborted) console.error("Raven event subscription failed:", error)
+      }
+    })()
+    await ctx.agent.reload()
+    await ctx.tool.reload()
+    await ctx.command.reload()
+    startupTimer = setTimeout(() => {
+      void raven.event({ event: { type: "raven.ready" } }).catch((error) => console.error("Raven startup failed:", error))
+    }, 3000)
+    return cleanup
+  } catch (error) {
+    await cleanup()
+    throw error
+  }
+}