@ultimat3/mcp 27.10.4 → 27.12.0

package/CLAUDE.md

@@ -34,6 +34,7 @@ import. The CLI wires it.
 | `readonly-sql.ts` · `readonly-sql-calls.ts` | layer 3 of `db.query` — the single-read parse — and `db.migrate`'s branch check · the banned call families |
 | `query-limits.ts` | layer 4 of `db.query` — the row, byte and timeout ceilings, and what truncation reports |
 | `meta-surface.ts` | `surface: 'meta'` catalog: `list_resources` / `describe_resource`, `groups:` boot checks; dispatch stays in `server.ts` |
+| `meta-split.ts` · `meta-split-call.ts` · `meta-host.ts` | `surface: 'meta-split'`: the three dispatchers, the effect boot check · their dispatch (wrong tool, preview, `confirmed_by_user`) · the server half both meta doors call |
 | `list-params.ts` | `listParams` whitelist → the schema `manage_resource` enforces (flat keys: `status_eq`) |
 | `meta-errors.ts` · `framework-error.ts` | meta boot refusals · a thrown value read and rendered (split from `server.ts`) |
 | `server-voice.ts` · `surface-budget.ts` | `instructions`, `errorAudience`, the invalid-args RESULT · `tools/list`/`list_resources` size, measured and budgeted |
@@ -45,6 +46,10 @@ import. The CLI wires it.
   audited under the inner tool. `tools/list` shows what `tools/call` answers PER CALLER: a meta caller
   cannot call a grouped tool by name, a flat caller never sees the meta tools, and every not-found a
   meta caller gets carries `META_UNKNOWN_FIX`. Default `'flat'` builds no `MetaSurface`.
+  **`'meta-split'` is three more doors on the same path** (`As of 2026-10-18`): the effect picks the
+  door and is never defaulted (`X_MCP_EFFECT_UNDECLARED` at boot); a wrong door runs nothing
+  (`X_MCP_WRONG_TOOL`, after visibility, before scope); `delete_resource` previews unless `live:
+  true` and commits only on `confirmed_by_user: true`, both after the policy's actor half.
 
 - `src/index.ts` re-exports `t` from `@ultimat3/schema` **verbatim**, so a `defineAppMcp` file
   imports one package. Never wrap, spread or re-declare it: `t` delegates to `schemaProvider()` on
@@ -202,19 +207,8 @@ import. The CLI wires it.
   second claim, exactly as `ToolRegistry.register` throws on a second tool name — one package
   cannot answer "this name is taken" two ways. `Map.set` made the answer whichever provider was
   wired last, and a `ultimate://` URI is quoted in AGENTS.md files.
-- **`\'` inside a string literal is refused** (`readonly-sql.ts`). `E'\''` is one quote to
-  Postgres and `standard_conforming_strings` decides the plain spelling, so the two readings
-  disagree about where the string ends — which is exactly where a `;` hides.
-  `select E'\'' ; drop table posts --'` was accepted as one read-only statement and handed back
-  verbatim to run. Only inside a single-quoted run: a comment, a `$tag$` body and a quoted
-  identifier are unambiguous and still read fine.
-- **An unterminated run is refused, never swallowed** (`readonly-sql.ts`). The stripper blanks what
-  it believes is inside a literal, so an opening delimiter that never closes hid the whole tail:
-  `select '; delete from members` counted one statement with no mutating keyword and was handed
-  back to run. All four forms now throw `X_MCP_QUERY_REJECTED` — `'`, `"`, `$tag$`, `/* */`. Not
-  exploitable through Postgres (a syntax error either way); the point is that this layer must not
-  be the thing that waves it through. `@ultimat3/admin`'s `/_x` panel failed CLOSED here where this
-  failed open, which is how it was found — a second, differently-behaved copy of one rule.
+- **`\'` inside a string literal is refused** (`readonly-sql.ts`) — why: `docs/history/mcp.md`.
+- **An unterminated run is refused, never swallowed** (`readonly-sql.ts`, all four delimiters, `X_MCP_QUERY_REJECTED`) — why: `docs/history/mcp.md`.
 - **`into` is a write keyword.** `SELECT ... INTO <table>` is `CREATE TABLE AS` in another spelling:
   a DDL write with a read LEADER, so nothing else in the scan sees it. Layer 2's `BEGIN READ ONLY`
   refuses it on the wired path — the point is that this layer must not be the thing that waves it

package/README.md

@@ -250,6 +250,58 @@ else, an optional input key the whitelist left out included (an `isError` result
 `X_INPUT_INVALID`), before the query runs; a
 whitelisted key the input does not declare is `X_MCP_LIST_PARAMS_INVALID` at boot.
 
+### Split by effect: `surface: 'meta-split'`
+
+`As of 2026-10-18`. `manage_resource` runs reads and writes alike, so it cannot carry an honest
+`readOnlyHint`, and a directory that refuses a read+write dispatcher refuses it. `'meta-split'`
+serves the same catalog pair plus three dispatchers, each running only its own effect class:
+
+| Tool | Runs | Input | Hints |
+|---|---|---|---|
+| `read_resource` | every query (`destructive: false`) | `{ resource, action, params? }` | `readOnlyHint: true` |
+| `write_resource` | actions declaring `mcp: { effect: 'write' }` | `{ resource, action, params? }` | `readOnlyHint: false`, `destructiveHint: true` |
+| `delete_resource` | actions declaring `mcp: { effect: 'delete' }` — archive, cancel, delete, an external send, a spend | `{ resource, action, params?, live?, confirmed_by_user }` | `readOnlyHint: false`, `destructiveHint: true` |
+
+```ts
+import { action } from '@ultimat3/action';
+import { defineAppMcp } from '@ultimat3/mcp';
+import { can } from '@ultimat3/policy';
+import { t } from '@ultimat3/schema';
+
+// An action declares its effect in the one mcp block; a query declares none.
+export const archivePost = action({
+  input: t.object({ postId: t.string }),
+  output: t.object({ ok: t.boolean }),
+  policy: can('post:archive'),
+  mcp: { expose: true, description: 'Archive a post', effect: 'delete' },
+  handle: () => ({ ok: true }),
+});
+
+defineAppMcp({
+  include: 'exposed',
+  surface: 'meta-split',
+  groups: { posts: { description: 'Blog posts', tools: ['archivePost'] } },
+});
+```
+
+- **No default.** A grouped write without `effect` is `X_MCP_EFFECT_UNDECLARED` at boot, naming
+  every one; a read declaring one is `X_MCP_EFFECT_CONFLICT`. A `surface` function is held to this
+  once any grouped tool declares an effect; until then its `'meta-split'` answer serves `'meta'`, so
+  an app written before the split boots as it did.
+- **Wrong dispatcher → `X_MCP_WRONG_TOOL`** (an `isError` result, audited `invalid-args`): the cause
+  says `wrong_tool_for_action` and names the tool that runs it (`meta.use_tool`). Nothing ran.
+- **`delete_resource`**: `live` absent or `false` answers the framework's preview, which runs nothing —
+  `{ preview: true, ran: false, resource, action, params, commit_with: { live: true,
+  confirmed_by_user: true } }`, audited `previewed`. An action whose own input declares `live`
+  authors its preview instead: it is handed `live: false` and runs. `live: true` runs only with
+  `confirmed_by_user: true` (the user approved the change, directly or by authorizing the task);
+  anything else is `X_MCP_USER_CONFIRMATION_REQUIRED`, audited `unconfirmed`. Both flags are read
+  top-level or from `params` (nested wins) and never handed to an action that does not declare them.
+  `confirmed_by_user` is required by the schema, so a client sees it at connect time.
+- Order: visibility (absent answer) → effect (`X_MCP_WRONG_TOOL`) → scope → arguments → the policy's
+  actor half → preview / confirmation → `dispatch`, the flat path — same audit line, same bucket.
+- Ungrouped tools (`docs`, `whoami`) stay flat beside the five, exactly as on `'meta'`.
+
 ### What a client is told beyond the schema
 
 `As of 22.10`, MCP 2025-06-18. The projection derives each from the declaration; the primitive's
