feat(plugin): flat tool draft with namespace

Effect draft.add accepts flat tool objects matching Promise ergonomics. Migrate the tool grouping concept fully to namespace: rename MCP's group helper/registration to namespace and thread namespace through the flat Effect and Promise draft declarations.
refactor(core): replace deferred tool option with codemode (#36560 )
2026-07-13 00:14:06 -05:00 · 2026-07-12 21:21:07 -05:00 · 2026-07-12 22:02:24 -04:00 · 2026-07-12 21:32:34 -04:00
49 changed files with 385 additions and 358 deletions
@@ -0,0 +1,5 @@
+---
+"@opencode-ai/client": patch
+---
+
+Reuse a same-version background service when a repeated health probe succeeds instead of replacing an endpoint another client may already be using.
@@ -1178,7 +1178,7 @@
    "@types/luxon": "3.7.1",
    "@types/node": "24.12.2",
    "@types/semver": "7.7.1",
-    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "@typescript/native-preview": "7.0.0-dev.20251207.1",
    "ai": "6.0.168",
    "cross-spawn": "7.0.6",
    "diff": "8.0.2",
@@ -3230,21 +3230,21 @@

    "@types/yauzl": ["@types/yauzl@2.10.3", "", { "dependencies": { "@types/node": "*" } }, "sha512-oJoftv0LSuaDZE3Le4DbKX+KS9G36NzOeSap90UIK0yMA/NhKJhqlSGtNDORNRaIbQfzjXDrQa0ytJ6mNRGz/Q=="],

-    "@typescript/native-preview": ["@typescript/native-preview@7.0.0-dev.20260707.2", "", { "optionalDependencies": { "@typescript/native-preview-darwin-arm64": "7.0.0-dev.20260707.2", "@typescript/native-preview-darwin-x64": "7.0.0-dev.20260707.2", "@typescript/native-preview-linux-arm": "7.0.0-dev.20260707.2", "@typescript/native-preview-linux-arm64": "7.0.0-dev.20260707.2", "@typescript/native-preview-linux-x64": "7.0.0-dev.20260707.2", "@typescript/native-preview-win32-arm64": "7.0.0-dev.20260707.2", "@typescript/native-preview-win32-x64": "7.0.0-dev.20260707.2" }, "bin": { "tsgo": "bin/tsgo" } }, "sha512-oUGp+Rep/hqMhPunyinsALUwSlzHINSxitifPiSaeqoKOKD2OlR9NE3TaPqwsl4NlGslsOSUXI1JotWQzpYCPg=="],
+    "@typescript/native-preview": ["@typescript/native-preview@7.0.0-dev.20251207.1", "", { "optionalDependencies": { "@typescript/native-preview-darwin-arm64": "7.0.0-dev.20251207.1", "@typescript/native-preview-darwin-x64": "7.0.0-dev.20251207.1", "@typescript/native-preview-linux-arm": "7.0.0-dev.20251207.1", "@typescript/native-preview-linux-arm64": "7.0.0-dev.20251207.1", "@typescript/native-preview-linux-x64": "7.0.0-dev.20251207.1", "@typescript/native-preview-win32-arm64": "7.0.0-dev.20251207.1", "@typescript/native-preview-win32-x64": "7.0.0-dev.20251207.1" }, "bin": { "tsgo": "bin/tsgo.js" } }, "sha512-4QcRnzB0pi9rS0AOvg8kWbmuwHv5X7B2EXHbgcms9+56hsZ8SZrZjNgBJb2rUIodJ4kU5mrkj/xlTTT4r9VcpQ=="],

-    "@typescript/native-preview-darwin-arm64": ["@typescript/native-preview-darwin-arm64@7.0.0-dev.20260707.2", "", { "os": "darwin", "cpu": "arm64" }, "sha512-wny2pgKjGbiZtnOIHVa3tXC1UfDqxNEFzyPGmiqybedG8hipG2Nfp0l5UxbaKCjkLacUpH/W5bP2hBOMVhCOzg=="],
+    "@typescript/native-preview-darwin-arm64": ["@typescript/native-preview-darwin-arm64@7.0.0-dev.20251207.1", "", { "os": "darwin", "cpu": "arm64" }, "sha512-waWJnuuvkXh4WdpbTjYf7pyahJzx0ycesV2BylyHrE9OxU9FSKcD/cRLQYvbq3YcBSdF7sZwRLDBer7qTeLsYA=="],

-    "@typescript/native-preview-darwin-x64": ["@typescript/native-preview-darwin-x64@7.0.0-dev.20260707.2", "", { "os": "darwin", "cpu": "x64" }, "sha512-Afc7M5zOwo+GpfcYwz5Z8HMB2tPVsui7nNIqEuuFB73MPdVqNn/Wmpe4tP4MRri0AtJnJknoHBaTJ/VDAp/Jhw=="],
+    "@typescript/native-preview-darwin-x64": ["@typescript/native-preview-darwin-x64@7.0.0-dev.20251207.1", "", { "os": "darwin", "cpu": "x64" }, "sha512-3bkD9QuIjxETtp6J1l5X2oKgudJ8z+8fwUq0izCjK1JrIs2vW1aQnbzxhynErSyHWH7URGhHHzcsXHbikckAsg=="],

-    "@typescript/native-preview-linux-arm": ["@typescript/native-preview-linux-arm@7.0.0-dev.20260707.2", "", { "os": "linux", "cpu": "arm" }, "sha512-hJm/UOqZTr9FHmR7uNm8VGX4oKtfWk0Jem0zPeJFNC8ckGUfSBueyiEYMZB+XmRc1aG4x1E46y3CplP4CLHvGQ=="],
+    "@typescript/native-preview-linux-arm": ["@typescript/native-preview-linux-arm@7.0.0-dev.20251207.1", "", { "os": "linux", "cpu": "arm" }, "sha512-OjrZBq8XJkB7uCQvT1AZ1FPsp+lT0cHxY5SisE+ZTAU6V0IHAZMwJ7J/mnwlGsBcCKRLBT+lX3hgEuOTSwHr9w=="],

-    "@typescript/native-preview-linux-arm64": ["@typescript/native-preview-linux-arm64@7.0.0-dev.20260707.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-iITBa2WjjTI5N9t5l7Z4KoOSI+2zBlhbvFzsD/f8qX8QoKjz/Y4DPyBDgezYi8nkqjjksbgSOJ3/ykzhwrB9cg=="],
+    "@typescript/native-preview-linux-arm64": ["@typescript/native-preview-linux-arm64@7.0.0-dev.20251207.1", "", { "os": "linux", "cpu": "arm64" }, "sha512-Qhp06OObkwy5B+PlAhAmq+Ls3GVt4LHAovrTRcpLB3Mk3yJ0h9DnIQwPQiayp16TdvTsGHI3jdIX4MGm5L/ghA=="],

-    "@typescript/native-preview-linux-x64": ["@typescript/native-preview-linux-x64@7.0.0-dev.20260707.2", "", { "os": "linux", "cpu": "x64" }, "sha512-du0dzi6y97Po5vDNdPJTyyijHCpaS22JLRnKZEJXBDaO9gCIymOv/5QQokFRuOlQm0bWl3i9PF4OVdGP6uAOQA=="],
+    "@typescript/native-preview-linux-x64": ["@typescript/native-preview-linux-x64@7.0.0-dev.20251207.1", "", { "os": "linux", "cpu": "x64" }, "sha512-fPRw0zfTBeVmrkgi5Le+sSwoeAz6pIdvcsa1OYZcrspueS9hn3qSC5bLEc5yX4NJP1vItadBqyGLUQ7u8FJjow=="],

-    "@typescript/native-preview-win32-arm64": ["@typescript/native-preview-win32-arm64@7.0.0-dev.20260707.2", "", { "os": "win32", "cpu": "arm64" }, "sha512-SsAwfhyHJ1akgBc+99z4+hwdbHsdWaKB8EwCNIMA6JfSLMeUjffrYvxu+vfMyxVtOVOz7RrRXRoiDiu4a2sCtg=="],
+    "@typescript/native-preview-win32-arm64": ["@typescript/native-preview-win32-arm64@7.0.0-dev.20251207.1", "", { "os": "win32", "cpu": "arm64" }, "sha512-KxY1i+HxeSFfzZ+HVsKwMGBM79laTRZv1ibFqHu22CEsfSPDt4yiV1QFis8Nw7OBXswNqJG/UGqY47VP8FeTvw=="],

-    "@typescript/native-preview-win32-x64": ["@typescript/native-preview-win32-x64@7.0.0-dev.20260707.2", "", { "os": "win32", "cpu": "x64" }, "sha512-DL4u27stv0fo71sVhOzHSwE+YMZsbBijVI+kg5dLDLilSH79WFTJ8RSQ46vJrCMt+Gjlv/JOZP1PuLJDfioYeQ=="],
+    "@typescript/native-preview-win32-x64": ["@typescript/native-preview-win32-x64@7.0.0-dev.20251207.1", "", { "os": "win32", "cpu": "x64" }, "sha512-5l51HlXjX7lXwo65DEl1IaCFLjmkMtL6K3NrSEamPNeNTtTQwZRa3pQ9V65dCglnnCQ0M3+VF1RqzC7FU0iDKg=="],

    "@typescript/vfs": ["@typescript/vfs@1.6.4", "", { "dependencies": { "debug": "^4.4.3" }, "peerDependencies": { "typescript": "*" } }, "sha512-PJFXFS4ZJKiJ9Qiuix6Dz/OwEIqHD7Dme1UwZhTK11vR+5dqW2ACbdndWQexBzCx+CPuMe5WBYQWCsFyGlQLlQ=="],

@@ -81,7 +81,7 @@
      "@playwright/test": "1.59.1",
      "semver": "7.7.4",
      "typescript": "5.8.2",
-      "@typescript/native-preview": "7.0.0-dev.20260707.2",
+      "@typescript/native-preview": "7.0.0-dev.20251207.1",
      "zod": "4.1.8",
      "remeda": "2.26.0",
      "sst": "4.13.1",
@@ -17,7 +17,6 @@
    "emitDeclarationOnly": true,
    "outDir": "node_modules/.ts-dist",
    "isolatedModules": true,
-    "types": ["vite/client", "bun"],
    "paths": {
      "@/*": ["./src/*"]
    }
@@ -59,11 +59,11 @@ const discoverLocal = Effect.fnUntraced(function* (options: Options) {
 export const start = Effect.fn("service.start")(function* (options: StartOptions = {}) {
  const compatible = yield* discover(options)
  if (compatible !== undefined) return compatible
-  const mismatched = yield* find(options)
-  yield* Effect.sync(() =>
-    options.onStart?.(mismatched === undefined ? "missing" : "version-mismatch", mismatched?.info),
-  )
-  if (mismatched !== undefined) yield* kill(mismatched.info, options).pipe(Effect.ignore)
+  const existing = yield* find(options)
+  if (existing?.version !== undefined && (options.version === undefined || existing.version === options.version))
+    return existing.endpoint
+  yield* Effect.sync(() => options.onStart?.(existing === undefined ? "missing" : "version-mismatch", existing?.info))
+  if (existing !== undefined) yield* kill(existing.info, options).pipe(Effect.ignore)

  const [command, ...args] = options.command ?? ["opencode", "serve", "--service"]
  if (command === undefined) return yield* Effect.fail(new Error("Missing service command"))
@@ -138,6 +138,7 @@ const read = Effect.fnUntraced(function* (file?: string) {
 type LocalService = {
  readonly info: Info
  readonly endpoint: Endpoint
+  readonly version?: string
 }

 const probe = Effect.fnUntraced(function* (info: Info, version?: string, allowLegacy = false) {
@@ -161,7 +162,7 @@ const probe = Effect.fnUntraced(function* (info: Info, version?: string, allowLe
    if (health.value.pid !== info.pid) return undefined
    if (info.version !== undefined && health.value.version !== info.version) return undefined
    if (version !== undefined && health.value.version !== version) return undefined
-    return { info, endpoint } satisfies LocalService
+    return { info, endpoint, version: health.value.version } satisfies LocalService
  }
  if (
    !allowLegacy ||
@@ -0,0 +1,39 @@
+import { rename, writeFile } from "node:fs/promises"
+
+const [registration, mode] = process.argv.slice(2)
+if (registration === undefined || mode === undefined) throw new Error("Missing service fixture arguments")
+
+let requests = 0
+const server = Bun.serve({
+  port: 0,
+  async fetch(request) {
+    if (new URL(request.url).pathname !== "/api/health") return new Response(null, { status: 404 })
+    requests += 1
+    if (mode === "modern" && requests === 1) {
+      await writeFile(registration + ".first-request", "")
+      while (!(await Bun.file(registration + ".release").exists())) await Bun.sleep(5)
+      return new Response(null, { status: 503 })
+    }
+    if (mode === "legacy") return Response.json({ healthy: true })
+    return Response.json({ healthy: true, version: "test", pid: process.pid })
+  },
+})
+
+await writeFile(
+  registration + ".tmp",
+  JSON.stringify({
+    id: crypto.randomUUID(),
+    version: mode === "legacy" ? undefined : "test",
+    url: server.url.toString(),
+    pid: process.pid,
+  }),
+  { mode: 0o600 },
+)
+await rename(registration + ".tmp", registration)
+
+const shutdown = () => {
+  server.stop(true)
+  process.exit()
+}
+process.on("SIGTERM", shutdown)
+process.on("SIGINT", shutdown)
@@ -0,0 +1,91 @@
+import { NodeFileSystem } from "@effect/platform-node"
+import { afterEach, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { mkdtemp, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { Service } from "../src/effect/index"
+
+const fixture = join(import.meta.dir, "fixture/service.ts")
+const processes: Bun.Subprocess[] = []
+const directories: string[] = []
+
+afterEach(async () => {
+  processes.forEach((process) => process.kill("SIGTERM"))
+  await Promise.all(processes.splice(0).map((process) => process.exited))
+  await Promise.all(directories.splice(0).map((directory) => rm(directory, { recursive: true, force: true })))
+})
+
+test("a concurrent same-version start cannot invalidate a resolved endpoint", async () => {
+  const directory = await temp()
+  const registration = join(directory, "service.json")
+  spawn(registration, "modern")
+  await waitForFile(registration)
+  const original = await Bun.file(registration).json()
+
+  const starts: Service.StartReason[] = []
+  const first = run(
+    Service.start({
+      file: registration,
+      version: "test",
+      command: [],
+      onStart: (reason) => starts.push(reason),
+    }),
+  )
+  await waitForFile(registration + ".first-request")
+
+  const resolved = await run(Service.start({ file: registration, version: "test" }))
+  expect(resolved.url).toBe(original.url)
+
+  await writeFile(registration + ".release", "")
+  await first
+
+  expect(starts).toEqual([])
+  expect(await Bun.file(registration).json()).toEqual(original)
+  expect(await health(resolved.url)).toEqual({ healthy: true, version: "test", pid: original.pid })
+})
+
+test("a legacy health response is still replaced", async () => {
+  const directory = await temp()
+  const registration = join(directory, "service.json")
+  const existing = spawn(registration, "legacy")
+  await waitForFile(registration)
+
+  const starts: Service.StartReason[] = []
+  const result = run(Service.start({ file: registration, command: [], onStart: (reason) => starts.push(reason) }))
+
+  await expect(result).rejects.toThrow("Missing service command")
+  expect(starts).toEqual(["version-mismatch"])
+  await existing.exited
+})
+
+function run<A, E>(effect: Effect.Effect<A, E, never>) {
+  return Effect.runPromise(effect.pipe(Effect.provide(NodeFileSystem.layer)))
+}
+
+function spawn(registration: string, mode: string, ...args: string[]) {
+  const subprocess = Bun.spawn([process.execPath, fixture, registration, mode, ...args], {
+    stdout: "ignore",
+    stderr: "inherit",
+  })
+  processes.push(subprocess)
+  return subprocess
+}
+
+async function temp() {
+  const directory = await mkdtemp(join(tmpdir(), "opencode-client-service-"))
+  directories.push(directory)
+  return directory
+}
+
+async function waitForFile(file: string) {
+  for (let attempt = 0; attempt < 600; attempt++) {
+    if (await Bun.file(file).exists()) return
+    await Bun.sleep(5)
+  }
+  throw new Error(`Timed out waiting for ${file}`)
+}
+
+async function health(url: string) {
+  return fetch(new URL("/api/health", url), { signal: AbortSignal.timeout(1_000) }).then((response) => response.json())
+}
@@ -3,7 +3,6 @@
  "extends": "@tsconfig/bun/tsconfig.json",
  "compilerOptions": {
    "lib": ["ESNext", "DOM", "DOM.Iterable"],
-    "types": ["bun"],
    "allowImportingTsExtensions": false,
    "allowJs": false,
    "noUncheckedIndexedAccess": false
@@ -4,7 +4,7 @@
 - Do not add a speculative generic permission or approval policy. A host omits tools it does not expose and enforces domain authorization inside each provided tool.
 - Keep Code Mode unaware of host session, channel, and conversation models. The hosting application supplies trusted execution scope around it.
 - Tool schemas are the model-facing Interface. Keep arguments minimal and natural to the operation; never add unrelated IDs as ambient capability tokens.
- When interpreter behavior or support changes, update `interpreter-support.md` and direct tests in the same PR. Update `codemode.md` when the package design, integration status, or rationale changes.
+- When interpreter behavior or support changes, update `interpreter-support.md` and direct tests in the same PR.

 ## OpenAPI

@@ -1,164 +0,0 @@
-# CodeMode Design and Status
-
-This is the living design and status document for `@opencode-ai/codemode` and its existing V2 OpenCode adapter.
-It records current behavior, intentional boundaries, durable rationale, and material remaining work.
-
-Completed implementation history, branch names, test counts, and closed findings belong in git, not here. Remove
-completed work instead of preserving checked-off chronology.
-
-Detailed package API documentation lives in [README.md](./README.md), and the checkable language/runtime matrix lives
-in [interpreter-support.md](./interpreter-support.md). OpenAPI-specific follow-ups live in
-[src/openapi/TODO.md](./src/openapi/TODO.md).
-
-## How CodeMode Works
-
-### Purpose
-
-CodeMode gives a model one `execute` tool backed by a confined JavaScript interpreter. Inside the program, the model
-can call an explicit tree of schema-described tools, sequence dependent work, run independent calls concurrently,
-and filter or aggregate results before returning them to the agent loop.
-
-The goals are:
-
- Reduce model context consumed by large tool catalogs.
- Avoid an agent round-trip between every dependent tool call.
- Keep large intermediate results inside the program instead of sending them through model context.
- Give generated code only the authority explicitly supplied by the host.
-
-CodeMode is an orchestration language, not a general JavaScript runtime or an application authorization system.
-
-### Runtime
-
-The generic runtime lives in `packages/codemode` and is host-neutral:
-
-1. The host builds a tree of `Tool.make(...)` definitions and calls `CodeMode.make(...)` or `CodeMode.execute(...)`.
-2. CodeMode generates model instructions, a budgeted inline catalog, and the global `search(...)` built-in.
-3. TypeScript syntax is transpiled away, Acorn parses the resulting JavaScript, and an owned tree-walking interpreter
-   executes it without `eval`.
-4. Tool inputs and outputs cross schema and plain-data boundaries before they become visible on either side.
-5. Execution returns `CodeMode.Result`. Expected program and tool failures are diagnostic data; host interruption
-   remains Effect interruption.
-
-Effect Schemas validate and transform tool inputs and outputs. JSON Schemas render model-facing signatures but do not
-validate values; adapter-provided values still cross the plain-data boundary. A tool without an output schema is
-advertised as `Promise<unknown>`.
-
-### Discovery and model workflow
-
-The model sees a token-budgeted catalog. Every namespace remains visible, and complete signatures are selected
-round-robin across namespaces so one large namespace cannot starve the others. The global `search(...)` built-in is
-always callable - synchronously, counted as an admitted tool call - and is advertised when the inline catalog is
-partial.
-
-The intended workflow is:
-
-1. Pick an exact signature from the inline catalog, or return `search(...)` results and use a selected path in the
-   next execution.
-2. Call the exact returned path without guessing or normalizing segments.
-3. Narrow `Promise<unknown>` results before reading fields.
-4. Start independent calls together and await them with `Promise.all`.
-5. Filter and aggregate inside the program, then return only the data needed by the model.
-
-Search returns directly usable JavaScript paths, descriptions, and complete TypeScript signatures. It supports exact
-path lookup, namespace browsing, deterministic ranking, and pagination.
-
-### Tool execution
-
-Every sandbox promise starts eagerly on a run-once fiber owned by the whole CodeMode execution, including tool calls,
-async functions, chained `.then`/`.catch`/`.finally` reactions, `new Promise(executor)` constructions, and the
-`Promise.all`/`allSettled`/`race`/`any`/`resolve`/`reject` statics. Nested functions therefore cannot end the lifetime
-of work they started.
-Independent aggregate batches overlap, and rejection is observed at the eventual `await` or chained rejection handler.
-`Promise.race` and `Promise.any` use native non-cancelling settlement semantics: the deciding member wins while losers
-continue running, and an all-rejected `Promise.any` rejects with an `AggregateError`. `new Promise(...)` hands the
-executor first-class resolve/reject callables that may escape and settle the promise later, exactly once.
-Reaction ordering matches what V8 makes observable - handlers and await continuations are deferred and run in attach
-order, and a combinator settles one reaction turn after its deciding member - without promising exact microtask-count
-parity beyond that. At normal completion CodeMode interrupts everything still running - race losers,
-fail-fast `Promise.all` stragglers, and fire-and-forget calls alike: the program has returned, so no future await can
-exist, and work whose completion matters must be awaited by the program. Waiting for any class of leftover instead
-would let it hold the execution open indefinitely.
-Rejections that settled un-awaited before the return become `Success.warnings` diagnostics. A fatal program failure or
-host interruption closes the execution promise scope and interrupts its active fibers instead. A timeout does the
-same, except that a value the program already returned is preserved alongside a `TimeoutExceeded` warning rather than
-discarded. CodeMode does not limit tool-call concurrency.
-
-The public execution-policy knobs are `timeoutMs`, `maxToolCalls`, and `maxOutputBytes`. The package supplies no
-defaults because budgets are host policy. The interpreter also enforces a fixed internal data nesting depth.
-`maxOutputBytes` bounds retained payload bytes, not the complete rendered message;
-warning diagnostics have an equal separate budget so a large value cannot starve them, and fixed truncation notices and
-host-added framing are intentionally outside the budgets.
-
-### Data, files, and failures
-
-Program results and tool arguments are JSON-like data. Dates become ISO strings at host boundaries; RegExp, Map, and
-Set values become `{}` as they do under JSON serialization. Promise and runtime reference values cannot cross the
-boundary.
-
-Unknown host failures and invalid outputs are sanitized. `ToolError` is the explicit channel for a safe message that a
-tool wants the model to see. Diagnostic categories distinguish parsing, unsupported syntax, unknown tools, invalid
-data, tool failures, limits, timeouts, execution failures, and warning truncation.
-
-Files and other attachment content stay outside the interpreter. A host may collect them while child tools execute and
-attach them to the outer result, but the program receives only the structured tool output.
-
-### V2 OpenCode adapter
-
-CodeMode is integrated into V2 through `packages/core/src/tool/registry.ts` and
-`packages/core/src/tool/execute.ts`:
-
- Core has one canonical `Tool` representation. Location-scoped producers register direct or deferred tools through
-  `Tools.Service`.
- Each model step snapshots effective registrations, applies catalog visibility filtering, and exposes direct tools
-  normally.
- When visible deferred tools exist, Core reserves and materializes one `execute` tool. Grouped deferred tools become
-  CodeMode namespaces instead of flattened model-facing names.
- Nested calls execute the registered `Tool` values captured for the model request; later registrations affect later
-  requests.
- Authorization and side-effect ordering remain responsibilities of the leaf tool. Catalog visibility is not execution
-  authorization.
- Structured child output enters the interpreter. File parts are collected host-side and attached to the outer result.
- Nested call statuses are returned as final `execute` metadata for the TUI.
- `execute` is the one model-facing tool invocation. Nested calls reuse its invocation context and do not independently
-  run registry hooks or model-output bounding; this keeps complete intermediate structured values available for
-  in-program filtering. The outer `execute` settlement is the single model-output bounding boundary.
- Core supplies no CodeMode timeout or tool-call limit. User cancellation interrupts the outer invocation and its
-  supervised children; the outer settlement applies Core's normal output-retention policy.
-
-MCP tools use this canonical path: they register as grouped tools and are deferred while CodeMode is enabled. Existing
-output schemas are preserved in generated signatures. Direct Core tools remain direct and are not ambient globals
-inside CodeMode.
-
-## Intentionally Unsupported
-
-These are product boundaries rather than DSL backlog:
-
- Ambient filesystem, process, environment, network, credential, or application access. External work must go through
-  supplied tools.
- Modules, imports, dynamic imports, `eval`, arbitrary host globals, npm packages, and prototype mutation.
- Generic permission prompts, authorization policy, durable pause/resume, replay, storage, or exactly-once external
-  side effects. Hosts and tools own those concerns.
- Heuristic parsing of text tool results as JSON. A result should not silently change type based on its contents.
-
-The OpenAPI adapter may gain more transports and encodings, but it must continue skipping operations it cannot
-represent accurately rather than guessing semantics.
-
-## Decisions and Rationale
-
-| Decision                                                     | Rationale                                                                                                                                                                                                                |
-| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Keep an owned tree-walking interpreter.                      | The product need is bounded tool orchestration, not arbitrary JavaScript. Owning the language surface keeps authority and behavior explicit.                                                                             |
-| Treat schemas as the model-facing interface.                 | Signatures drive correct calls; Effect Schema also provides the runtime validation boundary, while JSON Schema supports adapter interoperability.                                                                        |
-| Keep authority host-owned.                                   | CodeMode can only confine programs to supplied tools. The host chooses those tools, and each tool enforces its own authorization and side-effect policy.                                                                 |
-| Use progressive catalog disclosure plus search.              | Large tool sets should not consume the prompt, but every namespace must remain discoverable and speculative search calls should remain valid.                                                                            |
-| Start promises eagerly and supervise them for the execution. | This preserves normal call-time parallelism and run-once settlement while allowing pending work to be interrupted when the program returns.                                                                              |
-| Keep files outside the sandbox value space.                  | Models should compose structured data without routing binary payloads through generated code or context.                                                                                                                 |
-| Treat `execute` as the model-facing invocation boundary.     | Nested calls are implementation details of one orchestration program. Reusing the outer context and bounding only the final result preserves complete intermediate data without inventing durable child-call identities. |
-| Return expected failures as data.                            | Models need actionable diagnostics without exposing private host causes; host interruption and defects must still propagate correctly.                                                                                   |
-| Leave execution-limit defaults to hosts.                     | Appropriate budgets depend on the surrounding product and its own cancellation, retention, and output-bounding policies.                                                                                                 |
-| Skip unsupported OpenAPI operations.                         | Incorrect parameter encoding, authentication, or transport behavior is worse than a precise `skipped` reason.                                                                                                            |
-
-## Remaining Work
-
-The [interpreter support checklist](./interpreter-support.md) owns concrete DSL, standard-library, semantic-correctness,
-diagnostic, and data-boundary work. OpenAPI adapter work remains in [src/openapi/TODO.md](./src/openapi/TODO.md).
@@ -2,8 +2,6 @@
  "$schema": "https://json.schemastore.org/tsconfig",
  "extends": "@tsconfig/bun/tsconfig.json",
  "compilerOptions": {
-    "lib": ["ESNext", "DOM", "DOM.Iterable"],
-    "types": ["bun"],
    "noUncheckedIndexedAccess": false,
    "noUnusedLocals": true
  }
@@ -52,9 +52,6 @@ export const Flag = {
  get OPENCODE_EXPERIMENTAL_REFERENCES() {
    return enabledByExperimental("OPENCODE_EXPERIMENTAL_REFERENCES")
  },
-  get CODEMODE_ENABLED() {
-    return process.env["CODEMODE_ENABLED"] === undefined || truthy("CODEMODE_ENABLED")
-  },
  get OPENCODE_TUI_CONFIG() {
    return process.env["OPENCODE_TUI_CONFIG"]
  },
@@ -1,7 +1,6 @@
 export * as McpGuidance from "./guidance"

 import { makeLocationNode } from "../effect/app-node"
-import { Flag } from "../flag/flag"
 import { Context, Effect, Layer, Schema } from "effect"
 import { AgentV2 } from "../agent"
 import { PermissionV2 } from "../permission"
@@ -18,11 +17,7 @@ type Summary = typeof Summary.Type
 const entries = (servers: ReadonlyArray<Summary>) =>
  servers.flatMap((server) => [
    `  <server name="${server.server}">`,
-    ...(Flag.CODEMODE_ENABLED
-      ? [
-          `    Use tools from this server through \`execute\` under \`tools[${JSON.stringify(McpTool.group(server.server))}]\`.`,
-        ]
-      : []),
+    `    Use tools from this server through \`execute\` under \`tools[${JSON.stringify(McpTool.namespace(server.server))}]\`.`,
    ...server.instructions.split("\n").map((line) => `    ${line}`),
    "  </server>",
  ])
@@ -81,7 +76,7 @@ export const layer = Layer.effect(
              removed: () => "MCP server instructions are no longer available.",
            },
          })
-        if (Flag.CODEMODE_ENABLED && PermissionV2.evaluate("execute", "*", agent.permissions).effect === "deny")
+        if (PermissionV2.evaluate("execute", "*", agent.permissions).effect === "deny")
          return source(Instructions.removed)
        const [instructions, tools] = yield* Effect.all([mcp.instructions(), mcp.tools()], {
          concurrency: "unbounded",
@@ -90,12 +85,9 @@ export const layer = Layer.effect(
        const visible = instructions
          .filter((item) => {
            const owned = tools.filter((tool) => tool.server === item.server)
-            return (
-              (!Flag.CODEMODE_ENABLED && owned.length === 0) ||
-              owned.some(
-                (tool) =>
-                  PermissionV2.evaluate(McpTool.name(tool.server, tool.name), "*", agent.permissions).effect !== "deny",
-              )
+            return owned.some(
+              (tool) =>
+                PermissionV2.evaluate(McpTool.name(tool.server, tool.name), "*", agent.permissions).effect !== "deny",
            )
          })
          .map((item) => ({ server: item.server, instructions: item.instructions }))
@@ -305,27 +305,13 @@ export const make = Effect.fn("PluginHost.make")(function* (plugin: PluginV2.Int
        }),
    },
    tool: {
+      // The tool domain is scoped registration, not State, so the host adapts the draft to register calls directly.
      transform: (callback) =>
-        Effect.gen(function* () {
-          const registrations: Array<{
-            readonly name: string
-            readonly tool: Tool.AnyTool
-            readonly options?: Tool.RegisterOptions
-          }> = []
-          yield* Effect.sync(() =>
-            callback({
-              add: (name, tool, options) => {
-                registrations.push({ name, tool, ...(options ? { options } : {}) })
-              },
-            }),
-          )
-          yield* Effect.forEach(
-            registrations,
-            (registration) => tools.register({ [registration.name]: registration.tool }, registration.options),
-            { discard: true },
-          ).pipe(Effect.orDie)
-          return { dispose: Effect.void }
-        }),
+        Effect.forEach(
+          Tool.fromDraft(callback),
+          ({ name, tool, options }) => tools.register({ [name]: tool }, options),
+          { discard: true },
+        ).pipe(Effect.orDie, Effect.as({ dispose: Effect.void })),
      hook: (name, callback) => {
        if (name === "execute.before") {
          return toolHooks.hook.before((event) => {
@@ -154,7 +154,11 @@ export function fromPromise(plugin: Plugin) {
              register(
                host.tool.transform((draft) =>
                  callback({
-                    add: (tool: AnyTool) => draft.add(tool.name, fromPromiseTool(tool), tool.options),
+                    add: (tool: AnyTool) =>
+                      draft.add(tool.name, fromPromiseTool(tool), {
+                        ...(tool.namespace !== undefined ? { namespace: tool.namespace } : {}),
+                        ...(tool.codemode !== undefined ? { codemode: tool.codemode } : {}),
+                      }),
                  }),
                ),
              ),
@@ -29,7 +29,8 @@ Leaves own resolution, permission, and side-effect ordering. Translate only expe
 ## Registration

 Built-ins and plugin tools register through `Tools.Service.register({ [name]: tool })`. Registrations may provide a
-group, which flattens direct model names to `<group>_<tool>`, and may be deferred from direct model exposure.
+`namespace`, which flattens native model names to `<namespace>_<tool>`, and default into CodeMode (`codemode` defaults
+true; `codemode: false` keeps the tool on the provider's native tool list).

 Registrations are scoped:

@@ -212,6 +212,7 @@ export const Plugin = {
            }),
            "edit",
          ),
+          { codemode: false },
        ),
      )
      .pipe(Effect.orDie)
@@ -39,7 +39,7 @@ type CollectedFiles = {
 interface Registration {
  readonly tool: AnyTool
  readonly name: string
-  readonly group?: string
+  readonly namespace?: string
 }

 export const create = (registrations: ReadonlyMap<string, Registration>) => {
@@ -56,19 +56,19 @@ export const create = (registrations: ReadonlyMap<string, Registration>) => {
        output: child.outputSchema,
        run: (input) => invoke(name, registration, input),
      })
-      if (registration.group === undefined) {
+      if (registration.namespace === undefined) {
        const path = registration.name
-        if (Object.hasOwn(tools, path)) throw new TypeError(`Deferred tool namespace conflict: ${path}`)
+        if (Object.hasOwn(tools, path)) throw new TypeError(`CodeMode tool namespace conflict: ${path}`)
        tools[path] = value
        continue
      }
      const path = registration.name
-      const namespace = registration.group
-      const group = tools[namespace]
-      if (group && Tool.isDefinition(group)) throw new TypeError(`Deferred tool namespace conflict: ${namespace}`)
-      if (group) {
-        if (Object.hasOwn(group, path)) throw new TypeError(`Deferred tool namespace conflict: ${namespace}.${path}`)
-        group[path] = value
+      const namespace = registration.namespace
+      const branch = tools[namespace]
+      if (branch && Tool.isDefinition(branch)) throw new TypeError(`CodeMode tool namespace conflict: ${namespace}`)
+      if (branch) {
+        if (Object.hasOwn(branch, path)) throw new TypeError(`CodeMode tool namespace conflict: ${namespace}.${path}`)
+        branch[path] = value
        continue
      }
      const entries: Record<string, Tool.Definition<never>> = {}
@@ -106,6 +106,7 @@ export const Plugin = {
                ),
              ),
          }),
+          { codemode: false },
        ),
      )
      .pipe(Effect.orDie)
@@ -137,6 +137,7 @@ export const Plugin = {
                ),
              ),
          }),
+          { codemode: false },
        ),
      )
      .pipe(Effect.orDie)
@@ -5,7 +5,7 @@ import { McpEvent } from "@opencode-ai/schema/mcp-event"
 import { Effect, Exit, type JsonSchema, Layer, Scope, Semaphore, Stream } from "effect"
 import { makeLocationNode } from "../effect/app-node"
 import { EventV2 } from "../event"
-import { Flag } from "../flag/flag"
+
 import { MCP } from "../mcp"
 import { PermissionV2 } from "../permission"
 import { Tool } from "./tool"
@@ -13,10 +13,10 @@ import { Tools } from "./tools"
 import { ToolRegistry } from "./registry"

 /**
- * Registry group and permission action names for MCP tools.
+ * Registry namespace and permission action names for MCP tools.
 */
-export const group = (server: string) => server.replace(/[^a-zA-Z0-9_-]/g, "_")
-export const name = (server: string, tool: string) => `${group(server)}_${tool.replace(/[^a-zA-Z0-9_-]/g, "_")}`
+export const namespace = (server: string) => server.replace(/[^a-zA-Z0-9_-]/g, "_")
+export const name = (server: string, tool: string) => `${namespace(server)}_${tool.replace(/[^a-zA-Z0-9_-]/g, "_")}`

 export const layer = Layer.effectDiscard(
  Effect.gen(function* () {
@@ -32,11 +32,11 @@ export const layer = Layer.effectDiscard(
    // registry never has a gap where MCP tools disappear mid-swap.
    const reconcile = lock.withPermit(
      Effect.gen(function* () {
-        const groups = new Map<string, Record<string, Tool.AnyTool>>()
+        const byServer = new Map<string, Record<string, Tool.AnyTool>>()
        for (const tool of yield* mcp.tools()) {
-          const group = groups.get(tool.server) ?? {}
+          const record = byServer.get(tool.server) ?? {}
          const schema = (tool.inputSchema ?? {}) as JsonSchema.JsonSchema
-          group[tool.name] = Tool.withPermission(
+          record[tool.name] = Tool.withPermission(
            Tool.make({
              description: tool.description ?? "",
              jsonSchema: {
@@ -102,16 +102,12 @@ export const layer = Layer.effectDiscard(
            }),
            name(tool.server, tool.name),
          )
-          groups.set(tool.server, group)
+          byServer.set(tool.server, record)
        }
        const next = yield* Scope.fork(scope)
-        yield* Effect.forEach(
-          groups,
-          ([group, record]) => tools.register(record, { group, deferred: Flag.CODEMODE_ENABLED }),
-          {
-            discard: true,
-          },
-        ).pipe(Scope.provide(next), Effect.orDie)
+        yield* Effect.forEach(byServer, ([server, record]) => tools.register(record, { namespace: server }), {
+          discard: true,
+        }).pipe(Scope.provide(next), Effect.orDie)
        if (current) yield* Scope.close(current, Exit.void)
        current = next
      }),
@@ -191,6 +191,7 @@ export const Plugin = {
            }),
            "edit",
          ),
+          { codemode: false },
        ),
      )
      .pipe(Effect.orDie)
@@ -106,6 +106,7 @@ export const Plugin = {
                  }),
                ),
          }),
+          { codemode: false },
        ),
      )
      .pipe(Effect.orDie)
@@ -139,6 +139,7 @@ export const Plugin = {
              )
            },
          }),
+          { codemode: false },
        ),
      )
      .pipe(Effect.orDie)
@@ -3,7 +3,6 @@ export * as ToolRegistry from "./registry"
 import { ToolOutput, type ToolCall, type ToolDefinition, type ToolResultValue } from "@opencode-ai/llm"
 import { Context, Effect, Layer, Scope } from "effect"
 import type { AgentV2 } from "../agent"
-import { Flag } from "../flag/flag"
 import { PermissionV2 } from "../permission"
 import { SessionMessage } from "../session/message"
 import { SessionSchema } from "../session/schema"
@@ -55,8 +54,8 @@ const registryLayer = Layer.effect(
    type Registration = {
      readonly tool: AnyTool
      readonly name: string
-      readonly group?: string
-      readonly deferred: boolean
+      readonly namespace?: string
+      readonly codemode: boolean
    }
    const local = new Map<string, Array<{ readonly token: object; readonly registration: Registration }>>()

@@ -130,9 +129,10 @@ const registryLayer = Layer.effect(

    return Service.of({
      register: Effect.fn("ToolRegistry.register")(function* (tools, options) {
-        const entries = registrationEntries(tools, options?.group)
+        const entries = registrationEntries(tools, options?.namespace)
        if (entries.length === 0) return
-        const reserved = options?.deferred ? undefined : entries.find((entry) => entry.key === "execute")
+        const codemode = options?.codemode ?? true
+        const reserved = codemode ? undefined : entries.find((entry) => entry.key === "execute")
        if (reserved)
          return yield* Effect.fail(
            new RegistrationError({ name: reserved.key, message: 'Tool name "execute" is reserved for CodeMode' }),
@@ -148,8 +148,8 @@ const registryLayer = Layer.effect(
                  registration: {
                    tool: entry.tool,
                    name: entry.name,
-                    group: entry.group,
-                    deferred: options?.deferred ?? false,
+                    namespace: entry.namespace,
+                    codemode,
                  },
                },
              ])
@@ -168,18 +168,17 @@ const registryLayer = Layer.effect(
      }),
      materialize: Effect.fn("ToolRegistry.materialize")(function* (permissions) {
        const direct = new Map<string, Registration>()
-        const deferred = new Map<string, Registration>()
+        const codemode = new Map<string, Registration>()
        const rules = permissions ?? []
        for (const [name, entries] of local) {
          const registration = entries.at(-1)?.registration
          if (!registration) continue
-          if (registration.deferred && !Flag.CODEMODE_ENABLED) continue
          if (whollyDisabled(permission(registration.tool, name), rules)) continue
-          if (registration.deferred) deferred.set(name, registration)
+          if (registration.codemode) codemode.set(name, registration)
          else direct.set(name, registration)
        }
        const execute =
-          deferred.size > 0 && !whollyDisabled("execute", rules) ? ExecuteTool.create(deferred) : undefined
+          codemode.size > 0 && !whollyDisabled("execute", rules) ? ExecuteTool.create(codemode) : undefined
        return {
          definitions: [
            ...Array.from(direct, ([name, registration]) => definition(name, registration.tool)),
@@ -278,6 +278,7 @@ export const Plugin = {
                ),
              ),
          }),
+          { codemode: false },
        ),
      )
      .pipe(Effect.orDie)
@@ -97,6 +97,7 @@ export const Plugin = {
                }).pipe(Effect.mapError((error) => unableToLoad(input.id, error)))
              }),
          }),
+          { codemode: false },
        ),
      )
      .pipe(Effect.orDie)
@@ -208,6 +208,7 @@ export const Plugin = {
                return { sessionID: child.id, status: "completed" as const, output: result?.info.output ?? NO_TEXT }
              }),
          }),
