refactor(core): use shared tool transform lifecycle

packages/core/src/plugin/host.ts

@@ -377,14 +377,8 @@ export const make = Effect.fn("PluginHost.make")(function* (plugin: Interface, p
       hook: (name, callback) => hooks.register("shell", name, callback),
     },
     tool: {
-      transform: (callback) =>
-        tools
-          .transform((draft) =>
-            callback({
-              add: (tool) => draft.add(tool),
-            }),
-          )
-          .pipe(Effect.as({ dispose: Effect.void })),
+      transform: tools.transform,
+      reload: tools.reload,
       hook: (name, callback) => hooks.register("tool", name, callback),
     },
     vcs: {

packages/core/src/tool.ts

@@ -4,7 +4,8 @@ export type { Context, Metadata, Options, Result } from "@opencode-ai/schema/too
 
 import { ToolDefinition, type ToolCall } from "@opencode-ai/ai"
 import { Tool } from "@opencode-ai/schema/tool"
-import { Context, Effect, Layer, Schema, SchemaIssue, Scope, Semaphore } from "effect"
+import type { ToolDraft } from "@opencode-ai/plugin/effect/tool"
+import { Context, Effect, Layer, Result, Schema, SchemaIssue, Types } from "effect"
 import { makeLocationNode } from "@opencode-ai/util/effect/app-node"
 import type { Agent } from "./agent.js"
 import { CodeModeCatalog } from "./codemode/catalog.js"
@@ -14,6 +15,7 @@ import { Permission } from "./permission.js"
 import { PluginHooks } from "./plugin/hooks.js"
 import { SessionMessage } from "./session/message.js"
 import { SessionSchema } from "./session/schema.js"
+import { State } from "./state.js"
 import { definition, execute, normalizeContent } from "./tool/runtime.js"
 import { Wildcard } from "./util/wildcard.js"
 
@@ -22,10 +24,7 @@ export class RegistrationError extends Schema.TaggedError<RegistrationError>()("
   message: Schema.String,
 }) {}
 
-export interface Interface {
-  readonly transform: (
-    callback: (draft: { readonly add: (tool: Tool.Info) => void }) => void,
-  ) => Effect.Effect<void, never, Scope.Scope>
+export interface Interface extends State.Transformable<ToolDraft> {
   readonly snapshot: (permissions?: Permission.Ruleset) => Effect.Effect<Snapshot>
 }
 
@@ -79,9 +78,6 @@ const layer = Layer.effect(
       ]
     })
 
-    const local = new Map<string, Array<{ readonly token: object; readonly tool: Tool.Info }>>()
-    const lock = Semaphore.makeUnsafe(1)
-
     const executeTool = Effect.fn("Tool.execute")(function* (
       tool: Tool.Info,
       name: string,
@@ -137,112 +133,123 @@ const layer = Layer.effect(
       }
     })
 