@@ -265,7 +317,7 @@ whitelisted key the input does not declare is `X_MCP_LIST_PARAMS_INVALID` at boo
 
 A tool's text is **compact JSON** (`jsonResult`; the 2-space form until 22.10). The meta tools
 carry their own hints: `list_resources` and `describe_resource` read-only, `manage_resource` a
-write.
+write; on `'meta-split'`, `read_resource` read-only and the other two destructive.
 
 **Budget test.** `measureMcpSurface(server, caller)` answers `{ toolsList, listResources,
 instructions }` in characters, as serialized on the wire; `assertMcpSurfaceBudget(server, caller,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mcp",
-  "version": "27.10.4",
+  "version": "27.12.0",
   "description": "MCP server, dev tools, and the action-to-tool projection \u2014 one authz system, two surfaces",
   "license": "MIT",
   "type": "module",
@@ -33,14 +33,14 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "27.10.4",
-    "@ultimat3/core": "27.10.4",
-    "@ultimat3/db": "27.10.4",
-    "@ultimat3/entity": "27.10.4",
-    "@ultimat3/http": "27.10.4",
-    "@ultimat3/jobs": "27.10.4",
-    "@ultimat3/policy": "27.10.4",
-    "@ultimat3/query": "27.10.4",
-    "@ultimat3/schema": "27.10.4"
+    "@ultimat3/action": "27.12.0",
+    "@ultimat3/core": "27.12.0",
+    "@ultimat3/db": "27.12.0",
+    "@ultimat3/entity": "27.12.0",
+    "@ultimat3/http": "27.12.0",
+    "@ultimat3/jobs": "27.12.0",
+    "@ultimat3/policy": "27.12.0",
+    "@ultimat3/query": "27.12.0",
+    "@ultimat3/schema": "27.12.0"
   }
 }

package/src/app-tool.ts

@@ -11,7 +11,7 @@
 // apply to routes and miss tools.
 
 import { guardAction, guardActionBeforeInput, InputInvalidError } from '@ultimat3/action';
-import type { Ctx } from '@ultimat3/core';
+import type { Ctx, McpEffect } from '@ultimat3/core';
 import { actorOf, useContext } from '@ultimat3/core';
 import type { KnownPermission } from '@ultimat3/policy';
 import { can } from '@ultimat3/policy';
@@ -42,6 +42,11 @@ export interface AppToolDefinition<TInput extends StandardSchemaV1 = StandardSch
    * rate-limit bucket, so forgetting the flag costs throughput rather than safety.
    */
   readonly destructive?: boolean;
+  /**
+   * `'write'` | `'delete'` — which dispatcher runs this tool on a `'meta-split'` surface, where a
+   * grouped write without one is `X_MCP_EFFECT_UNDECLARED`. Ignored by every other surface.
+   */
+  readonly effect?: McpEffect;
   /** Display name for a client's UI. Absent: none published. */
   readonly title?: string;
   /**
@@ -60,6 +65,7 @@ export interface AnyAppToolDefinition {
   readonly policy: KnownPermission;
   readonly visibleTo?: readonly McpRole[];
   readonly destructive?: boolean;
+  readonly effect?: McpEffect;
   readonly title?: string;
   readonly annotations?: McpToolAnnotations;
   handle(args: { readonly input: unknown; readonly ctx: Ctx }): unknown;
@@ -98,6 +104,7 @@ export function appToolPrimitive(name: string, def: AnyAppToolDefinition): Proje
       description: def.description,
       ...(visibleTo !== undefined ? { visibleTo } : {}),
       ...(def.title !== undefined ? { title: def.title } : {}),
+      ...(def.effect !== undefined ? { effect: def.effect } : {}),
       ...(def.annotations !== undefined ? { annotations: def.annotations } : {}),
     },
     inputJsonSchema: toWireSchema(def.input),

package/src/audit.ts

@@ -28,6 +28,11 @@ export type McpOutcome =
    * one there was expired. Expected — `mcpConfirmations` answers it by design — so `info`.
    */
   | 'unconfirmed'
+  /**
+   * `delete_resource` without `live: true`: resolved and admitted, and answered with a preview of
+   * the call instead of running it. Its own outcome so "previewed" never reads as "committed".
+   */
+  | 'previewed'
   /**
    * The handler threw something that is not an authz denial: a non-authz framework refusal
    * (`db.migrate` aimed at prod), or a bug. Both want a human — a projected action rejecting
@@ -52,13 +57,14 @@ const DENIAL_CODES: ReadonlySet<string> = new Set([
  * Codes that mean the CALLER got the arguments wrong, in a way the published JSON Schema could
  * not have refused. `X_ADMIN_INVALID` is the case: `@ultimat3/admin` publishes a `type` per field
  * and nothing else, so an entity's own rules are the first thing a value meets, and a mistyped
- * `admin.create` is a client misreading a schema — `invalid-args`, at `info`.
+ * `admin.create` is a client misreading a schema — `invalid-args`, at `info`. `X_MCP_WRONG_TOOL`
+ * is the same kind of slip one level up: the right action on the wrong `meta-split` dispatcher.
  *
  * `X_INPUT_INVALID` deliberately stays OUT: a projected action publishes its whole schema, so
  * input this server already validated failing inside the action means the two have drifted, and
  * that wants a human.
  */
-const ARGUMENT_CODES: ReadonlySet<string> = new Set(['X_ADMIN_INVALID']);
+const ARGUMENT_CODES: ReadonlySet<string> = new Set(['X_ADMIN_INVALID', 'X_MCP_WRONG_TOOL']);
 
 /**
  * `mcpConfirmations`' answers for a call no live approval covers. A rejection is NOT here: a human
@@ -67,6 +73,7 @@ const ARGUMENT_CODES: ReadonlySet<string> = new Set(['X_ADMIN_INVALID']);
 const UNCONFIRMED_CODES: ReadonlySet<string> = new Set([
   'X_MCP_CONFIRMATION_PENDING',
   'X_MCP_CONFIRMATION_EXPIRED',
+  'X_MCP_USER_CONFIRMATION_REQUIRED',
 ]);
 
 /** Classify a code a tool threw. Denials are outcome 3; everything else wants a human. */
@@ -125,6 +132,7 @@ const LEVEL: ReadonlyMap<McpOutcome, 'info' | 'warn' | 'error'> = new Map([
   ['policy-denied', 'warn'],
   ['invalid-args', 'info'],
   ['unconfirmed', 'info'],
+  ['previewed', 'info'],
   ['failed', 'error'],
 ]);
 // An outcome is a closed union, so the `Map` is total; `?? 'error'` is the type's witness, not a

package/src/errors.ts

@@ -36,6 +36,10 @@ export const MCP_ERROR_CODES = [
   'X_MCP_CONFIRMATION_TOOL_UNKNOWN',
   'X_MCP_CONFIRMATION_CONTESTED',
   'X_MCP_CONFIRMATION_ARGUMENTS_MISMATCH',
+  'X_MCP_EFFECT_UNDECLARED',
+  'X_MCP_EFFECT_CONFLICT',
+  'X_MCP_WRONG_TOOL',
+  'X_MCP_USER_CONFIRMATION_REQUIRED',
 ] as const;
 
 export type McpErrorCode = (typeof MCP_ERROR_CODES)[number];
@@ -75,6 +79,11 @@ export const MCP_ERROR_TITLES: Readonly<Record<McpErrorCode, string>> = {
   X_MCP_CONFIRMATION_CONTESTED: 'identical concurrent MCP calls kept racing one confirmation',
   X_MCP_CONFIRMATION_ARGUMENTS_MISMATCH:
     'an MCP confirmation approval did not carry the arguments the agent sent',
+  X_MCP_EFFECT_UNDECLARED: 'an MCP tool on a meta-split surface declares no effect',
+  X_MCP_EFFECT_CONFLICT: 'a read-only MCP tool declares an effect',
+  X_MCP_WRONG_TOOL: 'a meta-split action was called through the wrong dispatcher',
+  X_MCP_USER_CONFIRMATION_REQUIRED:
+    'a delete_resource commit did not carry confirmed_by_user: true',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is

package/src/from-action.ts

@@ -98,6 +98,7 @@ export function toolFrom(listed: ListedPrimitive): AnyMcpTool {
   const mutates = primitive.mutates ?? true;
   const visibleTo = primitive.mcp?.visibleTo;
   const listParams = primitive.mcp?.listParams;
+  const effect = primitive.mcp?.effect;
   const title = primitive.mcp?.title;
   const outputSchema = primitive.outputJsonSchema;
   const wrap = primitive.outputWrap;
@@ -112,6 +113,7 @@ export function toolFrom(listed: ListedPrimitive): AnyMcpTool {
     destructive: mutates,
     ...(visibleTo !== undefined ? { visibleTo } : {}),
     ...(listParams !== undefined ? { listParams } : {}),
+    ...(effect !== undefined ? { effect } : {}),
     ...(primitive.admit === undefined
       ? {}
       : { admit: (caller: McpCaller) => primitive.admit?.(caller.actor) }),

package/src/index.ts

@@ -131,12 +131,25 @@ export { MCP_IDEMPOTENCY_KEY_ARG } from './idempotency-arg';
 export type { ListFilterOp, McpListParams } from './list-params';
 export { DEFAULT_LIST_MAX_LIMIT, listParamsSchema } from './list-params';
 export {
+  McpEffectConflictError,
+  McpEffectUndeclaredError,
   McpGroupConflictError,
   McpGroupUnknownError,
   McpListParamsInvalidError,
   McpSurfaceInvalidError,
+  McpUserConfirmationRequiredError,
+  McpWrongToolError,
   META_UNKNOWN_FIX,
 } from './meta-errors';
+export type { McpEffectClass } from './meta-split';
+export {
+  DELETE_RESOURCE,
+  effectOf,
+  READ_RESOURCE,
+  SPLIT_DISPATCHERS,
+  toolForEffect,
+  WRITE_RESOURCE,
+} from './meta-split';
 export type {
   DescribedAction,
   McpResourceGroup,

package/src/meta-call.ts

@@ -1,35 +1,20 @@
-// A META caller's `tools/call`: the three meta tools, and the refusal of a grouped tool called by
-// its flat name. Split from `server.ts` for the size ceiling only — it holds no gate of its own:
-// every call it runs goes back through the server's `resolve` → `dispatch`, the flat path.
+// A META caller's `tools/call`: the meta tools, and the refusal of a grouped tool called by its
+// flat name; the split surface's dispatchers continue in `meta-split-call.ts`. Split from
+// `server.ts` for the size ceiling only — it holds no gate of its own: every call it runs goes back
+// through the server's `resolve` → `dispatch`, the flat path.
 
-import type { McpAuditor } from './audit-hook';
 import { META_UNKNOWN_FIX } from './meta-errors';
-import type { MetaSurface } from './meta-surface';
-import {
-  DESCRIBE_RESOURCE,
-  LIST_RESOURCES,
-  META_TOOL_ENTRIES,
-  renderCatalog,
-  schemaOf,
-} from './meta-surface';
-import type { McpCaller, ToolRegistry, ToolResolution } from './registry';
+import type { MetaHost } from './meta-host';
+import { resolveAddressed } from './meta-host';
+import { splitCall } from './meta-split-call';
+import { DESCRIBE_RESOURCE, LIST_RESOURCES, MetaSurface, renderCatalog } from './meta-surface';
+import type { McpCaller } from './registry';
 import { jsonResult, textResult } from './registry';
 import { validateArgs } from './validate-args';
 import type { JsonRpcId, JsonRpcResponse } from './wire';
 import { errorResponse, METHOD_NOT_FOUND, resultResponse } from './wire';
 
-/** The server's own two steps, handed in so this file cannot grow a second path. */
-export interface MetaHost {
-  readonly tools: ToolRegistry;
-  readonly audit: McpAuditor;
-  dispatch(
-    id: JsonRpcId,
-    name: string,
-    resolved: ToolResolution,
-    caller: McpCaller,
-  ): Promise<JsonRpcResponse>;
-  notFound(id: JsonRpcId, name: string, caller: McpCaller, fix: string): JsonRpcResponse;
-}
+export type { MetaHost } from './meta-host';
 
 export interface MetaRequest {
   readonly id: JsonRpcId;
@@ -45,7 +30,8 @@ export async function metaCall(
   request: MetaRequest,
 ): Promise<JsonRpcResponse | undefined> {
   const { id, name, caller } = request;
-  const entry = META_TOOL_ENTRIES.find((tool) => tool.name === name);
+  const surface = meta.surfaceFor(caller) === 'meta-split' ? 'meta-split' : 'meta';
+  const entry = MetaSurface.entriesFor(surface).find((tool) => tool.name === name);
   if (entry === undefined) {
     return meta.isGrouped(name) ? host.notFound(id, name, caller, META_UNKNOWN_FIX) : undefined;
   }
@@ -55,7 +41,7 @@ export async function metaCall(
   }
   if (name === LIST_RESOURCES) {
     host.audit.toolCall({ tool: name, outcome: 'ok', caller });
-    return resultResponse(id, textResult(renderCatalog(meta.listResources(caller))));
+    return resultResponse(id, textResult(renderCatalog(meta.listResources(caller), surface)));
   }
   if (name === DESCRIBE_RESOURCE) {
     const described = meta.describe(args.value['resources'] as readonly string[], caller);
@@ -71,22 +57,19 @@ export async function metaCall(
     host.audit.toolCall({ tool: name, outcome: 'ok', caller });
     return resultResponse(id, jsonResult({ resources: described.resources }));
   }
+  if (surface === 'meta-split')
+    return splitCall(host, meta, { id, name, caller, args: args.value });
   // `manage_resource`: address → the SAME resolve and dispatch a flat call takes, audited under
   // the tool it reached. Visibility first (a hidden pair is an absent pair), then the shared
-  // resolver's scope → args. A list whitelist's issues REPLACE the tool schema's: both are pure
-  // checks with nothing run between them, so which is evaluated first is invisible — the answer
-  // names the whitelist, which is the contract `describe_resource` published.
+  // resolver's scope → args (`resolveAddressed`).
   const resource = args.value['resource'] as string;
   const action = args.value['action'] as string;
   const tool = meta.locate(resource, action, caller);
   if (tool === undefined) return host.notFound(id, action, caller, META_UNKNOWN_FIX);
-  const input = args.value['params'] ?? {};
-  let resolved = host.tools.resolve(action, input, caller);
-  if (resolved.kind !== 'scope-denied' && resolved.kind !== 'not-found') {
-    const listed = validateArgs(schemaOf(tool), input);
-    if (!listed.ok) {
-      resolved = { kind: 'invalid-args', name: action, issues: listed.issues, tool };
-    }
-  }
-  return host.dispatch(id, action, resolved, caller);
+  return host.dispatch(
+    id,
+    action,
+    resolveAddressed(host, tool, args.value['params'] ?? {}, caller),
+    caller,
+  );
 }

package/src/meta-errors.ts

@@ -66,3 +66,69 @@ export class McpSurfaceInvalidError extends UltimateError {
     });
   }
 }
+
+/** A grouped write on a `'meta-split'` surface that names no effect: no dispatcher can run it. */
+export class McpEffectUndeclaredError extends UltimateError {
+  readonly names: readonly string[];
+
+  constructor(input: { names: readonly string[] }) {
+    const names = input.names.join(', ');
+    super({
+      code: 'X_MCP_EFFECT_UNDECLARED',
+      cause: `surface can be 'meta-split', and ${input.names.length} grouped write(s) declare no effect (${names}), so neither write_resource nor delete_resource can be picked for them`,
+      fix: `mcp: { expose: true, effect: 'write' }   # on ${names} — 'delete' for an archive, a cancel, a send or a spend; a hand-written tool takes tools: { <name>: { effect } }`,
+    });
+    this.names = input.names;
+  }
+}
+
+/** A grouped READ that declares an effect: a read is `read_resource`'s, whatever it says. */
+export class McpEffectConflictError extends UltimateError {
+  constructor(input: { name: string; effect: string }) {
+    super({
+      code: 'X_MCP_EFFECT_CONFLICT',
+      cause: `"${input.name}" is a read (a query, or destructive: false) and declares effect: '${input.effect}'; on a meta-split surface a read is always run by read_resource`,
+      fix: `mcp: { expose: true }   # on "${input.name}", without effect — or, if it changes state, make it an action (or a tool with destructive: true) and keep effect: '${input.effect}'`,
+    });
+  }
+}
+
+/** The right action, the wrong dispatcher. Names the dispatcher that runs it; nothing ran. */
+export class McpWrongToolError extends UltimateError {
+  readonly useTool: string;
+
+  constructor(input: { resource: string; action: string; called: string; useTool: string }) {
+    const call = `${input.useTool}({ resource: "${input.resource}", action: "${input.action}", params })`;
+    super({
+      code: 'X_MCP_WRONG_TOOL',
+      cause: `${input.resource}.${input.action} is not run by ${input.called}; it is run by ${input.useTool} (wrong_tool_for_action). Nothing ran`,
+      fix: `${call}   # the same params, on ${input.useTool}`,
+      callerFix: `call ${call} with the same params`,
+      meta: {
+        resource: input.resource,
+        action: input.action,
+        called: input.called,
+        use_tool: input.useTool,
+      },
+    });
+    this.useTool = input.useTool;
+  }
+}
+
+/** A `delete_resource` commit (`live: true`) without the user's approval. Nothing ran. */
+export class McpUserConfirmationRequiredError extends UltimateError {
+  constructor(input: { resource: string; action: string }) {
+    const call = `delete_resource({ resource: "${input.resource}", action: "${input.action}", params, live: true, confirmed_by_user: true })`;
+    super({
+      code: 'X_MCP_USER_CONFIRMATION_REQUIRED',
+      cause: `${input.resource}.${input.action} commits only with confirmed_by_user: true; nothing ran`,
+      fix: `${call}   # once the user approved this change, directly or by authorizing the task that includes it; live: false previews it without running`,
+      callerFix: `ask the user to approve ${input.resource}.${input.action}, then call ${call} with the same params`,
+      meta: {
+        resource: input.resource,
+        action: input.action,
+        retry_with: { confirmed_by_user: true },
+      },
+    });
+  }
+}