+          { codemode: false },
        ),
      )
      .pipe(Effect.orDie)
@@ -174,6 +174,7 @@ export const Plugin = {
                }
              }).pipe(Effect.mapError((error) => new ToolFailure({ message: `Unable to fetch ${input.url}`, error }))),
          }),
+          { codemode: false },
        ),
      )
      .pipe(Effect.orDie)
@@ -252,6 +252,7 @@ export const Plugin = {
              )
            },
          }),
+          { codemode: false },
        ),
      )
      .pipe(Effect.orDie)
@@ -91,6 +91,7 @@ export const Plugin = {
            }),
            "edit",
          ),
+          { codemode: false },
        ),
      )
      .pipe(Effect.orDie)
@@ -46,24 +46,11 @@ export const registerToolPlugin = <R>(plugin: {
    const context = host({
      tool: {
        transform: (callback) =>
-          Effect.gen(function* () {
-            const registrations: Array<{
-              readonly name: string
-              readonly tool: Tool.AnyTool
-              readonly options?: Tool.RegisterOptions
-            }> = []
-            callback({
-              add: (name, tool, options) => {
-                registrations.push({ name, tool, ...(options ? { options } : {}) })
-              },
-            })
-            yield* Effect.forEach(
-              registrations,
-              (registration) => tools.register({ [registration.name]: registration.tool }, registration.options),
-              { discard: true },
-            ).pipe(Effect.orDie)
-            return { dispose: Effect.void }
-          }),
+          Effect.forEach(
+            Tool.fromDraft(callback),
+            ({ name, tool, options }) => tools.register({ [name]: tool }, options),
+            { discard: true },
+          ).pipe(Effect.orDie, Effect.as({ dispose: Effect.void })),
        hook: () => Effect.die("registerToolPlugin does not support tool hooks"),
      },
    })
@@ -260,6 +260,7 @@ describe("PluginV2", () => {
                  output: Schema.Struct({ ok: Schema.Boolean }),
                  execute: () => Effect.succeed({ ok: true }),
                }),
+                { codemode: false },
              ),
            )
            .pipe(Effect.orDie),