-    const transform: Interface["transform"] = Effect.fn("Tool.transform")(function* (callback) {
-      const tools: Array<Tool.Info> = []
-      yield* Effect.sync(() => callback({ add: (tool) => tools.push(tool) }))
-      const valid = yield* Effect.filter(normalizedEntries(tools), (entry) =>
-        Effect.gen(function* () {
-          if (entry.tool.options?.namespace !== undefined) yield* validateNamespace(entry.tool.options.namespace)
-          yield* validateName(normalizedName(entry.tool))
-          if (entry.tool.options?.codemode === false && entry.key === "execute")
-            return yield* new RegistrationError({
-              name: entry.key,
-              message: 'Tool name "execute" is reserved for CodeMode',
-            })
-          yield* Effect.try({
-            try: () => ToolDefinition.make(definition(entry.tool)),
-            catch: (error) =>
-              new RegistrationError({
-                name: entry.key,
-                message: `Invalid tool definition ${entry.key}: ${schemaMakeError(error)}`,
-              }),
-          })
-          return true
-        }).pipe(Effect.catchTag("Tool.RegistrationError", (error) => skipRegistration(entry.tool, error))),
-      )
-      // Reject every ambiguous entry rather than choosing a winner.
-      const entries = yield* Effect.filter(valid, (entry) => {
-        if (!valid.some((candidate) => candidate !== entry && candidate.key === entry.key)) return Effect.succeed(true)
-        return skipRegistration(
-          entry.tool,
-          new RegistrationError({ name: entry.key, message: `Duplicate normalized tool name: ${entry.key}` }),
-        )
-      })
-      if (entries.length === 0) return
-      yield* Effect.uninterruptible(
-        lock.withPermit(
-          Effect.gen(function* () {
-            const token = {}
-            for (const entry of entries)
-              local.set(entry.key, [...(local.get(entry.key) ?? []), { token, tool: entry.tool }])
-            yield* Effect.addFinalizer(() =>
-              lock.withPermit(
-                Effect.sync(() => {
-                  for (const entry of entries) {
-                    const remaining = local.get(entry.key)?.filter((item) => item.token !== token) ?? []
-                    if (remaining.length > 0) local.set(entry.key, remaining)
-                    else local.delete(entry.key)
-                  }
-                }),
-              ),
-            )
-          }),
+    const state = State.create({
+      name: "tool",
+      initial: () => ({
+        tools: new Map<string, Types.Mutable<Tool.Info>>(),
+        errors: new Array<{ tool: Tool.Info; error: RegistrationError }>(),
+      }),
+      draft: (data) => data,
+      finalize: (draft) =>
+        Effect.forEach(
+          draft.errors,
+          (entry) =>
+            Effect.logError("Skipping invalid tool registration", {
+              name: entry.tool.name,
+              namespace: entry.tool.options?.namespace,
+              error: entry.error.message,
+            }),
+          { discard: true },
         ),
-      )
     })
 
     return Service.of({
-      transform,
-      snapshot: Effect.fn("Tool.snapshot")((permissions) =>
-        lock.withPermit(
-          Effect.gen(function* () {
-            const active = new Map<string, Tool.Info>()
-            const rules = permissions ?? []
-            for (const [name, entries] of local) {
-              const tool = entries.at(-1)?.tool
-              if (!tool) continue
-              if (whollyDisabled(tool.options?.permission ?? name, rules)) continue
-              active.set(name, tool)
-            }
-            const direct = new Map(Array.from(active).filter(([, tool]) => tool.options?.codemode === false))
-            const codemode = new Map(Array.from(active).filter(([, tool]) => tool.options?.codemode !== false))
-            const executeRule = rules.findLast((rule) => Wildcard.match("execute", rule.action))
-            const codemodeEnabled = executeRule?.resource !== "*" || executeRule.effect !== "deny"
-            const codemodeTool = codemodeEnabled
-              ? CodeModeTool.create(codemode, (name, tool, input, context) => executeTool(tool, name, input, context))
-              : undefined
-            const codeModeCatalog = codemodeEnabled ? CodeModeTool.catalog(codemode) : undefined
-            return {
-              ...(codeModeCatalog === undefined ? {} : { codeModeCatalog }),
-              definitions: [
-                ...Array.from(direct)
-                  .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
-                  .map(([, tool]) => definition(tool)),
-                ...(codemodeTool ? [definition(codemodeTool)] : []),
-              ],
-              execute: (input: {
-                readonly sessionID: SessionSchema.ID
-                readonly agent: Agent.ID
-                readonly messageID: SessionMessage.ID
-                readonly call: ToolCall
-                readonly progress?: (update: Tool.Metadata) => Effect.Effect<void>
-              }) => {
-                const context: Tool.Context = {
-                  sessionID: input.sessionID,
-                  agent: input.agent,
-                  messageID: input.messageID,
-                  id: Tool.CallID.make(input.call.id),
-                  progress: input.progress ?? (() => Effect.void),
+      transform: (callback) =>
+        state.transform((draft) => {
+          // Preserve rejection of ambiguous adds within one transform, without rejecting later overrides.
+          const added = new Map<string, Tool.Info | undefined>()
+          callback({
+            add: (tool) => {
+              const error = registrationError(tool)
+              if (error) {
+                draft.errors.push({ tool, error })
+                return
+              }
+              const id = effectiveName(tool)
+              if (added.has(id)) {
+                draft.errors.push({
+                  tool,
+                  error: new RegistrationError({ name: id, message: `Duplicate normalized tool name: ${id}` }),
+                })
+                const previous = added.get(id)
+                if (previous) {
+                  draft.tools.set(id, previous)
+                  return
                 }
-                if (input.call.name === "execute" && codemodeTool)
-                  return executeTool(codemodeTool, input.call.name, input.call.input, context)
-                const tool = direct.get(input.call.name)
-                if (tool) return executeTool(tool, input.call.name, input.call.input, context)
-                return new Tool.Error({ message: `Unknown tool: ${input.call.name}` })
-              },
-            }
-          }),
-        ),
+                draft.tools.delete(id)
+                return
+              }
+              added.set(id, draft.tools.get(id))
+              draft.tools.set(id, { ...tool })
+            },
+            update: (id, update) => {
+              const current = draft.tools.get(id)
+              if (!current) return
+              const tool = { ...current }
+              update(tool)
+              tool.name = current.name
+              if (tool.options?.namespace !== current.options?.namespace)
+                tool.options = { ...tool.options, namespace: current.options?.namespace }
+              const error = registrationError(tool)
+              if (error) {
+                draft.errors.push({ tool, error })
+                return
+              }
+              draft.tools.set(id, tool)
+            },
+            remove: (id) => {
+              draft.tools.delete(id)
+              added.delete(id)
+            },
+          })
+        }),
+      reload: state.reload,
+      snapshot: Effect.fn("Tool.snapshot")((permissions) =>
+        Effect.sync(() => {
+          const active = new Map<string, Tool.Info>()
+          const rules = permissions ?? []
+          for (const [name, tool] of state.get().tools) {
+            if (whollyDisabled(tool.options?.permission ?? name, rules)) continue
+            active.set(name, tool)
+          }
+          const direct = new Map(Array.from(active).filter(([, tool]) => tool.options?.codemode === false))
+          const codemode = new Map(Array.from(active).filter(([, tool]) => tool.options?.codemode !== false))
+          const executeRule = rules.findLast((rule) => Wildcard.match("execute", rule.action))
+          const codemodeEnabled = executeRule?.resource !== "*" || executeRule.effect !== "deny"
+          const codemodeTool = codemodeEnabled
+            ? CodeModeTool.create(codemode, (name, tool, input, context) => executeTool(tool, name, input, context))
+            : undefined
+          const codeModeCatalog = codemodeEnabled ? CodeModeTool.catalog(codemode) : undefined
+          return {
+            ...(codeModeCatalog === undefined ? {} : { codeModeCatalog }),
+            definitions: [
+              ...Array.from(direct)
+                .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+                .map(([, tool]) => definition(tool)),
+              ...(codemodeTool ? [definition(codemodeTool)] : []),
+            ],
+            execute: (input: {
+              readonly sessionID: SessionSchema.ID
+              readonly agent: Agent.ID
+              readonly messageID: SessionMessage.ID
+              readonly call: ToolCall
+              readonly progress?: (update: Tool.Metadata) => Effect.Effect<void>
+            }) => {
+              const context: Tool.Context = {
+                sessionID: input.sessionID,
+                agent: input.agent,
+                messageID: input.messageID,
+                id: Tool.CallID.make(input.call.id),
+                progress: input.progress ?? (() => Effect.void),
+              }
+              if (input.call.name === "execute" && codemodeTool)
+                return executeTool(codemodeTool, input.call.name, input.call.input, context)
+              const tool = direct.get(input.call.name)
+              if (tool) return executeTool(tool, input.call.name, input.call.input, context)
+              return new Tool.Error({ message: `Unknown tool: ${input.call.name}` })
+            },
+          }
+        }),
       ),
     })
   }),
@@ -260,27 +267,22 @@ function schemaMakeError(error: unknown) {
   return error instanceof Error ? error.message : String(error)
 }
 
-const skipRegistration = (tool: Tool.Info, error: RegistrationError) =>
-  Effect.logError("Skipping invalid tool registration", {
-    name: tool.name,
-    namespace: tool.options?.namespace,
-    error: error.message,
-  }).pipe(Effect.as(false))
-
-const validateName = (name: string) =>
-  /^[A-Za-z0-9_-]{1,64}$/.test(name)
-    ? Effect.void
-    : Effect.fail(new RegistrationError({ name, message: `Invalid tool name: ${name}` }))
-
-const validateNamespace = (namespace: string) =>
-  namespace.split(".").every((segment) => /^[A-Za-z0-9_-]{1,64}$/.test(segment))
-    ? Effect.void
-    : Effect.fail(
-        new RegistrationError({
-          name: namespace,
-          message: `Invalid tool namespace: ${JSON.stringify(namespace)}`,
-        }),
-      )
+function registrationError(tool: Tool.Info) {
+  const namespace = tool.options?.namespace
+  if (namespace !== undefined && !namespace.split(".").every((segment) => /^[A-Za-z0-9_-]{1,64}$/.test(segment)))
+    return new RegistrationError({ name: namespace, message: `Invalid tool namespace: ${JSON.stringify(namespace)}` })
+  const name = normalizedName(tool)
+  if (!/^[A-Za-z0-9_-]{1,64}$/.test(name)) return new RegistrationError({ name, message: `Invalid tool name: ${name}` })
+  const id = effectiveName(tool)
+  if (tool.options?.codemode === false && id === "execute")
+    return new RegistrationError({ name: id, message: 'Tool name "execute" is reserved for CodeMode' })
+  const result = Result.try({
+    try: () => ToolDefinition.make(definition(tool)),
+    catch: (error) =>
+      new RegistrationError({ name: id, message: `Invalid tool definition ${id}: ${schemaMakeError(error)}` }),
+  })
+  return Result.isFailure(result) ? result.failure : undefined
+}
 
 const normalizedName = (tool: Tool.Info) => tool.name.replace(/[^a-zA-Z0-9_-]/g, "_")
 
@@ -289,12 +291,6 @@ const effectiveName = (tool: Tool.Info) =>
     ? normalizedName(tool)
     : `${tool.options.namespace.replaceAll(".", "_")}_${normalizedName(tool)}`
 
-const normalizedEntries = (tools: ReadonlyArray<Tool.Info>) =>
-  tools.map((tool) => ({
-    key: effectiveName(tool),
-    tool,
-  }))
-
 export const node = makeLocationNode({
   service: Service,
   layer,

packages/core/src/tool/AGENTS.md

@@ -30,17 +30,18 @@ Leaves own resolution, permission, and side-effect ordering. Translate only expe
 
 ## Registration
 
-Built-ins, plugins, and MCP install tools through `ToolRegistry.Service.transform`, adding complete tool objects to the draft. A tool may provide a namespace, which flattens direct model names to `<namespace>_<tool>`, and defaults into CodeMode (`codemode` defaults true; `codemode: false` keeps the tool on the provider's native tool list).
+Built-ins, plugins, and MCP install tools through `Tool.Service.transform`, adding complete tool objects to the draft. A tool may provide a namespace, which flattens direct model names to `<namespace>_<tool>`, and defaults into CodeMode (`codemode` defaults true; `codemode: false` keeps the tool on the provider's native tool list).
 
 Registrations are scoped:
 
-- The latest active same-placement registration wins.
-- Closing any registration removes only that registration and reveals the next active one.
+- Tool transforms use the shared `State.create` lifecycle, like agents and skills: `add`, `update`, and `remove` replay in registration order when state is rebuilt.
+- `update` and `remove` do nothing for missing tools. `add` requires a complete tool definition.
+- Disposing a registration or closing its scope removes its transform and rebuilds the remaining state. `reload` replays transforms after their external inputs change.
 - Each model request captures the effective tools it advertises; later registration changes affect later requests.
 
 Type safety ends at registration. The registry validates model input and declared output at runtime and should not carry producer schema generics through storage or execution.
 
-`ToolRegistry.Service` is Location-scoped. Do not make the registry process-global or construct a separate application-tool service for each Location.
+`Tool.Service` is Location-scoped. Do not make the registry process-global or construct a separate application-tool service for each Location.
 
 ## Permissions
 
@@ -56,4 +57,4 @@ Producer capture limits remain local to producers. For example, Bash keeps `AppP
 
 ## Current Gaps
 
-- MCP and future Session-scoped registrations still need an explicit canonical registration design.
+- Future Session-scoped registrations still need an explicit canonical registration design.

packages/core/src/tool/mcp.ts

@@ -2,7 +2,7 @@ export * as McpTool from "./mcp.js"
 
 import { ToolFailure } from "@opencode-ai/ai"
 import { McpEvent } from "@opencode-ai/schema/mcp-event"
-import { Context, Effect, Exit, Fiber, type JsonSchema, Layer, Scope, Semaphore, Stream } from "effect"
+import { Context, Effect, Fiber, type JsonSchema, Layer, Semaphore, Stream } from "effect"
 import { makeLocationNode } from "@opencode-ai/util/effect/app-node"
 import { Bus } from "../bus.js"
 
@@ -30,94 +30,88 @@ export const layer = Layer.effect(
     const tools = yield* Tool.Service
     const bus = yield* Bus.Service
     const permission = yield* Permission.Service
-    const scope = yield* Scope.Scope
     const lock = Semaphore.makeUnsafe(1)
-    let current: Scope.Closeable | undefined
+    let discovered: MCP.Tool[] = []
 
-    // Register the current tool set under a fresh child scope, then close the previous one so the
-    // registry never has a gap where MCP tools disappear mid-swap.
+    // Keep the source's position so later plugin transforms also apply after MCP refreshes.
+    yield* tools.transform((draft) => {
+      for (const tool of discovered) {
+        const schema = (tool.inputSchema ?? {}) as JsonSchema.JsonSchema
+        draft.add({
+          name: tool.name,
+          options: { namespace: namespace(tool.server), codemode: tool.codemode !== false },
+          description: tool.description ?? "",
+          input: {
+            ...schema,
+            type: "object",
+            properties: schema.properties ?? {},
+            additionalProperties: false,
+          },
+          output: (tool.outputSchema ?? {}) as JsonSchema.JsonSchema,
+          execute: (input, context) =>
+            Effect.gen(function* () {
+              yield* permission.assert({
+                action: name(tool.server, tool.name),
+                resources: ["*"],
+                save: ["*"],
+                metadata: {},
+                sessionID: context.sessionID,
+                agent: context.agent,
+                source: {
+                  type: "tool",
+                  messageID: context.messageID,
+                  id: context.id,
+                },
+              })
+              const result = yield* mcp
+                .callTool({
+                  server: tool.server,
+                  name: tool.name,
+                  args: (input ?? {}) as Record<string, unknown>,
+                })
+                .pipe(
+                  Effect.catchTags({
+                    "MCP.NotFoundError": (error) =>
+                      new ToolFailure({ message: `MCP server "${error.server}" is not available` }),
+                    "MCP.ToolCallError": (error) => new ToolFailure({ message: error.message }),
+                  }),
+                )
+              if (result.isError)
+                return yield* new ToolFailure({
+                  message:
+                    result.content
+                      .flatMap((part) => (part.type === "text" ? [part.text] : []))
+                      .join("\n")
+                      .trim() || "MCP tool returned an error",
+                })
+              const content = result.content.map((part) =>
+                part.type === "text"
+                  ? { type: "text" as const, text: part.text }
+                  : {
+                      type: "file" as const,
+                      uri: `data:${part.mimeType};base64,${part.data}`,
+                      mime: part.mimeType,
+                    },
+              )
+              const text = content.flatMap((part) => (part.type === "text" ? [part.text] : [])).join("\n")
+              return {
+                output: result.structured ?? (text === "" ? null : text),
+                ...(content.length === 0 ? {} : { content }),
+              }
+            }).pipe(
+              Effect.mapError((error) =>
+                error instanceof ToolFailure
+                  ? error
+                  : new ToolFailure({ message: `Unable to execute ${name(tool.server, tool.name)}` }),
+              ),
+            ),
+        })
+      }
+    })
     const reconcile = lock.withPermit(
       Effect.gen(function* () {
-        const discovered = yield* mcp.tools()
-        const next = yield* Scope.fork(scope)
-        yield* tools
-          .transform((draft) => {
-            for (const tool of discovered) {
-              const schema = (tool.inputSchema ?? {}) as JsonSchema.JsonSchema
-              draft.add({
-                name: tool.name,
-                options: { namespace: namespace(tool.server), codemode: tool.codemode !== false },
-                description: tool.description ?? "",
-                input: {
-                  ...schema,
-                  type: "object",
-                  properties: schema.properties ?? {},
-                  additionalProperties: false,
-                },
-                output: (tool.outputSchema ?? {}) as JsonSchema.JsonSchema,
-                execute: (input, context) =>
-                  Effect.gen(function* () {
-                    yield* permission.assert({
-                      action: name(tool.server, tool.name),
-                      resources: ["*"],
-                      save: ["*"],
-                      metadata: {},
-                      sessionID: context.sessionID,
-                      agent: context.agent,
-                      source: {
-                        type: "tool",
-                        messageID: context.messageID,
-                        id: context.id,
-                      },
-                    })
-                    const result = yield* mcp
-                      .callTool({
-                        server: tool.server,
-                        name: tool.name,
-                        args: (input ?? {}) as Record<string, unknown>,
-                      })
-                      .pipe(
-                        Effect.catchTags({
-                          "MCP.NotFoundError": (error) =>
-                            new ToolFailure({ message: `MCP server "${error.server}" is not available` }),
-                          "MCP.ToolCallError": (error) => new ToolFailure({ message: error.message }),
-                        }),
-                      )
-                    if (result.isError)
-                      return yield* new ToolFailure({
-                        message:
-                          result.content
-                            .flatMap((part) => (part.type === "text" ? [part.text] : []))
-                            .join("\n")
-                            .trim() || "MCP tool returned an error",
-                      })
-                    const content = result.content.map((part) =>
-                      part.type === "text"
-                        ? { type: "text" as const, text: part.text }
-                        : {
-                            type: "file" as const,
-                            uri: `data:${part.mimeType};base64,${part.data}`,
-                            mime: part.mimeType,
-                          },
-                    )
-                    const text = content.flatMap((part) => (part.type === "text" ? [part.text] : [])).join("\n")
-                    return {
-                      output: result.structured ?? (text === "" ? null : text),
-                      ...(content.length === 0 ? {} : { content }),
-                    }
-                  }).pipe(
-                    Effect.mapError((error) =>
-                      error instanceof ToolFailure
-                        ? error
-                        : new ToolFailure({ message: `Unable to execute ${name(tool.server, tool.name)}` }),
-                    ),
-                  ),
-              })
-            }
-          })
-          .pipe(Scope.provide(next))
-        if (current) yield* Scope.close(current, Exit.void)
-        current = next
+        discovered = yield* mcp.tools()
+        yield* tools.reload()
       }),
     )
 

packages/core/test/lib/tool.ts

@@ -64,10 +64,8 @@ export const registerToolPlugin = <R>(
         hook: () => Effect.succeed({ dispose: Effect.void }),
       },
       tool: {
-        transform: (callback) =>
-          tools
-            .transform((draft) => callback({ add: (tool) => draft.add(tool) }))
-            .pipe(Effect.orDie, Effect.as({ dispose: Effect.void })),
+        transform: tools.transform,
+        reload: tools.reload,
         hook: () => Effect.die("registerToolPlugin does not support tool hooks"),
       },
     })

packages/core/test/mcp.test.ts

@@ -1229,7 +1229,7 @@ test("serializes concurrent MCP lifecycle operations", async () => {
   )
 })
 
-testEffect(Layer.empty).live("isolates invalid MCP tools and keeps catalog updates alive", () =>
+testEffect(Layer.empty).live("isolates invalid MCP tools and reapplies plugin mutations on catalog updates", () =>
   Effect.gen(function* () {
     const tool = (server: string, name: string) =>
       new MCP.Tool({
@@ -1246,12 +1246,14 @@ testEffect(Layer.empty).live("isolates invalid MCP tools and keeps catalog updat
       const registry = yield* Tool.Service
       const registration = yield* McpTool.Service
       const bus = yield* Bus.Service
+      const policy = yield* registry.transform((draft) => {
+        draft.update("demo_search", (tool) => {
+          tool.description = "Updated search"
+        })
+        draft.remove("other_lookup")
+      })
       yield* registration.flush
-      expect((yield* toolDefinitions(registry)).map((tool) => tool.name)).toEqual([
-        "demo_search",
-        "other_lookup",
-        "execute",
-      ])
+      expect((yield* toolDefinitions(registry)).map((tool) => tool.name)).toEqual(["demo_search", "execute"])
 
       yield* Ref.set(catalog, [tool("demo", "y".repeat(65)), ...healthy, tool("demo", "added"), namespace])
       yield* bus.publish(McpEvent.ToolsChanged, { server: "demo" })
@@ -1259,23 +1261,36 @@ testEffect(Layer.empty).live("isolates invalid MCP tools and keeps catalog updat
       expect((yield* toolDefinitions(registry)).map((tool) => tool.name)).toEqual([
         "demo_added",
         "demo_search",
-        "other_lookup",
         "execute",
       ])
-      yield* Effect.forEach(["demo_search", "other_lookup"], (name) =>
-        executeTool(registry, {
+      expect((yield* toolDefinitions(registry)).find((tool) => tool.name === "demo_search")?.description).toBe(
+        "Updated search",
+      )
+      expect(
+        yield* executeTool(registry, {
           sessionID: Session.ID.make("ses_mcp_invalid_catalog"),
           ...toolIdentity,
-          call: { type: "tool-call", id: `call_${name}`, name, input: {} },
-        }).pipe(Effect.tap((result) => Effect.sync(() => expect(result).toMatchObject({ status: "completed" })))),
-      )
+          call: { type: "tool-call", id: "call_demo_search", name: "demo_search", input: {} },
+        }),
+      ).toMatchObject({ status: "completed" })
 
-      yield* Ref.set(catalog, [tool("demo", "status"), ...healthy, tool("demo", "added"), tool("repaired", "lookup")])
+      yield* Ref.set(catalog, [
+        tool("demo", "status"),
+        tool("other", "lookup"),
+        tool("demo", "added"),
+        tool("repaired", "lookup"),
+      ])
       yield* bus.publish(McpEvent.ToolsChanged, { server: "demo" })
       yield* waitForTool(registry, "demo_status")
       expect((yield* toolDefinitions(registry)).map((tool) => tool.name)).toEqual([
         "demo_added",
-        "demo_search",
+        "demo_status",
+        "repaired_lookup",
+        "execute",
+      ])
+      yield* policy.dispose
+      expect((yield* toolDefinitions(registry)).map((tool) => tool.name)).toEqual([
+        "demo_added",
         "demo_status",
         "other_lookup",
         "repaired_lookup",
@@ -1309,7 +1324,7 @@ testEffect(Layer.empty).live("isolates invalid MCP tools and keeps catalog updat
   }),
 )
 
-it.effect("advertises MCP output schemas to Code Mode", () =>
+it.live("advertises MCP output schemas to Code Mode", () =>
   Effect.gen(function* () {
     const registry = yield* Tool.Service
     const toolSet = yield* waitForCodeModeTool(registry, "demo.search")
@@ -1326,7 +1341,7 @@ it.effect("advertises MCP output schemas to Code Mode", () =>
   }),
 )
 
-it.effect("returns content-only MCP results through Code Mode", () =>
+it.live("returns content-only MCP results through Code Mode", () =>
   Effect.gen(function* () {
     assertion = yield* Deferred.make<Permission.AssertInput>()
     decision = Effect.void
@@ -1351,7 +1366,7 @@ it.effect("returns content-only MCP results through Code Mode", () =>
   }),
 )
 
-it.effect("advertises MCP tools directly when Code Mode is disabled for the server", () =>
+it.live("advertises MCP tools directly when Code Mode is disabled for the server", () =>
   Effect.gen(function* () {
     const registry = yield* Tool.Service
     yield* waitForTool(registry, "direct_lookup")
@@ -1365,7 +1380,7 @@ it.effect("advertises MCP tools directly when Code Mode is disabled for the serv
 
 // Baseline (PLAN.md step 1): MCP isError must become one failed tool call, not a
 // success whose text happens to describe an error.
-it.effect("fails the call when MCP reports isError", () =>
+it.live("fails the call when MCP reports isError", () =>
   Effect.gen(function* () {
     assertion = yield* Deferred.make<Permission.AssertInput>()
     decision = Effect.void
@@ -1383,7 +1398,7 @@ it.effect("fails the call when MCP reports isError", () =>
 )
 
 // Baseline (PLAN.md step 1): mixed MCP text and media content must reach the model intact.
-it.effect("preserves MCP text and media content for the model", () =>
+it.live("preserves MCP text and media content for the model", () =>
   Effect.gen(function* () {
     assertion = yield* Deferred.make<Permission.AssertInput>()
     decision = Effect.void
@@ -1404,7 +1419,7 @@ it.effect("preserves MCP text and media content for the model", () =>
   }),
 )
 
-it.effect("waits for permission before calling an MCP tool", () =>
+it.live("waits for permission before calling an MCP tool", () =>
   Effect.gen(function* () {
     calls = 0
     assertion = yield* Deferred.make<Permission.AssertInput>()
@@ -1446,7 +1461,7 @@ it.effect("waits for permission before calling an MCP tool", () =>
   }),
 )
 
-it.effect("does not call MCP when permission is blocked", () =>
+it.live("does not call MCP when permission is blocked", () =>
   Effect.gen(function* () {
     calls = 0
     assertion = yield* Deferred.make<Permission.AssertInput>()

packages/core/test/plugin/host.ts

@@ -114,6 +114,7 @@ export function host(overrides: Overrides = {}): Plugin.Context {
     },
     tool: overrides.tool ?? {
       transform: () => Effect.die("unused tool.transform"),
+      reload: () => Effect.die("unused tool.reload"),
       hook: () => Effect.die("unused tool.hook"),
     },
     vcs: overrides.vcs ?? {

packages/core/test/plugin/plan.test.ts

@@ -72,6 +72,7 @@ const run = Effect.fnUntraced(function* (events: ReadonlyArray<SessionEvent.Agen
       },
       tool: {
         transform: () => Effect.die("unused tool.transform"),
+        reload: () => Effect.die("unused tool.reload"),
         hook: (name, callback) => {
           if (name === "execute.after") {
             // Hook names and callbacks are correlated, but TypeScript does not narrow this generic registration API.

packages/core/test/plugin/promise.test.ts

@@ -636,4 +636,77 @@ describe("fromPromise", () => {
       })
     }),
   )
+
+  it.live("adapts tool mutation, replay, and disposal through the Promise API", () =>
+    Effect.gen(function* () {
+      const plugins = yield* Plugin.Service
+      const registry = yield* Tool.Service
+      const host = yield* PluginHost.make(plugins)
+      const progress: Tool.Metadata[] = []
+      let greeting = "Hello"
+      let registration: { dispose(): Promise<void> } | undefined
+      yield* host.tool.transform((draft) => {
+        const text = greeting
+        draft.add({
+          name: "hello",
+          description: "Hello",
+          options: { namespace: "acme", codemode: false },
+          input: Schema.Struct({ name: Schema.String }),
+          output: Schema.String,
+          execute: ({ name }, context) =>
+            context.progress({ phase: "original" }).pipe(Effect.as({ output: `${text}, ${name}!` })),
+        })
+        draft.add({
+          name: "temporary",
+          description: "Temporary",
+          input: Schema.Struct({}),
+          options: { codemode: false },
+          execute: () => Effect.succeed({ content: "temporary" }),
+        })
+      })
+      yield* PluginPromise.fromPromise(
+        define({
+          id: "promise-update",
+          setup: async (ctx) => {
+            registration = await ctx.tool.transform((draft) => {
+              draft.update("missing", () => {
+                throw new Error("must not create a tool")
+              })
+              draft.update("acme_hello", (tool) => {
+                const execute = tool.execute
+                tool.description = "Wrapped"
+                tool.execute = async (input, context) => {
+                  const result = await execute(input, context)
+                  return { ...result, output: `${result.output} Wrapped.` }
+                }
+              })
+              draft.remove("temporary")
+            })
+            greeting = "Hi"
+            await ctx.tool.reload()
+          },
+        }),
+      ).effect(host)
+      const snapshot = yield* registry.snapshot()
+      expect(snapshot.definitions.map((tool) => tool.name)).toEqual(["acme_hello", "execute"])
+      expect(snapshot.definitions[0]?.description).toBe("Wrapped")
+      expect(
+        yield* snapshot.execute({
+          sessionID: Session.ID.make("ses_promise_update"),
+          agent: Agent.ID.make("build"),
+          messageID: SessionMessage.ID.make("msg_promise_update"),
+          progress: (value) => Effect.sync(() => progress.push(value)),
+          call: { type: "tool-call", id: "call_promise_update", name: "acme_hello", input: { name: "world" } },
+        }),
+      ).toMatchObject({ output: "Hi, world! Wrapped." })
+      expect(progress).toEqual([{ phase: "original" }])
+      const registered = registration
+      if (!registered) throw new Error("Expected registration")
+      yield* Effect.promise(() => registered.dispose())
+      yield* Effect.promise(() => registered.dispose())
+      const restored = yield* registry.snapshot()
+      expect(restored.definitions.map((tool) => tool.name)).toEqual(["acme_hello", "temporary", "execute"])
+      expect(restored.definitions[0]?.description).toBe("Hello")
+    }),
+  )
 })

packages/core/test/session-runner-tool-registry.test.ts

@@ -7,6 +7,7 @@ import { PluginHooks } from "@opencode-ai/core/plugin/hooks"
 import { Session } from "@opencode-ai/core/session"
 import { SessionMessage } from "@opencode-ai/core/session/message"
 import { Tool } from "@opencode-ai/core/tool"
+import { State } from "@opencode-ai/core/state"
 import type { Info } from "@opencode-ai/schema/tool"
 import { LayerNode } from "@opencode-ai/util/effect/layer-node"
 import { executeTool, toolDefinitions } from "./lib/tool"
@@ -71,6 +72,138 @@ const transform = (service: Tool.Interface, tools: Readonly<Record<string, Info>
   )
 
 describe("Tool", () => {
+  it.live("replays updates and removals on reload and restores definitions on disposal", () =>
+    Effect.gen(function* () {
+      const service = yield* Tool.Service
+      let text = "original"
+      const source = yield* service.transform((draft) =>
+        draft.add({
+          ...constant(text),
+          name: "echo",
+          description: text,
+          options: { namespace: "acme", codemode: false },
+        }),
+      )
+      yield* transform(service, { echo: make() }, { namespace: "other", codemode: false })
+      const before = yield* service.snapshot()
+      const update = yield* service.transform((draft) => {
+        draft.update("missing", () => {
+          throw new Error("must not create a tool")
+        })
+        draft.update("acme_echo", (tool) => {
+          tool.description += " updated"
+          const execute = tool.execute
+          tool.execute = (input, context) =>
+            execute(input, context).pipe(
+              Effect.map((result) => ({ ...result, output: { text: `${result.output.text} updated` } })),
+            )
+        })
+      })
+      const removal = yield* service.transform((draft) => {
+        draft.remove("missing")
+        draft.remove("other_echo")
+      })
+      const updated = yield* service.snapshot()
+      expect(updated.definitions.map((tool) => tool.name)).toEqual(["acme_echo", "execute"])
+      expect(updated.definitions[0]?.description).toBe("original updated")
+      expect((yield* updated.execute(call("acme_echo"))).output).toEqual({ text: "original updated" })
+      text = "refreshed"
+      yield* service.reload()
+      const reloaded = yield* service.snapshot()
+      expect(reloaded.definitions.map((tool) => tool.name)).toEqual(["acme_echo", "execute"])
+      expect(reloaded.definitions[0]?.description).toBe("refreshed updated")
+      expect((yield* reloaded.execute(call("acme_echo"))).output).toEqual({ text: "refreshed updated" })
+      expect((yield* before.execute(call("acme_echo"))).output).toEqual({ text: "original" })
+      yield* removal.dispose
+      yield* removal.dispose
+      yield* update.dispose
+      const restored = yield* service.snapshot()
+      expect(restored.definitions.map((tool) => tool.name)).toEqual(["acme_echo", "other_echo", "execute"])
+      expect((yield* restored.execute(call("acme_echo"))).output).toEqual({ text: "refreshed" })
+      yield* source.dispose
+      expect((yield* service.snapshot()).definitions.map((tool) => tool.name)).toEqual(["other_echo", "execute"])
+    }),
+  )
+
+  it.effect("does not retain an updated tool after its source scope closes", () =>
+    Effect.gen(function* () {
+      const service = yield* Tool.Service
+      const scope = yield* Scope.make()
+      yield* transform(service, { echo: make() }, { codemode: false }).pipe(Scope.provide(scope))
+      yield* service.transform((draft) =>
+        draft.update("echo", (tool) => {
+          tool.description = "Updated"
+        }),
+      )
+      yield* Scope.close(scope, Exit.void)
+      expect((yield* service.snapshot()).definitions.map((tool) => tool.name)).toEqual(["execute"])
+    }),
+  )
+
+  it.effect("batches tool transforms with the shared state lifecycle", () =>
+    Effect.gen(function* () {
+      const service = yield* Tool.Service
+      let runs = 0
+      yield* State.batch(
+        Effect.gen(function* () {
+          yield* service.transform((draft) => {
+            runs++
+            draft.add({ ...make(), options: { codemode: false } })
+          })
+          yield* service.transform((draft) =>
+            draft.update("echo", (tool) => {
+              tool.description = "Batched"
+            }),
+          )
+          expect(runs).toBe(0)
+        }),
+      )
+      expect(runs).toBe(1)
+      expect((yield* service.snapshot()).definitions[0]?.description).toBe("Batched")
+    }),
+  )
+
+  it.effect("skips invalid updates without dropping the existing definition", () =>
+    Effect.gen(function* () {
+      const service = yield* Tool.Service
+      yield* transform(service, { echo: make() }, { codemode: false })
+      yield* service.transform((draft) =>
+        draft.update("echo", (tool) => {
+          Object.assign(tool, { description: undefined })
+        }),
+      )
+      expect((yield* service.snapshot()).definitions[0]?.description).toBe("Echo text")
+    }),
+  )
+
+  it.effect("updates newly added tools and applies removals in order", () =>
+    Effect.gen(function* () {
+      const service = yield* Tool.Service
+      yield* service.transform((draft) => {
+        draft.add({ ...make(), options: { codemode: false } })
+        draft.update("echo", (tool) => {
+          tool.description = "Updated"
+          tool.input = Schema.Struct({ value: Schema.Number })
+          tool.output = Schema.Number
+          tool.execute = ({ value }) => Effect.succeed({ output: value * 2 })
+        })
+        draft.add({ ...make(), name: "removed" })
+        draft.remove("removed")
+        draft.add({ ...make(), name: "removed" })
+        draft.remove("removed")
+      })
+      const snapshot = yield* service.snapshot()
+      expect(snapshot.definitions.map((tool) => tool.name)).toEqual(["echo", "execute"])
+      expect(snapshot.definitions[0]?.description).toBe("Updated")
+      expect(
+        (yield* snapshot.execute({
+          ...call("echo"),
+          call: { type: "tool-call", id: "updated", name: "echo", input: { value: 3 } },
+        })).output,
+      ).toBe(6)
+    }),
+  )
+
   it.effect("logs and skips invalid dotted namespaces", () => {
     const output: unknown[] = []
     const logger = Logger.map(Logger.formatStructured, (entry) => {

packages/plugin/src/effect/tool.ts

@@ -2,13 +2,16 @@ import { Tool } from "@opencode-ai/schema/tool"
 import type { Agent } from "@opencode-ai/schema/agent"
 import type { Session } from "@opencode-ai/schema/session"
 import type { SessionMessage } from "@opencode-ai/schema/session-message"
-import type { JsonSchema } from "effect"
+import type { Effect, JsonSchema, Types } from "effect"
 import type { Hooks, Transform } from "./registration.js"
 
 export interface ToolDraft {
   add<Input extends Tool.ValueSchema<any>, Output extends Tool.ValueSchema<any> | undefined>(
     tool: Tool.Info<Input, Output>,
   ): void
+  /** Updates an existing tool; missing IDs are ignored. */
+  update(id: string, update: (tool: Types.Mutable<Tool.Info>) => void): void
+  remove(id: string): void
 }
 
 export interface ToolHooks {
@@ -48,5 +51,6 @@ export interface ToolFailures extends Record<keyof ToolHooks, unknown> {
 
 export interface ToolDomain {
   readonly transform: Transform<ToolDraft>
+  readonly reload: () => Effect.Effect<void>
   readonly hook: Hooks<ToolHooks, ToolFailures>
 }

packages/plugin/src/promise/adapter.ts

@@ -294,10 +294,31 @@ export function fromPromise(plugin: Plugin) {
             scan: (options) => run(host.storage.scan(options)),
           },
           tool: {
+            reload: () => run(host.tool.reload()),
             transform: (callback) =>
               register(
                 host.tool.transform((draft) =>
                   callback({
+                    update: (id, update) =>
+                      draft.update(id, (tool) => {
+                        const execute = tool.execute
+                        const value: Info = {
+                          ...tool,
+                          execute: (input, context) =>
+                            run(
+                              execute(input, {
+                                ...context,
+                                progress: (update) => Effect.promise(() => context.progress(update)),
+                              }),
+                            ),
+                        }
+                        update(value)
+                        Object.assign(tool, {
+                          ...value,
+                          execute: (input: unknown, context: Tool.Context) => executePromiseTool(value, input, context),
+                        })
+                      }),
+                    remove: (id) => draft.remove(id),
                     add: (tool: Info) =>
                       draft.add({
                         ...tool,

packages/plugin/src/promise/tool.ts

@@ -5,7 +5,7 @@ import { Tool } from "@opencode-ai/schema/tool"
 import type { Agent } from "@opencode-ai/schema/agent"
 import type { Session } from "@opencode-ai/schema/session"
 import type { SessionMessage } from "@opencode-ai/schema/session-message"
-import type { JsonSchema } from "effect"
+import type { JsonSchema, Types } from "effect"
 import type { Hooks, Transform } from "./registration.js"
 
 export interface ToolContext extends Omit<Tool.Context, "progress"> {
@@ -26,6 +26,9 @@ interface ToolDraft {
   add<Input extends Tool.ValueSchema<any>, Output extends Tool.ValueSchema<any> | undefined>(
     tool: Info<Input, Output>,
   ): void
+  /** Updates an existing tool; missing IDs are ignored. */
+  update(id: string, update: (tool: Types.Mutable<Info>) => void): void
+  remove(id: string): void
 }
 
 interface ToolHooks {
@@ -59,5 +62,6 @@ interface ToolHooks {
 
 export interface ToolDomain {
   readonly transform: Transform<ToolDraft>
+  readonly reload: () => Promise<void>
   readonly hook: Hooks<ToolHooks>
 }

packages/www/src/docs/content/build/plugins/effect.mdx

@@ -847,13 +847,23 @@ interface ToolDraft {
   add<Input extends Tool.ValueSchema<any>, Output extends Tool.ValueSchema<any> | undefined>(
     tool: Tool.Info<Input, Output>,
   ): void
+  update(id: string, update: (tool: Types.Mutable<Tool.Info>) => void): void
+  remove(id: string): void
 }
 
 interface ToolDomain {
   readonly transform: Transform<ToolDraft>
+  readonly reload: () => Effect.Effect<void>
 }
 ```
 
+`update` and `remove` use the effective registry name, such as `acme_greeting` above, and do nothing for missing tools.
+Creating a tool requires `add`, not an agent-style upsert. Updates preserve the name and namespace; assign new schemas
+and options to replace them.
+
+As with agents and skills, transforms replay in registration order. Use `yield* ctx.tool.reload()` after external state
+changes. `yield* registration.dispose` removes that transform and rebuilds the tools. Scope cleanup does the same.
+
 ### VCS
 
 Read repository information, working-copy status, or file diffs.

packages/www/src/docs/content/build/plugins/index.mdx

@@ -783,7 +783,7 @@ interface StorageScanResult {
 
 ### Tools
 
-Register tools with a transform.
+Register, update, and remove tools with a transform.
 
 ```ts
 await ctx.tool.transform((draft) => {
@@ -802,9 +802,22 @@ await ctx.tool.transform((draft) => {
       return { content: `Hello ${(input as { name: string }).name}!` }
     },
   })
+  draft.update("acme_greeting", (tool) => {
+    tool.description = "Greet someone by name"
+  })
+  draft.remove("legacy")
 })
 ```
 
+`update` and `remove` use effective registry names, including the namespace: `acme_greeting` in the example above.
+Dots in namespaces and unsupported characters in tool names become `_`.
+
+`update` does nothing when the ID is missing. Unlike agent upserts, creating a tool requires `add` with a complete
+definition. Updates preserve the tool's name and namespace; replace its schemas and options by assigning new values.
+As with agents and skills, transforms replay in registration order when registered, reloaded, or disposed. Later
+transforms see earlier changes. Call `await ctx.tool.reload()` after external state used by a transform changes.
+Calling `await registration.dispose()` removes that transform and rebuilds the tools; plugin unload does the same.
+
 #### Reference
 
 Schemas: [`Tool.Content`](/api#schema-Tool.Content), [`Tool.TextContent`](/api#schema-Tool.TextContent),
@@ -813,10 +826,13 @@ Schemas: [`Tool.Content`](/api#schema-Tool.Content), [`Tool.TextContent`](/api#s
 ```ts
 interface ToolContext {
   transform(callback: (draft: ToolDraft) => void): Promise<Registration>
+  reload(): Promise<void>
 }
 
 interface ToolDraft {
   add(tool: ToolInfo): void
+  update(id: string, update: (tool: Types.Mutable<ToolInfo>) => void): void
+  remove(id: string): void
 }
 ```