package/src/meta-host.ts

@@ -0,0 +1,43 @@
+// The server's half of a meta dispatch, handed to `meta-call.ts` and `meta-split-call.ts` so neither
+// can grow a second path: its `dispatch` IS the flat `tools/call`'s resolve → run → audit.
+
+import type { McpAuditor } from './audit-hook';
+import { schemaOf } from './meta-surface';
+import type { AnyMcpTool, McpCaller, ToolRegistry, ToolResolution } from './registry';
+import { validateArgs } from './validate-args';
+import type { JsonRpcId, JsonRpcResponse } from './wire';
+
+/** The server's own two steps, handed in so this file cannot grow a second path. */
+export interface MetaHost {
+  readonly tools: ToolRegistry;
+  readonly audit: McpAuditor;
+  dispatch(
+    id: JsonRpcId,
+    name: string,
+    resolved: ToolResolution,
+    caller: McpCaller,
+  ): Promise<JsonRpcResponse>;
+  notFound(id: JsonRpcId, name: string, caller: McpCaller, fix: string): JsonRpcResponse;
+  /** A coded refusal rendered and audited exactly as a thrown one — `tool-thrown.ts`. */
+  refuse(id: JsonRpcId, name: string, error: unknown, caller: McpCaller): JsonRpcResponse;
+}
+
+/**
+ * The shared resolver's scope → args for a tool a dispatcher located, with a list whitelist's
+ * issues REPLACING the tool schema's: both are pure checks with nothing run between them, so which
+ * is evaluated first is invisible — the answer names the whitelist, which is the contract
+ * `describe_resource` published.
+ */
+export function resolveAddressed(
+  host: MetaHost,
+  tool: AnyMcpTool,
+  input: unknown,
+  caller: McpCaller,
+): ToolResolution {
+  const resolved = host.tools.resolve(tool.name, input, caller);
+  if (resolved.kind === 'scope-denied' || resolved.kind === 'not-found') return resolved;
+  const listed = validateArgs(schemaOf(tool), input);
+  return listed.ok
+    ? resolved
+    : { kind: 'invalid-args', name: tool.name, issues: listed.issues, tool };
+}