@@ -273,7 +274,7 @@ describe("PluginV2", () => {
    }),
  )

-  it.effect("groups tool names and defers registrations from direct exposure", () =>
+  it.effect("namespaces tool names and routes codemode registrations through execute", () =>
    Effect.gen(function* () {
      const plugins = yield* PluginV2.Service
      const registry = yield* ToolRegistry.Service
@@ -285,13 +286,13 @@ describe("PluginV2", () => {
          execute: () => Effect.succeed({ ok: true }),
        })
      const plugin = EffectPlugin.define({
-        id: "grouped-tools",
+        id: "namespaced-tools",
        effect: (ctx) =>
          ctx.tool
            .transform((draft) => {
-              draft.add("plain", tool("Plain"))
-              draft.add("look/up", tool("Lookup"), { group: "context 7" })
-              draft.add("search", tool("Search"), { group: "context 7", deferred: true })
+              draft.add("plain", tool("Plain"), { codemode: false })
+              draft.add("look/up", tool("Lookup"), { namespace: "context 7", codemode: false })
+              draft.add("search", tool("Search"), { namespace: "context 7" })
            })
            .pipe(Effect.orDie),
      })
@@ -306,6 +307,41 @@ describe("PluginV2", () => {
    }),
  )

+  it.effect("accepts flat Effect draft declarations with namespace", () =>
+    Effect.gen(function* () {
+      const plugins = yield* PluginV2.Service
+      const registry = yield* ToolRegistry.Service
+      const plugin = EffectPlugin.define({
+        id: "flat-tools",
+        effect: (ctx) =>
+          ctx.tool
+            .transform((draft) => {
+              draft.add({
+                name: "send",
+                namespace: "slack",
+                description: "Send a Slack message",
+                input: Schema.Struct({ text: Schema.String }),
+                output: Schema.Struct({ sent: Schema.Boolean }),
+                execute: () => Effect.succeed({ sent: true }),
+              })
+              draft.add({
+                name: "edit",
+                codemode: false,
+                description: "Edit a file",
+                input: Schema.Struct({}),
+                output: Schema.Struct({ ok: Schema.Boolean }),
+                execute: () => Effect.succeed({ ok: true }),
+              })
+            })
+            .pipe(Effect.orDie),
+      })
+
+      yield* plugins.activate([versioned(plugin)])
+
+      expect((yield* registry.materialize()).definitions.map((tool) => tool.name)).toEqual(["edit", "execute"])
+    }),
+  )
+
  it.effect("fires before/after tool hooks with mutable events around settlement", () =>
    Effect.gen(function* () {
      const plugins = yield* PluginV2.Service
@@ -330,6 +366,7 @@ describe("PluginV2", () => {
                    output: Schema.Struct({ text: Schema.String }),
                    execute: ({ text }) => Effect.sync(() => executed.push({ text })).pipe(Effect.as({ text })),
                  }),
+                  { codemode: false },
                ),
              )
              .pipe(Effect.orDie)
@@ -135,6 +135,7 @@ describe("fromPromise", () => {
          await ctx.tool.transform((tools) => {
            tools.add({
              name: "hello",
+              codemode: false,
              description: "Hello",
              input: Schema.Struct({ name: Schema.String }),
              output: Schema.String,
@@ -70,7 +70,7 @@ describe("ToolRegistry", () => {
        bash: make(),
        edit: make("edit"),
        write: make("edit"),
-      })
+      }, { codemode: false })
      const names = (permissions: PermissionV2.Ruleset) =>
        toolDefinitions(service, permissions).pipe(Effect.map((definitions) => definitions.map((tool) => tool.name)))

@@ -95,8 +95,8 @@ describe("ToolRegistry", () => {
    Effect.gen(function* () {
      const service = yield* ToolRegistry.Service
      const shared = make()
-      yield* service.register({ first: shared })
-      yield* service.register({ second: Tool.withPermission(shared, "edit") })
+      yield* service.register({ first: shared }, { codemode: false })
+      yield* service.register({ second: Tool.withPermission(shared, "edit") }, { codemode: false })
      Tool.withPermission(shared, "question")

      expect(
@@ -110,7 +110,7 @@ describe("ToolRegistry", () => {
  it.effect("reuses model definitions across requests", () =>
    Effect.gen(function* () {
      const service = yield* ToolRegistry.Service
-      yield* service.register({ echo: make() })
+      yield* service.register({ echo: make() }, { codemode: false })
      const first = yield* toolDefinitions(service)
      const second = yield* toolDefinitions(service)

@@ -122,7 +122,7 @@ describe("ToolRegistry", () => {
    Effect.gen(function* () {
      const service = yield* ToolRegistry.Service
      const scope = yield* Scope.make()
-      yield* service.register({ echo: make() }).pipe(Scope.provide(scope))
+      yield* service.register({ echo: make() }, { codemode: false }).pipe(Scope.provide(scope))
      expect((yield* toolDefinitions(service)).map((tool) => tool.name)).toEqual(["echo"])
      yield* Scope.close(scope, Exit.void)
      expect(yield* toolDefinitions(service)).toEqual([])
@@ -135,7 +135,7 @@ describe("ToolRegistry", () => {
      const scope = yield* Scope.make()
      const registered = yield* Deferred.make<void>()
      const fiber = yield* service
-        .register({ echo: make() })
+        .register({ echo: make() }, { codemode: false })
        .pipe(
          Effect.andThen(Deferred.succeed(registered, undefined)),
          Effect.andThen(Effect.never),
@@ -161,7 +161,7 @@ describe("ToolRegistry", () => {
          output: Schema.Struct({ ok: Schema.Boolean }),
          execute: () => Effect.fail(new Tool.Failure({ message: "Denied" })),
        }),
-      })
+      }, { codemode: false })
      expect(
        yield* executeTool(service, {
          sessionID,
@@ -184,7 +184,7 @@ describe("ToolRegistry", () => {
          output: Schema.Struct({}),
          execute: () => Effect.die("unexpected executor defect"),
        }),
-      })
+      }, { codemode: false })
      expect(
        yield* service.materialize().pipe(
          Effect.flatMap((materialized) =>
@@ -203,7 +203,7 @@ describe("ToolRegistry", () => {
  it.effect("propagates retention failures through settlement", () =>
    Effect.gen(function* () {
      const service = yield* ToolRegistry.Service
-      yield* service.register({ echo: make() })
+      yield* service.register({ echo: make() }, { codemode: false })
      const materialized = yield* service.materialize()
      const exit = yield* materialized.settle(call("echo", "call-retention-failure")).pipe(Effect.exit)

@@ -234,7 +234,7 @@ describe("ToolRegistry", () => {
          output: Schema.Struct({ ok: Schema.Boolean }),
          execute: (_, context) => Effect.sync(() => contexts.push(context)).pipe(Effect.as({ ok: true })),
        }),
-      })
+      }, { codemode: false })
      yield* executeTool(service, {
        sessionID,
        ...identity,
@@ -248,7 +248,7 @@ describe("ToolRegistry", () => {
    Effect.gen(function* () {
      bounds.length = 0
      const service = yield* ToolRegistry.Service
-      yield* service.register({ bounded: make() })
+      yield* service.register({ bounded: make() }, { codemode: false })
      expect(
        yield* settleTool(service, {
          sessionID,
@@ -282,7 +282,7 @@ describe("ToolRegistry", () => {
          execute: ({ value }) => Effect.sync(() => executed.push(value)).pipe(Effect.as({ value })),
          toModelOutput: ({ output }) => [{ type: "text", text: String(output.value) }],
        }),
-      })
+      }, { codemode: false })

      expect(
        yield* executeTool(service, {
@@ -319,7 +319,7 @@ describe("ToolRegistry", () => {
          }),
          execute: () => Effect.succeed({ value: "invalid" }),
        }),
-      })
+      }, { codemode: false })
      expect(
        yield* executeTool(service, {
          sessionID,
@@ -334,10 +334,10 @@ describe("ToolRegistry", () => {
    Effect.gen(function* () {
      const service = yield* ToolRegistry.Service
      const scope = yield* Scope.make()
-      yield* service.register({ echo: constant("advertised") }).pipe(Scope.provide(scope))
+      yield* service.register({ echo: constant("advertised") }, { codemode: false }).pipe(Scope.provide(scope))
      const request = yield* service.materialize()
      yield* Scope.close(scope, Exit.void)
-      yield* service.register({ echo: constant("replacement") })
+      yield* service.register({ echo: constant("replacement") }, { codemode: false })

      expect((yield* request.settle(call("echo"))).result).toEqual({ type: "text", value: "advertised" })
      expect(yield* executeTool(service, call("echo"))).toEqual({ type: "text", value: "replacement" })
@@ -347,9 +347,9 @@ describe("ToolRegistry", () => {
  it.effect("reveals the previous registration after an overlay closes", () =>
    Effect.gen(function* () {
      const service = yield* ToolRegistry.Service
-      yield* service.register({ echo: constant("base") })
+      yield* service.register({ echo: constant("base") }, { codemode: false })
      const overlay = yield* Scope.make()
-      yield* service.register({ echo: constant("overlay") }).pipe(Scope.provide(overlay))
+      yield* service.register({ echo: constant("overlay") }, { codemode: false }).pipe(Scope.provide(overlay))

      expect(yield* executeTool(service, call("echo"))).toEqual({ type: "text", value: "overlay" })
      yield* Scope.close(overlay, Exit.void)
@@ -357,37 +357,31 @@ describe("ToolRegistry", () => {
    }),
  )

-  it.effect("executes deferred tools advertised in a model request", () =>
+  it.effect("executes codemode tools advertised in a model request", () =>
    Effect.gen(function* () {
      const service = yield* ToolRegistry.Service
      const executed: string[] = []
      const scope = yield* Scope.make()
      yield* service
-        .register(
-          {
-            echo: Tool.make({
-              description: "Echo text",
-              input: Schema.Struct({ text: Schema.String }),
-              output: Schema.Struct({ text: Schema.String }),
-              execute: ({ text }) => Effect.sync(() => executed.push(`old:${text}`)).pipe(Effect.as({ text })),
-            }),
-          },
-          { deferred: true },
-        )
-        .pipe(Scope.provide(scope))
-      const materialized = yield* service.materialize()
-      yield* Scope.close(scope, Exit.void)
-      yield* service.register(
-        {
+        .register({
          echo: Tool.make({
            description: "Echo text",
            input: Schema.Struct({ text: Schema.String }),
            output: Schema.Struct({ text: Schema.String }),
-            execute: ({ text }) => Effect.sync(() => executed.push(`new:${text}`)).pipe(Effect.as({ text })),
+            execute: ({ text }) => Effect.sync(() => executed.push(`old:${text}`)).pipe(Effect.as({ text })),
          }),
-        },
-        { deferred: true },
-      )
+        })
+        .pipe(Scope.provide(scope))
+      const materialized = yield* service.materialize()
+      yield* Scope.close(scope, Exit.void)
+      yield* service.register({
+        echo: Tool.make({
+          description: "Echo text",
+          input: Schema.Struct({ text: Schema.String }),
+          output: Schema.Struct({ text: Schema.String }),
+          execute: ({ text }) => Effect.sync(() => executed.push(`new:${text}`)).pipe(Effect.as({ text })),
+        }),
+      })

      const settlement = yield* materialized.settle({
        ...call("execute"),
@@ -261,7 +261,7 @@ const echo = Layer.effectDiscard(
        output: Schema.Any,
        execute: () => Effect.succeed({ big: 1n }),
      }),
-    }),
+    }, { codemode: false }),
  ),
 )
 const echoNode = makeLocationNode({ name: "test/session-runner-tools", layer: echo, deps: [ToolRegistry.node] })
@@ -782,7 +782,7 @@ describe("SessionRunnerLLM", () => {
              return { answer: query.toUpperCase() }
            }),
        }),
-      })
+      }, { codemode: false })
      yield* admit(session, "Use application context")
      responses = [reply.tool("call-location", "location_context", { query: "hello" }), []]

@@ -827,7 +827,7 @@ describe("SessionRunnerLLM", () => {
            output: Schema.Struct({ value: Schema.String }),
            execute: () => Effect.sync(() => executions.push("advertised")).pipe(Effect.as({ value: "advertised" })),
          }),
-        })
+        }, { codemode: false })
        .pipe(Scope.provide(scope))
      yield* admit(session, "Use the reloaded tool")
      responses = [
@@ -852,7 +852,7 @@ describe("SessionRunnerLLM", () => {
          output: Schema.Struct({ value: Schema.String }),
          execute: () => Effect.sync(() => executions.push("replacement")).pipe(Effect.as({ value: "replacement" })),
        }),
-      })
+      }, { codemode: false })
      yield* Deferred.succeed(streamGate, undefined)
      yield* Fiber.join(run)

@@ -3189,7 +3189,7 @@ describe("SessionRunnerLLM", () => {
              Effect.mapError(() => new Tool.Failure({ message: "Permission blocked" })),
            ),
        }),
-      })
+      }, { codemode: false })
      yield* admit(session, "Call blocked")

      responses = [reply.tool("call-blocked", "blocked", {}), reply.stop()]
@@ -3221,7 +3221,7 @@ describe("SessionRunnerLLM", () => {
          output: Schema.Struct({}),
          execute: () => Effect.die(new PermissionV2.DeclinedError()),
        }),
-      })
+      }, { codemode: false })
      yield* admit(session, "Call declined")

      response = reply.tool("call-declined", "declined", {})
@@ -3261,7 +3261,7 @@ describe("SessionRunnerLLM", () => {
              Effect.mapError(() => new Tool.Failure({ message: "Use another tool" })),
            ),
        }),
-      })
+      }, { codemode: false })
      yield* admit(session, "Call corrected")

      responses = [reply.tool("call-corrected", "corrected", {}), reply.stop()]
@@ -3321,7 +3321,7 @@ describe("SessionRunnerLLM", () => {
    Effect.gen(function* () {
      const session = yield* setup
      const registry = yield* ToolRegistry.Service
-      yield* registry.register({ permissionfail: permissionFail })
+      yield* registry.register({ permissionfail: permissionFail }, { codemode: false })
      yield* admit(session, "Reject permission")
      responses = [
        reply.tool("call-permission", "permissionfail", {}),
@@ -3366,7 +3366,7 @@ describe("SessionRunnerLLM", () => {
          output: Schema.Struct({}),
          execute: () => Effect.die(new QuestionTool.CancelledError()),
        }),
-      })
+      }, { codemode: false })
      yield* admit(session, "Ask then stop")

      responses = [reply.tool("call-question", "question", {}), []]
@@ -312,14 +312,16 @@ export default Plugin.define({
 })
 ```

-Unsupported characters in tool and group names are normalized to underscores.
+Unsupported characters in tool and namespace names are normalized to underscores.
 The resulting exposed key must begin with a letter and contain at most 64
-letters, digits, underscores, or hyphens. Set `options` on the declaration to
-configure registration with `{ group, deferred }`:
+letters, digits, underscores, or hyphens. Set registration fields on the
+declaration or options with `{ namespace, codemode }`:

- `group` prefixes and groups the exposed tool name.
- `deferred: true` makes the tool available through the deferred `execute`
-  tool instead of exposing it directly.
+- `namespace` prefixes the exposed tool name (and becomes the CodeMode path
+  segment).
+- `codemode` defaults to `true` and makes the tool available through the
+  `execute` CodeMode tool. Set `codemode: false` to expose it directly to the
+  provider.

 The executor receives a second context argument containing `sessionID`,
 `agent`, `assistantMessageID`, and `toolCallID`.
@@ -3,7 +3,6 @@
  "extends": "@tsconfig/bun/tsconfig.json",
  "compilerOptions": {
    "lib": ["ESNext", "DOM", "DOM.Iterable"],
-    "types": ["bun"],
    "noUncheckedIndexedAccess": false,
    "plugins": [
      {
@@ -3,7 +3,6 @@
  "extends": "@tsconfig/bun/tsconfig.json",
  "compilerOptions": {
    "lib": ["ESNext", "DOM", "DOM.Iterable"],
-    "types": ["node"],
    "noUncheckedIndexedAccess": false,
    "plugins": [
      {
@@ -5,8 +5,7 @@
    "noEmit": true,
    "declaration": false,
    "module": "preserve",
-    "moduleResolution": "bundler",
-    "types": ["bun", "node"]
+    "moduleResolution": "bundler"
  },
  "include": ["../src", "."]
 }
@@ -9,7 +9,6 @@
    "declaration": true,
    "stripInternal": true,
    "lib": ["ESNext", "DOM", "DOM.Iterable"],
-    "types": ["node"],
    "noUncheckedIndexedAccess": false,
    "plugins": [
      {
@@ -3,7 +3,6 @@
  "extends": "@tsconfig/bun/tsconfig.json",
  "compilerOptions": {
    "lib": ["ESNext", "DOM", "DOM.Iterable"],
-    "types": ["bun"],
    "noUncheckedIndexedAccess": false
  }
 }
@@ -3,7 +3,6 @@
  "extends": "@tsconfig/bun/tsconfig.json",
  "compilerOptions": {
    "lib": ["ESNext", "DOM", "DOM.Iterable"],
-    "types": ["bun"],
    "noUncheckedIndexedAccess": false,
    "plugins": [
      {
@@ -123,6 +123,17 @@ export function make(config: Config<any, any, any> | DynamicConfig): AnyTool {
  return makeTyped(config)
 }

+/**
+ * Split a flat tool declaration into its registration name, opaque Tool value,
+ * and registration options. Narrowing on `jsonSchema` selects the matching
+ * constructor, so no cast is needed to build the Tool from the flat union.
+ */
+export function fromFlat(flat: FlatDefinition<any, any, any> | FlatDynamicDefinition) {
+  const { name, namespace, codemode, ...config } = flat
+  const tool = "jsonSchema" in config ? makeDynamic(config) : makeTyped(config)
+  return { name, tool, options: { namespace, codemode } satisfies RegisterOptions }
+}
+
 function makeTyped<
  Input extends SchemaType<any>,
  Output extends SchemaType<any>,
@@ -212,14 +223,14 @@ export const validateName = (name: string) =>
    ? Effect.void
    : Effect.fail(new RegistrationError({ name, message: `Invalid tool name: ${name}` }))

-export const registrationEntries = (tools: Readonly<Record<string, AnyTool>>, group?: string) =>
+export const registrationEntries = (tools: Readonly<Record<string, AnyTool>>, namespace?: string) =>
  Object.entries(tools).map(([name, tool]) => {
    const normalized = name.replace(/[^a-zA-Z0-9_-]/g, "_")
-    const parent = group?.replace(/[^a-zA-Z0-9_-]/g, "_")
+    const parent = namespace?.replace(/[^a-zA-Z0-9_-]/g, "_")
    return {
      key: parent === undefined ? normalized : `${parent}_${normalized}`,
      name: normalized,
-      group: parent,
+      namespace: parent,
      tool,
    }
  })
@@ -271,14 +282,68 @@ export interface ToolExecuteAfterEvent {
 }

 export interface RegisterOptions {
-  readonly group?: string
-  readonly deferred?: boolean
+  /** Dotted CodeMode path prefix, e.g. "slack.admin". */
+  readonly namespace?: string
+  /** Defaults to true. False exposes the tool directly to the provider. */
+  readonly codemode?: boolean
+}
+
+export type FlatDefinition<
+  Input extends SchemaType<any>,
+  Output extends SchemaType<any>,
+  Structured extends SchemaType<any> = Output,
+> = {
+  readonly name: string
+  readonly namespace?: string
+  readonly codemode?: boolean
+  readonly description: string
+  readonly input: Input
+  readonly output: Output
+  readonly structured?: Structured
+  readonly toStructuredOutput?: Config<Input, Output, Structured>["toStructuredOutput"]
+  readonly execute: Config<Input, Output, Structured>["execute"]
+  readonly toModelOutput?: Config<Input, Output, Structured>["toModelOutput"]
+}
+
+export type FlatDynamicDefinition = {
+  readonly name: string
+  readonly namespace?: string
+  readonly codemode?: boolean
+  readonly description: string
+  readonly jsonSchema: JsonSchema.JsonSchema
+  readonly outputSchema?: JsonSchema.JsonSchema
+  readonly execute: DynamicConfig["execute"]
 }

 export interface ToolDraft {
+  add<
+    Input extends SchemaType<any>,
+    Output extends SchemaType<any>,
+    Structured extends SchemaType<any> = Output,
+  >(tool: FlatDefinition<Input, Output, Structured>): void
+  add(tool: FlatDynamicDefinition): void
  add(name: string, tool: AnyTool, options?: RegisterOptions): void
 }

+export type Registration = {
+  readonly name: string
+  readonly tool: AnyTool
+  readonly options?: RegisterOptions
+}
+
+/** Run a draft callback and collect the tools it declared, in registration order. */
+export function fromDraft(callback: (draft: ToolDraft) => void) {
+  const registrations: Array<Registration> = []
+  const add = (
+    nameOrTool: string | FlatDefinition<any, any, any> | FlatDynamicDefinition,
+    tool?: AnyTool,
+    options?: RegisterOptions,
+  ) =>
+    registrations.push(typeof nameOrTool === "string" ? { name: nameOrTool, tool: tool!, options } : fromFlat(nameOrTool))
+  callback({ add })
+  return registrations
+}
+
 export interface ToolHooks {
  readonly "execute.before": ToolExecuteBeforeEvent
  readonly "execute.after": ToolExecuteAfterEvent
@@ -16,7 +16,8 @@ export type Definition<
  Structured extends SchemaType<any> = Output,
 > = {
  readonly name: string
-  readonly options?: RegisterOptions
+  readonly namespace?: string
+  readonly codemode?: boolean
  readonly description: string
  readonly input: Input
  readonly output: Output
@@ -37,7 +38,8 @@ export type Definition<

 export type DynamicDefinition = {
  readonly name: string
-  readonly options?: RegisterOptions
+  readonly namespace?: string
+  readonly codemode?: boolean
  readonly description: string
  readonly jsonSchema: JsonSchema.JsonSchema
  readonly outputSchema?: JsonSchema.JsonSchema
@@ -67,11 +69,6 @@ export interface ToolExecuteAfterEvent {
  outputPaths?: ReadonlyArray<string>
 }

-export interface RegisterOptions {
-  readonly group?: string
-  readonly deferred?: boolean
-}
-
 export interface ToolDraft {
  add<
    Input extends SchemaType<any>,
@@ -3,7 +3,6 @@
  "extends": "@tsconfig/bun/tsconfig.json",
  "compilerOptions": {
    "lib": ["ESNext", "DOM", "DOM.Iterable"],
-    "types": ["bun"],
    "noUncheckedIndexedAccess": false
  }
 }
@@ -3,7 +3,6 @@
  "extends": "@tsconfig/bun/tsconfig.json",
  "compilerOptions": {
    "lib": ["ESNext", "DOM", "DOM.Iterable"],
-    "types": ["bun"],
    "noUncheckedIndexedAccess": false
  }
 }
@@ -3,7 +3,6 @@
  "extends": "@tsconfig/bun/tsconfig.json",
  "compilerOptions": {
    "lib": ["ESNext", "DOM", "DOM.Iterable"],
-    "types": ["bun"],
    "noUncheckedIndexedAccess": false
  }
 }
@@ -46,7 +46,6 @@ export function DialogSkill(props: DialogSkillProps) {
      title: skill.name.padEnd(maxWidth),
      description: skill.description?.replace(/\s+/g, " ").trim(),
      value: skill.id,
-      category: "Skills",
      onSelect: () => {
        props.onSelect(skill.id)
        dialog.clear()
@@ -57,7 +56,6 @@ export function DialogSkill(props: DialogSkillProps) {
  return (
    <DialogSelect
      title="Skills"
-      placeholder="Search skills..."
      options={options()}
      renderFilter={!showError()}
      locked={showError()}
Author	SHA1	Message	Date
Aiden Cline	6714f74433	feat(plugin): flat tool draft with namespace Effect draft.add accepts flat tool objects matching Promise ergonomics. Migrate the tool grouping concept fully to namespace: rename MCP's group helper/registration to namespace and thread namespace through the flat Effect and Promise draft declarations.	2026-07-13 00:14:06 -05:00
Aiden Cline	64ca9b8d77	refactor(core): replace deferred tool option with codemode (#36560 )	2026-07-12 21:21:07 -05:00
Kit Langton	a4b91d33d9	fix(tui): align skills dialog copy (#36592 )	2026-07-12 22:02:24 -04:00
Kit Langton	397993e898	fix(client): preserve compatible background service (#36583 )	2026-07-12 21:32:34 -04:00