package/src/meta-split-call.ts

@@ -0,0 +1,129 @@
+// `read_resource` / `write_resource` / `delete_resource` on a `'meta-split'` surface: locate (the
+// visibility gate) → the tool its effect names, else `X_MCP_WRONG_TOOL` → the shared resolver →
+// for `delete_resource`, preview unless `live: true`, and commit only with `confirmed_by_user:
+// true` → the server's `dispatch`. Every call that runs goes through the flat path's one dispatch.
+
+import {
+  McpUserConfirmationRequiredError,
+  McpWrongToolError,
+  META_UNKNOWN_FIX,
+} from './meta-errors';
+import type { MetaHost } from './meta-host';
+import { resolveAddressed } from './meta-host';
+import { DELETE_RESOURCE, effectOf, toolForEffect } from './meta-split';
+import type { MetaSurface } from './meta-surface';
+import { schemaOf } from './meta-surface';
+import type { AnyMcpTool, McpCaller, ToolArgs } from './registry';
+import { jsonResult } from './registry';
+import { admitted } from './tool-thrown';
+import type { JsonRpcId, JsonRpcResponse } from './wire';
+import { resultResponse } from './wire';
+
+/** The tool-level arguments of `delete_resource`, accepted top-level or (where models put them) in `params`. */
+const LIVE = 'live';
+const CONFIRMED = 'confirmed_by_user';
+
+export interface SplitRequest {
+  readonly id: JsonRpcId;
+  /** The dispatcher called: `read_resource`, `write_resource` or `delete_resource`. */
+  readonly name: string;
+  readonly caller: McpCaller;
+  /** The envelope, already validated against the dispatcher's own schema. */
+  readonly args: ToolArgs;
+}
+
+export async function splitCall(
+  host: MetaHost,
+  meta: MetaSurface,
+  request: SplitRequest,
+): Promise<JsonRpcResponse> {
+  const { id, name, caller, args } = request;
+  const resource = args['resource'] as string;
+  const action = args['action'] as string;
+  const tool = meta.locate(resource, action, caller);
+  if (tool === undefined) return host.notFound(id, action, caller, META_UNKNOWN_FIX);
+  // `assertEffects` refused an undeclared write at boot, so `effectOf` answers for a served tool.
+  const effect = effectOf(tool) ?? 'delete';
+  const useTool = toolForEffect(effect);
+  if (useTool !== name) {
+    // Visibility already passed, and the effect is what `list_resources` shows this caller: the
+    // refusal names nothing the catalog did not.
+    const wrong = new McpWrongToolError({ resource, action, called: name, useTool });
+    return host.refuse(id, action, wrong, caller);
+  }
+  const params = isRecord(args['params']) ? args['params'] : {};
+  if (name !== DELETE_RESOURCE) {
+    return host.dispatch(id, action, resolveAddressed(host, tool, params, caller), caller);
+  }
+  const lifted = liftToolArgs(args, params, tool);
+  const resolved = resolveAddressed(host, tool, lifted.params, caller);
+  if (resolved.kind !== 'ok') return host.dispatch(id, action, resolved, caller);
+  // The policy's actor half before any preview or confirmation prompt: a caller who may never run
+  // this gets the denial, never an answer that rehearses the call.
+  const refused = admitted(tool, caller);
+  if (refused !== undefined) return host.refuse(id, action, refused, caller);
+  if (lifted.live && lifted.confirmed !== true) {
+    return host.refuse(
+      id,
+      action,
+      new McpUserConfirmationRequiredError({ resource, action }),
+      caller,
+    );
+  }
+  // An action that declares `live` authors its own preview: it is handed `live: false` and runs.
+  if (lifted.live || lifted.ownsPreview) return host.dispatch(id, action, resolved, caller);
+  host.audit.toolCall({ tool: action, outcome: 'previewed', caller });
+  return resultResponse(
+    id,
+    jsonResult({
+      preview: true,
+      ran: false,
+      resource,
+      action,
+      params: resolved.args,
+      commit_with: { live: true, [CONFIRMED]: true },
+    }),
+  );
+}
+
+interface Lifted {
+  readonly params: Readonly<Record<string, unknown>>;
+  readonly live: boolean;
+  readonly confirmed: unknown;
+  /** The action's own input declares `live`, so the preview is the action's to answer. */
+  readonly ownsPreview: boolean;
+}
+
+/**
+ * `live` and `confirmed_by_user` are the dispatcher's, not the action's: read top-level or from
+ * `params` (nested wins, the precedence every other argument has) and removed from what the action
+ * is handed — except `live` for an action whose own input declares it, which is then always
+ * handed an explicit boolean so its preview branch never depends on its own default.
+ */
+function liftToolArgs(
+  args: ToolArgs,
+  params: Readonly<Record<string, unknown>>,
+  tool: AnyMcpTool,
+): Lifted {
+  const declared = schemaOf(tool).properties ?? {};
+  const ownsPreview = Object.hasOwn(declared, LIVE);
+  // Nested wins, ALWAYS — a declared field too: a nested `confirmed_by_user: false` beside a
+  // top-level `true` is a refusal, and reading the top level there would commit anyway.
+  const pick = (key: string): unknown => (Object.hasOwn(params, key) ? params[key] : args[key]);
+  const live = pick(LIVE) === true;
+  const rest: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(params)) {
+    if ((key === LIVE || key === CONFIRMED) && !Object.hasOwn(declared, key)) continue;
+    Object.defineProperty(rest, key, {
+      value,
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    });
+  }
+  if (ownsPreview) rest[LIVE] = live;
+  return { params: rest, live, confirmed: pick(CONFIRMED), ownsPreview };
+}
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);

package/src/meta-split.ts

@@ -0,0 +1,116 @@
+// The `'meta-split'` surface's dispatchers: `read_resource`, `write_resource`, `delete_resource`
+// in place of the one `manage_resource`, each picked from the action's declared effect. A client
+// decides whether to ask its user from a TOOL's annotations alone, and a directory refuses a tool
+// that both reads and writes — so the split is by tool, never by a flag inside the envelope.
+// Catalog and boot check here; the dispatch is `meta-split-call.ts`, on the shared path.
+
+import type { McpEffect } from '@ultimat3/core';
+import { McpEffectConflictError, McpEffectUndeclaredError } from './meta-errors';
+import type { AnyMcpTool, ToolListEntry } from './registry';
+import type { JsonSchema } from './wire';
+
+export const READ_RESOURCE = 'read_resource';
+export const WRITE_RESOURCE = 'write_resource';
+export const DELETE_RESOURCE = 'delete_resource';
+export const SPLIT_DISPATCHERS: readonly string[] = [
+  READ_RESOURCE,
+  WRITE_RESOURCE,
+  DELETE_RESOURCE,
+];
+
+/** What a grouped tool does, as the split surface reads it: a read, or its declared effect. */
+export type McpEffectClass = 'read' | McpEffect;
+
+/** The dispatcher that runs each class. */
+export function toolForEffect(effect: McpEffectClass): string {
+  if (effect === 'read') return READ_RESOURCE;
+  return effect === 'write' ? WRITE_RESOURCE : DELETE_RESOURCE;
+}
+
+/**
+ * `destructive === false` is a read, as `headOf` and `verbClass` read it; anything else is its
+ * declared effect, or `undefined` — which `assertEffects` refuses at boot, so a served tool always
+ * has one.
+ */
+export function effectOf(tool: AnyMcpTool): McpEffectClass | undefined {
+  return tool.destructive === false ? 'read' : tool.effect;
+}
+
+/**
+ * Boot: every grouped write names its effect, and no read names one. No default either way — a
+ * wrong one hides a deletion behind `write_resource`, or asks deletion-grade consent for an
+ * update. Every undeclared name is collected first, so one boot lists them all.
+ */
+export function assertEffects(tools: Iterable<AnyMcpTool>): void {
+  const undeclared: string[] = [];
+  for (const tool of tools) {
+    if (tool.destructive === false) {
+      if (tool.effect !== undefined) {
+        throw new McpEffectConflictError({ name: tool.name, effect: tool.effect });
+      }
+    } else if (tool.effect !== 'write' && tool.effect !== 'delete') {
+      undeclared.push(tool.name);
+    }
+  }
+  if (undeclared.length > 0) throw new McpEffectUndeclaredError({ names: undeclared.sort() });
+}
+
+const ENVELOPE: Readonly<Record<string, JsonSchema>> = {
+  resource: { type: 'string', description: 'Resource name, as list_resources shows it.' },
+  action: { type: 'string', description: 'Action name, as list_resources shows it.' },
+  params: {
+    type: 'object',
+    description: "The action's parameters, as describe_resource lists them.",
+  },
+};
+
+const envelope = (extra: Readonly<Record<string, JsonSchema>> = {}, required: string[] = []) =>
+  ({
+    type: 'object',
+    properties: { ...ENVELOPE, ...extra },
+    required: ['resource', 'action', ...required],
+    additionalProperties: false,
+  }) satisfies JsonSchema;
+
+/** The three dispatchers as `tools/list` publishes them. Descriptions state facts, never orders. */
+export const SPLIT_TOOL_ENTRIES: readonly ToolListEntry[] = [
+  {
+    name: READ_RESOURCE,
+    title: 'Read',
+    description:
+      'Runs one read-only action of one resource: { resource, action, params }. Changes nothing. list_resources shows which actions it runs (untagged ones); any other action is refused with X_MCP_WRONG_TOOL naming its tool.',
+    inputSchema: envelope(),
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+  },
+  {
+    name: WRITE_RESOURCE,
+    title: 'Write',
+    description:
+      'Runs one action of one resource that creates or changes state: { resource, action, params }. Same policies, scopes and audit as calling the action directly. Runs the actions list_resources tags (write); any other is refused with X_MCP_WRONG_TOOL naming its tool.',
+    inputSchema: envelope(),
+    // An update can overwrite state, so the honest hint for a write is still destructive.
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+  },
+  {
+    name: DELETE_RESOURCE,
+    title: 'Delete, send or spend',
+    description:
+      "Runs one action that archives, cancels or deletes, sends something outside the app, or commits money: { resource, action, params, live, confirmed_by_user }. live: false or absent answers a preview — the framework's, which runs nothing, or the action's own when its input declares live; live: true runs it, only with confirmed_by_user: true. Runs the actions list_resources tags (delete).",
+    inputSchema: envelope(
+      {
+        live: {
+          type: 'boolean',
+          description:
+            "true runs the action; false or absent answers a preview: the framework's runs nothing, and an action whose params declare live answers its own.",
+        },
+        confirmed_by_user: {
+          type: 'boolean',
+          description:
+            'true when the user approved this change, directly or by authorizing the task that includes it. A live call without true runs nothing and answers X_MCP_USER_CONFIRMATION_REQUIRED.',
+        },
+      },
+      ['confirmed_by_user'],
+    ),
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+  },
+];

package/src/meta-surface.ts

@@ -8,20 +8,26 @@
 // A grouped tool is reachable ONLY through `manage_resource` for a meta caller, and a flat caller
 // never sees the meta tools: what `tools/list` shows is what `tools/call` answers, per caller.
 
+import type { McpEffect } from '@ultimat3/core';
 import { McpToolDuplicateError } from './errors';
 import { assertListParams, listParamsSchema } from './list-params';
 import { McpGroupConflictError, McpGroupUnknownError, McpSurfaceInvalidError } from './meta-errors';
+import { assertEffects, SPLIT_DISPATCHERS, SPLIT_TOOL_ENTRIES } from './meta-split';
 import type { AnyMcpTool, McpCaller, ToolListEntry } from './registry';
 import { visibleToCaller } from './registry';
 import type { JsonSchema } from './wire';
 import { NO_ARGS } from './wire';
 
-export type McpSurface = 'flat' | 'meta';
+/**
+ * `'meta'`: one `manage_resource` runs every grouped tool. `'meta-split'`: `read_resource`,
+ * `write_resource` and `delete_resource` run them by declared effect (`meta-split.ts`).
+ */
+export type McpSurface = 'flat' | 'meta' | 'meta-split';
 
 /**
  * Which surface a caller is served. A function decides per POPULATION — staff meta, customers flat
  * — from the caller alone, never the arguments. A function that throws or answers anything but the
- * literal `'meta'` serves `'flat'`: the two surfaces reach the same tools under the same gates, so
+ * literal `'meta'` or `'meta-split'` serves `'flat'`: the two surfaces reach the same tools under the same gates, so
  * the fallback changes the shape of the catalog, never what the caller may do.
  */
 export type McpSurfaceOption = McpSurface | ((caller: McpCaller) => McpSurface);
@@ -44,6 +50,7 @@ export const META_TOOL_NAMES: readonly string[] = [
   LIST_RESOURCES,
   DESCRIBE_RESOURCE,
   MANAGE_RESOURCE,
+  ...SPLIT_DISPATCHERS,
 ];
 
 /** The three constant entries, as `tools/list` publishes them. */
@@ -90,9 +97,31 @@ export const META_TOOL_ENTRIES: readonly ToolListEntry[] = [
   },
 ];
 
+/**
+ * The catalog pair as the `'meta-split'` surface publishes it: the same tools, worded for three
+ * dispatchers instead of one. `'meta'` keeps its entries byte for byte.
+ */
+const CATALOG_ENTRIES: readonly ToolListEntry[] = META_TOOL_ENTRIES.filter(
+  (entry) => entry.name !== MANAGE_RESOURCE,
+).map((entry) =>
+  entry.name === DESCRIBE_RESOURCE
+    ? {
+        ...entry,
+        description:
+          "Full input schemas for the actions of one or more resources (batched), each with the tool that runs it. For when list_resources' one-line params are not enough. Read-only.",
+      }
+    : {
+        ...entry,
+        description:
+          'The catalog: every resource this caller may use, each action with a one-line parameter hint and the tool that runs it — read_resource, write_resource or delete_resource. Read-only.',
+      },
+);
+
 export interface MetaAction {
   readonly name: string;
   readonly kind: 'query' | 'action';
+  /** An action's declared effect — the dispatcher that runs it on `'meta-split'`. A query has none. */
+  readonly effect?: McpEffect;
   readonly description: string;
   /** One line an agent can compose a call from: `radicado: string, note?: string`. */
   readonly params: string;
@@ -116,13 +145,17 @@ export class MetaSurface {
   /** Tool name → the resource that answers it. */
   readonly #home: ReadonlyMap<string, string>;
   readonly #tools: ReadonlyMap<string, AnyMcpTool>;
+  /** Every grouped tool's effect was checked at boot, so `'meta-split'` may be served. */
+  readonly #split: boolean;
 
   private constructor(
     option: McpSurfaceOption,
     groups: ReadonlyMap<string, McpResourceGroup>,
     home: ReadonlyMap<string, string>,
     tools: ReadonlyMap<string, AnyMcpTool>,
+    split: boolean,
   ) {
+    this.#split = split;
     this.#option = option;
     this.#groups = groups;
     this.#home = home;
@@ -151,13 +184,13 @@ export class MetaSurface {
         cause: `groups: declares ${entries.length} resource(s), and surface is 'flat' for every caller, so no caller would ever see them`,
       });
     }
-    if (option !== 'meta' && typeof option !== 'function') {
+    if (option !== 'meta' && option !== 'meta-split' && typeof option !== 'function') {
       throw new McpSurfaceInvalidError({ cause: `surface is ${JSON.stringify(option)}` });
     }
     if (entries.length === 0) {
       throw new McpSurfaceInvalidError({
         cause:
-          "surface can be 'meta', and groups: declares no resource, so list_resources would always answer empty",
+          "surface can be 'meta' or 'meta-split', and groups: declares no resource, so list_resources would always answer empty",
       });
     }
     const tools = new Map(input.tools.map((tool) => [tool.name, tool]));
@@ -177,21 +210,39 @@ export class MetaSurface {
         home.set(name, group);
       }
     }
-    return new MetaSurface(option, new Map(entries), home, tools);
+    // 'meta-split' is held to the split's contract at boot. A FUNCTION is held to it once any
+    // grouped tool declares an effect — the app has opted in; until then it can only serve 'meta'
+    // (`surfaceFor`), so an app written before the split boots exactly as it did.
+    const grouped = [...home.keys()].flatMap((name) => tools.get(name) ?? []);
+    const split =
+      option === 'meta-split' ||
+      (typeof option === 'function' && grouped.some((tool) => tool.effect !== undefined));
+    if (split) assertEffects(grouped);
+    return new MetaSurface(option, new Map(entries), home, tools, split);
   }
 
-  /** The surface this caller is served. Fail-closed to `'flat'` — see `McpSurfaceOption`. */
+  /**
+   * The surface this caller is served. Fail-closed to `'flat'` — see `McpSurfaceOption`. A function's
+   * `'meta-split'` serves `'meta'` while no grouped tool declares an effect (see `build`).
+   */
   surfaceFor(caller: McpCaller): McpSurface {
     const option = this.#option;
     if (typeof option !== 'function') return option;
     try {
-      return option(caller) === 'meta' ? 'meta' : 'flat';
+      const chosen = option(caller);
+      if (chosen === 'meta-split') return this.#split ? 'meta-split' : 'meta';
+      return chosen === 'meta' ? 'meta' : 'flat';
     } catch {
       return 'flat';
     }
   }
 
-  /** True when a META caller must reach this tool through `manage_resource`, not by its name. */
+  /** The constant `tools/list` entries of a meta surface: the catalog pair plus its dispatcher(s). */
+  static entriesFor(surface: Exclude<McpSurface, 'flat'>): readonly ToolListEntry[] {
+    return surface === 'meta' ? META_TOOL_ENTRIES : [...CATALOG_ENTRIES, ...SPLIT_TOOL_ENTRIES];
+  }
+
+  /** True when a META caller must reach this tool through a dispatcher, not by its name. */
   isGrouped(name: string): boolean {
     return this.#home.has(name);
   }
@@ -278,19 +329,25 @@ export function schemaOf(tool: AnyMcpTool): JsonSchema {
  *   listCases {radicado?: string} — List the account's cases.
  *   closeCase (action; confirms) {id: string} — Close a case.
  * ```
+ *
+ * `'meta-split'` tags a write with the tool that runs it instead — `(write)` or `(delete)` — and
+ * its header names the three dispatchers; untagged still means a read.
  */
-export function renderCatalog(resources: readonly MetaResource[]): string {
+export function renderCatalog(
+  resources: readonly MetaResource[],
+  surface: 'meta' | 'meta-split' = 'meta',
+): string {
   if (resources.length === 0) return 'No resources are available to this caller.';
-  const lines = [
-    `${resources.length} resource(s). Run one with manage_resource({resource, action, params}); describe_resource({resources:["<name>"]}) has the full input schemas. Untagged = read-only query; (action) may write; (confirms) waits for a human; … = more in describe_resource.`,
-  ];
+  const lines = [surface === 'meta' ? metaHeader(resources.length) : splitHeader(resources.length)];
   for (const resource of resources) {
     const hoisted = hoistScopes(resource.actions);
     const said = hoisted.line === '' ? '' : ` (${hoisted.line})`;
     lines.push('', `${resource.name}${said} — ${oneLine(resource.description)}`);
     for (const action of resource.actions) {
       const tags = [
-        ...(action.kind === 'action' ? ['action'] : []),
+        ...(action.kind === 'action'
+          ? [surface === 'meta' ? 'action' : (action.effect ?? 'action')]
+          : []),
         ...(action.confirms === true ? ['confirms'] : []),
         ...(action.scope === undefined || hoisted.kinds.has(action.kind)
           ? []
@@ -303,6 +360,12 @@ export function renderCatalog(resources: readonly MetaResource[]): string {
   return lines.join('\n');
 }
 
+const metaHeader = (count: number): string =>
+  `${count} resource(s). Run one with manage_resource({resource, action, params}); describe_resource({resources:["<name>"]}) has the full input schemas. Untagged = read-only query; (action) may write; (confirms) waits for a human; … = more in describe_resource.`;
+
+const splitHeader = (count: number): string =>
+  `${count} resource(s). Untagged = read-only, run with read_resource({resource, action, params}); (write) runs with write_resource({resource, action, params}); (delete) archives, sends or spends, run with delete_resource({resource, action, params, live, confirmed_by_user}) — live: false previews it. describe_resource({resources:["<name>"]}) has the full input schemas. (confirms) waits for a human; … = more in describe_resource.`;
+
 /**
  * The scopes said once on the resource line, and the kinds whose actions no longer repeat theirs.
  * One scope for every action → `scope cases`. Otherwise per kind, because a token split into
@@ -339,11 +402,13 @@ function sharedScope(actions: readonly MetaAction[]): string | undefined {
 const oneLine = (text: string): string => text.replace(/\s+/g, ' ').trim();
 
 function headOf(tool: AnyMcpTool): Omit<MetaAction, 'params'> {
+  const effect = tool.destructive === false ? undefined : tool.effect;
   return {
     name: tool.name,
     // `=== false`, as `ToolRegistry.verbClass` meters it — one answer per tool. An omitted flag is
     // an action: the header's "untagged = read-only query" holds only for a DECLARED read.
     kind: tool.destructive === false ? 'query' : 'action',
+    ...(effect === undefined ? {} : { effect }),
     description: tool.description,
     ...(tool.confirms === true ? { confirms: true } : {}),
     ...(tool.scope === undefined ? {} : { scope: tool.scope }),

package/src/projectable.ts

@@ -151,6 +151,7 @@ function exposureOf(
     ...(declared.description === undefined ? {} : { description: declared.description }),
     ...(declared.visibleTo === undefined ? {} : { visibleTo: declared.visibleTo }),
     ...(declared.listParams === undefined ? {} : { listParams: declared.listParams }),
+    ...(declared.effect === undefined ? {} : { effect: declared.effect }),
     ...(declared.title === undefined ? {} : { title: declared.title }),
     ...(declared.annotations === undefined ? {} : { annotations: declared.annotations }),
   };

package/src/registry.ts

@@ -18,7 +18,7 @@
 // The outcomes are orthogonal on purpose. A tool can be visible and still refused for a
 // narrow token; a token holding every scope still cannot see a tool its role may not.
 
-import type { Actor } from '@ultimat3/core';
+import type { Actor, McpEffect } from '@ultimat3/core';
 import { McpToolDuplicateError } from './errors';
 import type { McpListParams } from './list-params';
 import type { ArgIssue } from './validate-args';
@@ -143,6 +143,11 @@ export interface McpTool<A extends ToolArgs = ToolArgs> {
    * the flat surface ignores it (the tool's `inputSchema` is its contract there).
    */
   readonly listParams?: McpListParams;
+  /**
+   * The action's effect class (`'write'` | `'delete'`), as its `mcp` block declared it. Picks the
+   * dispatcher on a `'meta-split'` surface; a read (`destructive: false`) carries none.
+   */
+  readonly effect?: McpEffect;
   /**
    * A catalog hint: this write answers "awaiting confirmation" and a human finishes it. Shown by
    * `list_resources` so an agent plans for the hand-off; it changes nothing about the call.

package/src/server.ts

@@ -12,8 +12,9 @@ import { McpProtocolError, McpScopeDeniedError, TOOL_UNKNOWN_FIX } from './error
 import { asFrameworkError, forAudience } from './framework-error';
 import { metaCall } from './meta-call';
 import { META_UNKNOWN_FIX } from './meta-errors';
+import { SPLIT_DISPATCHERS } from './meta-split';
 import type { McpResourceGroups, McpSurfaceOption, MetaResource } from './meta-surface';
-import { MANAGE_RESOURCE, META_TOOL_ENTRIES, META_TOOL_NAMES, MetaSurface } from './meta-surface';
+import { MANAGE_RESOURCE, META_TOOL_NAMES, MetaSurface } from './meta-surface';
 import { promptListEntry, promptsGet, visiblePrompts } from './prompts-get';
 import type {
   AnyMcpTool,
@@ -214,9 +215,12 @@ export class McpServer {
     const flat = this.tools.list(caller);
     const meta = this.metaFor(caller);
     if (meta === undefined) return flat;
-    // Constant: the three meta tools plus whatever the app left ungrouped (`docs`, `whoami`).
-    return [...flat.filter((tool) => !meta.isGrouped(tool.name)), ...META_TOOL_ENTRIES].sort(
-      (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0),
+    // Constant: the meta tools plus whatever the app left ungrouped (`docs`, `whoami`).
+    const entries = MetaSurface.entriesFor(
+      meta.surfaceFor(caller) === 'meta' ? 'meta' : 'meta-split',
+    );
+    return [...flat.filter((tool) => !meta.isGrouped(tool.name)), ...entries].sort((a, b) =>
+      a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
     );
   }
 
@@ -231,7 +235,7 @@ export class McpServer {
   /** The meta surface when THIS caller is served it, else `undefined`. */
   private metaFor(caller: McpCaller): MetaSurface | undefined {
     const meta = this.meta;
-    return meta !== undefined && meta.surfaceFor(caller) === 'meta' ? meta : undefined;
+    return meta !== undefined && meta.surfaceFor(caller) !== 'flat' ? meta : undefined;
   }
 
   /**
@@ -250,7 +254,7 @@ export class McpServer {
     // An unresolvable call is refused before it runs, so charging it the strict bucket
     // only costs a broken client — it never hands an unproven verb the cheap one.
     if (typeof name !== 'string') return 'write';
-    if (this.meta !== undefined && name === MANAGE_RESOURCE) {
+    if (this.meta !== undefined && (name === MANAGE_RESOURCE || SPLIT_DISPATCHERS.includes(name))) {
       // Billed as the tool it reaches, so the dispatcher is never a cheap door to a write.
       const args = params?.['arguments'];
       const action = isRecord(args) ? args['action'] : undefined;
@@ -277,6 +281,8 @@ export class McpServer {
           audit: this.audit,
           dispatch: (at, tool, resolved, who) => this.dispatch(at, tool, resolved, who),
           notFound: (at, tool, who, fix) => this.notFound(at, tool, who, fix),
+          refuse: (at, tool, error, who) =>
+            thrownResponse(at, tool, error, who, this.voice.errorAudience, this.audit),
         },
         meta,
         { id, name, rawArgs: params['arguments'], caller },