fix(core): enforce agent-scoped ownership boundaries

packages/core/tools/src/code-mode.ts

@@ -1,12 +1,14 @@
 /**
  * Code Mode: the `run_code` tool and its dispatch bridge. The model writes a
- * TypeScript program; the bridge hands it to `ctx.codeRuntime` with one
- * async binding per registered tool, serializes every binding call through a
- * per-run queue onto `ToolRegistry.execute()` (so `tools/pre-execute` /
- * `tools/post-execute` gate sub-calls exactly like native ones), logs each
- * sub-dispatch as a `tool/code-dispatch` session event, and returns only the
- * program's curated output. The registry itself decides WHEN this tool
- * exists (its `mode` config); this module owns only the tool and the bridge.
+ * TypeScript program; the bridge hands it to `ctx.codeRuntime` with one async
+ * binding per end capability visible to the calling agent, then serializes
+ * every binding call through a per-run queue onto `ToolRegistry.execute()`.
+ * Sub-calls therefore traverse the complete pre/guard/around/post/final-result
+ * pipeline exactly like native calls and carry the outer execution's opaque
+ * token for correlation. The bridge logs each sub-dispatch as a
+ * `tool/code-dispatch` session event and returns only the program's curated
+ * output. The registry itself decides WHEN this tool exists (its `mode`
+ * config); this module owns only the tool and the bridge.
  *
  * @module @deepseek-ai/dsh-tools/src/code-mode
  */
@@ -205,6 +207,7 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () =>
             name,
             arguments: normalized.dispatched,
             ...exec.agent ? { agent: exec.agent } : {},
+            parent: exec.token,
             signal: runController.signal,
           })
           const text = textOf(result.content)

packages/core/tools/src/index.ts

@@ -1,15 +1,15 @@
 /**
  * Tool registry and execution pipeline. Plugins register tools; the registry
  * feeds schemas into the system prompt, and `execute()` dispatches each call
- * through `tools/pre-execute` (the allow/deny gate) → `tools/execute` (an
- * around-dispatch wrapper for timeout/retry/metrics plugins) → `tools/post-execute`
- * (inspect/replace the result, attach context) for sandbox, permission, and hook
- * plugins to gate or transform a call.
+ * through `tools/pre-execute` (the extensible allow/deny gate) → monotonic
+ * registered guards → `tools/execute` (an around-dispatch wrapper for
+ * timeout/retry/metrics plugins) → `tools/post-execute` (inspect/replace the
+ * result, attach context) → the observe-only `tools/result` notification.
  *
  * The registry also owns HOW its tools are presented to the model — its
  * `mode` config: `'native'` (every tool as a wire function definition,
- * today's behavior and the default), `'code'` (the wire carries exactly one
- * tool, `run_code`, plus a generated TypeScript SDK prompt section), or
+ * today's behavior and the default), `'code'` (the registry's canonical wire
+ * contribution is one tool, `run_code`, plus a generated TypeScript SDK prompt section), or
  * `'both'`. See `code-mode.ts` (the tool + dispatch bridge) and
  * `ts-types.ts` (the SDK codegen); design in the Code Mode RFC.
  *
@@ -21,8 +21,9 @@ import z from 'schemastery'
 import { scopeOf, scopeTarget } from '@deepseek-ai/dsh-scope'
 import type { ScopeKey, Scoped } from '@deepseek-ai/dsh-scope'
 import type { CallId, ContentBlock, ToolSchema } from '@deepseek-ai/dsh-llm'
-import { HarnessError } from '@deepseek-ai/dsh-llm'
+import { deepFreeze, HarnessError } from '@deepseek-ai/dsh-llm'
 import type { Agent, HookContext } from '@deepseek-ai/dsh-agent'
+import { isJsonValue } from '@deepseek-ai/dsh-session'
 import type { ToolProviderResult } from '@deepseek-ai/dsh-system-prompt'
 import type { CodeRuntime } from '@deepseek-ai/dsh-code-runtime'
 import type { ToolCallView, ToolResultView } from './presentation.ts'
@@ -105,10 +106,13 @@ declare module 'cordis' {
      * unknown tool) is already normalized to an `isError` result by the time a
      * listener's `await next()` returns, so a wrapper never sees a raw throw from
      * the tool body. This is the seam a timeout/retry/metrics plugin wraps: it can
-     * mutate `exec` (e.g. replace `exec.signal` with a per-call deadline) BEFORE
-     * `next()` and inspect the result AFTER. (Cordis `next()` ignores any passed
-     * arguments and re-invokes downstream with the shared payload, so a wrapper
-     * mutates `exec` in place rather than passing a new object to `next()`.)
+     * set or replace the one mutable field, `exec.signal` (e.g. with a per-call
+     * deadline), BEFORE `next()`, restore/delete it afterward, and inspect the result AFTER. Call identity
+     * (`token`, `callId`, `name`, `arguments`, `agent`, and `parent`) is immutable throughout the
+     * pipeline so a wrapper cannot change which capability or scope was
+     * authorized. (Cordis `next()` ignores passed arguments and re-invokes
+     * downstream with the shared payload, so a wrapper changes `exec.signal` in
+     * place rather than passing a new object to `next()`.)
      * Multiple listeners compose by registration order — an outer one wraps the
      * inner ones plus dispatch.
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): the carrier is keyed by
@@ -139,6 +143,21 @@ declare module 'cordis' {
      * @mode waterfall
      */
     'tools/post-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, result: ToolExecutionResult, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>
+    /**
+     * Awaited notification of the authoritative FINAL tool outcome, after the
+     * complete pre/execute/post pipeline, final lossless-JSON validation, and
+     * outer error normalization.
+     * Unlike the three waterfalls, this seam cannot transform the result: each
+     * listener receives the now-frozen execution object and a deep-frozen result
+     * snapshot; listener failures are contained and logged, and
+     * {@link ToolRegistry.execute} still returns the outcome.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by
+     * `exec.agent`, using the same carrier as the pipeline.
+     * @param exec - the execution object that traversed the pipeline.
+     * @param result - a deep-frozen snapshot of the final returned result.
+     * @mode parallel
+     */
+    'tools/result'(this: Scoped<ToolRegistry>, exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): Promise<void> | void
     /**
      * A tool was registered or unregistered, or a scoped restriction changed
      * (the available tool set changed — possibly for one scope only). An
@@ -152,10 +171,8 @@ declare module 'cordis' {
   }
 }
 
-// TODO(review): revisit these shapes when the first real tools and
-// sandbox/permission plugins land (e.g. a concurrency-safety hint for
-// parallel execution — Claude Code partitions read-only tools; phase 1
-// executes sequentially).
+// TODO(review): revisit these shapes when concurrency metadata becomes useful
+// (for example, a read-only hint that would permit safe parallel execution).
 
 /**
  * What a tool's `execute` returns. The bare {@link ContentBlock}`[]` form is the
@@ -214,17 +231,54 @@ export interface ToolResult {
   meta?: unknown
 }
 
-/** One pending tool call, as it flows through the execution pipeline (`tools/pre-execute` → dispatch → `tools/post-execute`). */
-export interface ToolExecution {
-  callId: CallId
-  name: string
-  /** Parsed JSON arguments (unknown — tools validate their own input). */
-  arguments: unknown
+declare const toolExecutionTokenBrand: unique symbol
+
+/** Tokens minted in this module; a cast or JavaScript object cannot forge membership. */
+const executionTokens = new WeakSet<object>()
+
+/**
+ * Opaque, immutable identity for one trip through the tool pipeline. Nested
+ * transports carry the enclosing execution's token instead of its live object,
+ * so observe-only result listeners can correlate calls without gaining a
+ * mutation path into an outer around-dispatch wrapper.
+ */
+export interface ToolExecutionToken {
+  readonly [toolExecutionTokenBrand]: true
+}
+
+/**
+ * Caller-supplied description of one tool call. {@link ToolRegistry.execute}
+ * snapshots this input into a pipeline-owned {@link ToolExecution}; callers do
+ * not choose the execution token.
+ */
+export interface ToolExecutionInput {
+  readonly callId: CallId
+  readonly name: string
+  /** Losslessly JSON-serializable parsed arguments (tools validate their own schema). */
+  readonly arguments: unknown
   /** The agent on whose behalf the call runs (set by the agent loop). */
-  agent?: Agent
+  readonly agent?: Agent
+  /**
+   * Opaque token of the enclosing transport execution, when one exists. Code
+   * Mode sets this on SDK sub-dispatches so commit-style observers can wait for
+   * the outer `run_code` outcome without receiving its live mutable execution.
+   */
+  readonly parent?: ToolExecutionToken
   signal?: AbortSignal
 }
 
+/**
+ * One pending tool call inside the registry pipeline. Call identity, the
+ * registry-assigned {@link token}, and a lossless-JSON-validated, deep-frozen
+ * clone of the parsed arguments are immutable from the first policy listener onward, while an
+ * around-dispatch wrapper may set, replace, or remove only `signal`. The
+ * registry freezes the complete object before `tools/result` observers run.
+ */
+export interface ToolExecution extends ToolExecutionInput {
+  /** Registry-assigned identity shared with nested calls only as their opaque `parent` token. */
+  readonly token: ToolExecutionToken
+}
+
 /** Structured error metadata for a failed tool call (alongside the model-facing text). */
 export interface ToolErrorInfo {
   name: string
@@ -255,7 +309,6 @@ export interface ToolExecutionResult {
    * text in `content` is always present; this is extra structure for code.
    */
   error?: ToolErrorInfo
-  /**
   /**
    * Extra model-facing context a `tools/post-execute` listener attached for the
    * NEXT request (Claude Code's PostToolUse `additionalContext`). It is NOT part
@@ -318,17 +371,28 @@ export type PostToolDecision =
  * is stringified.
  */
 function errorMessage(error: unknown): string {
-  if (error instanceof Error) return error.message
-  if (typeof error === 'object' && error !== null
-    && 'message' in error && typeof error.message === 'string') {
-    return error.message
+  try {
+    if (error instanceof Error) return error.message
+    if (typeof error === 'object' && error !== null
+      && 'message' in error && typeof error.message === 'string') {
+      return error.message
+    }
+    return String(error)
+  } catch {
+    // A hostile thrown value can trap `instanceof`, property access, or string
+    // coercion. Error normalization is the outermost safety boundary, so its
+    // fallback must itself be total.
+    return '<unprintable thrown value>'
   }
-  return String(error)
 }
 
 /** Structured `{ name, code }` for a thrown HarnessError, else undefined. */
 function errorInfo(error: unknown): ToolErrorInfo | undefined {
-  return error instanceof HarnessError ? { name: error.name, code: error.code } : undefined
+  try {
+    return error instanceof HarnessError ? { name: error.name, code: error.code } : undefined
+  } catch {
+    return undefined
+  }
 }
 
 /** How the registry presents its tools to the model (see {@link Config.mode}). */
@@ -338,9 +402,9 @@ export type ToolPresentationMode = 'native' | 'code' | 'both'
 export interface Config {
   /**
    * The presentation mode. `'native'` (the default) contributes every
-   * registered tool as a wire function definition — byte-for-byte today's
-   * behavior. `'code'` contributes exactly ONE wire tool, `run_code`, plus
-   * the generated `tools:sdk` prompt section declaring every other tool as a
+   * visible end capability as a native wire function definition. Under
+   * `'code'` this registry contributes exactly ONE wire tool,
+   * `run_code`, plus the generated `tools:sdk` prompt section declaring every other tool as a
    * TypeScript API the program calls. `'both'` contributes every native
    * definition AND `run_code` + the SDK section. Non-native modes require a
    * loaded `ctx.codeRuntime` whose `language` is `'typescript'` — a missing
@@ -371,11 +435,27 @@ export interface ToolRestriction {
   deny?: string[]
 }
 
+/**
+ * A monotonic execution guard evaluated after every `tools/pre-execute`
+ * listener and before the tool body. Returning a reason denies the call;
+ * returning `undefined` leaves it unchanged. Because guards have no allow
+ * result, listener ordering cannot turn a denial back into permission.
+ * @param execution - the identity-protected call after extensible pre-execute policy completed.
+ * @returns a final denial reason, or `undefined` to leave the call allowed.
+ */
+export type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined
+
+/** One guard registration; the wrapper preserves independent duplicate registrations. */
+interface ToolGuardRegistration {
+  guard: ToolGuard
+}
+
 /**
  * Tool registry (`ctx.tools`): tool plugins register definitions; the agent
- * loop executes calls through the `tools/pre-execute` → `tools/execute` →
- * `tools/post-execute` pipeline. The registry contributes its schemas into the
- * system-prompt assembly — WHICH schemas is governed by its `mode` config
+ * loop executes calls through the `tools/pre-execute` → guards →
+ * `tools/execute` → `tools/post-execute` → `tools/result` pipeline. The
+ * registry contributes its schemas into the system-prompt assembly — WHICH
+ * schemas is governed by its `mode` config
  * (see {@link Config.mode}); under a non-native mode it also owns the reserved
  * `run_code` presentation transport and the `tools:sdk` prompt section.
  *
@@ -402,6 +482,9 @@ export class ToolRegistry extends Service {
   private scoped = new Map<ScopeKey, Map<string, ToolDefinition>>()
   /** Snapshot-at-registration restriction filters, per scope (see {@link restrict}). */
   private restrictions = new Map<ScopeKey, ToolRestriction[]>()
+  /** Monotonic post-policy guards, split into global and per-agent layers. */
+  private globalGuards = new Set<ToolGuardRegistration>()
+  private scopedGuards = new Map<ScopeKey, Set<ToolGuardRegistration>>()
   private readonly mode: ToolPresentationMode
   /** Reserved presentation transport, kept outside the filterable registration layers. */
   private readonly codeTransport: ToolDefinition | undefined
@@ -418,7 +501,7 @@ export class ToolRegistry extends Service {
     // the filterable global/scoped capability layers.
     this.codeTransport = this.mode === 'native'
       ? undefined
-      : createRunCodeTool(this, () => this.requireCodeRuntime())
+      : deepFreeze(createRunCodeTool(this, () => this.requireCodeRuntime()))
     ctx.systemPrompt.tools(context => this.wireSchemas(context.scope))
     if (this.mode !== 'native') {
       ctx.systemPrompt.section({
@@ -436,6 +519,11 @@ export class ToolRegistry extends Service {
           return renderToolsSdk(this.schemas(context.scope).filter(schema => schema.name !== RUN_CODE_NAME))
         },
       })
+      // These are presentation infrastructure, not optional end capabilities.
+      // Protect them at their owner: assembly listeners may still transform
+      // ordinary tools and prose, but cannot silently leave Code Mode without
+      // its only wire transport or the SDK that tells the model how to use it.
+      ctx.systemPrompt.protect({ sections: ['tools:sdk'], tools: [RUN_CODE_NAME] })
     }
   }
 
@@ -495,8 +583,12 @@ export class ToolRegistry extends Service {
    * the shadowing feature, not an error; the global-duplicate message names
    * `agent.ctx` as the per-agent alternative), or if a non-native mode reserves
    * the `run_code` name for its presentation transport. The visible schema set
-   * flows into prompt assembly automatically. Disposed with the calling
-   * fiber. Emits `tools/change` on register/unregister.
+   * flows into prompt assembly automatically. Registration validates and
+   * clones the JSON parameters, copies scalar fields, binds each callback once
+   * to the caller's definition as its method receiver, and freezes the stored
+   * snapshot; later mutation or callback replacement on the input object does
+   * not rewrite the registry. Disposed with the calling fiber. Emits
+   * `tools/change` on register/unregister.
    * @param definition - the tool's schema plus its execute (and optional
    *   presentation) functions.
    * @returns the disposer that unregisters the tool. The exact
@@ -505,24 +597,52 @@ export class ToolRegistry extends Service {
    */
   register(definition: ToolDefinition): () => Promise<void> | void {
     const scope = scopeOf(this.ctx)
-    if (this.codeTransport !== undefined && definition.name === RUN_CODE_NAME) {
+    // A schema crosses the same model/log boundary as execution arguments.
+    // Validate BEFORE cloning because structuredClone silently turns some
+    // forbidden values (for example class instances) into plain records, then
+    // validate the detached value again to contain hostile getters that change
+    // between inspection and snapshotting. A frozen Map is still mutable, so
+    // deepFreeze alone is not a sufficient registration boundary.
+    if (!isJsonValue(definition.parameters)) {
+      throw new TypeError('tool parameters must be losslessly JSON-serializable')
+    }
+    const parameters = structuredClone(definition.parameters)
+    if (!isJsonValue(parameters)) {
+      throw new TypeError('tool parameters must be stable losslessly JSON-serializable data')
+    }
+    // Bind once so replacing a callback on the caller-owned definition after
+    // registration cannot change dispatch, while preserving the historical
+    // method receiver (`this === definition`) for callbacks that use it.
+    const execute = definition.execute.bind(definition)
+    const presentCall = definition.presentCall?.bind(definition)
+    const presentResult = definition.presentResult?.bind(definition)
+    const snapshot: ToolDefinition = deepFreeze({
+      name: definition.name,
+      description: definition.description,
+      parameters,
+      execute,
+      ...definition.timeoutMs !== undefined ? { timeoutMs: definition.timeoutMs } : {},
+      ...presentCall !== undefined ? { presentCall } : {},
+      ...presentResult !== undefined ? { presentResult } : {},
+    })
+    if (this.codeTransport !== undefined && snapshot.name === RUN_CODE_NAME) {
       throw new Error(`tool name "${RUN_CODE_NAME}" is reserved for the Code Mode presentation transport and cannot be registered or shadowed`)
     }
     const dispose = this.ctx.effect(function* (this: ToolRegistry) {
       const layer = scope === undefined ? this.global : this.layerFor(scope)
-      if (layer.has(definition.name)) {
+      if (layer.has(snapshot.name)) {
         throw new Error(scope === undefined
-          ? `tool "${definition.name}" is already registered (for a per-agent variant, register through that agent's \`agent.ctx\` instead)`
-          : `tool "${definition.name}" is already registered in this scope`)
+          ? `tool "${snapshot.name}" is already registered (for a per-agent variant, register through that agent's \`agent.ctx\` instead)`
+          : `tool "${snapshot.name}" is already registered in this scope`)
       }
-      layer.set(definition.name, definition)
+      layer.set(snapshot.name, snapshot)
       // Yield the rollback BEFORE emitting `tools/change`: a generator effect
       // collects each yielded disposer before the next step runs, so a throwing
       // `tools/change` listener removes the tool instead of leaking it (a leak
       // would wedge the duplicate-name check until restart). The duplicate
       // throw above fires before any mutation — it leaks nothing.
       yield () => {
-        layer.delete(definition.name)
+        layer.delete(snapshot.name)
         // An emptied scope layer is dropped so a disposed scope leaves no
         // residue keyed by its (dead) key.
         if (scope !== undefined && layer.size === 0) this.scoped.delete(scope)
@@ -604,6 +724,30 @@ export class ToolRegistry extends Service {
     return dispose
   }
 
+  /**
+   * Register a monotonic guard after the extensible `tools/pre-execute`
+   * waterfall. A plain-context guard applies globally; one registered through
+   * `agent.ctx` applies only to that agent. Any matching guard may deny by
+   * returning a reason, while no guard can force-allow a call another guard
+   * denied. The exact effect disposer is returned for ordered ownership and
+   * HMR cleanup.
+   * @param guard - synchronous check; a returned string denies the execution.
+   * @returns the exact disposer that unregisters the guard.
+   */
+  guard(guard: ToolGuard): () => Promise<void> | void {
+    const scope = scopeOf(this.ctx)
+    const registration = { guard }
+    const dispose = this.ctx.effect(function* (this: ToolRegistry) {
+      const layer = scope === undefined ? this.globalGuards : this.guardLayerFor(scope)
+      layer.add(registration)
+      yield () => {
+        layer.delete(registration)
+        if (scope !== undefined && layer.size === 0) this.scopedGuards.delete(scope)
+      }
+    }.bind(this), 'tools.guard()')
+    return dispose
+  }
+
   /** The (created-on-demand) scoped layer for `scope`. */
   private layerFor(scope: ScopeKey): Map<string, ToolDefinition> {
     let layer = this.scoped.get(scope)
@@ -614,6 +758,43 @@ export class ToolRegistry extends Service {
     return layer
   }
 
+  /** Get or create the guard layer for one agent scope. */
+  private guardLayerFor(scope: ScopeKey): Set<ToolGuardRegistration> {
+    let layer = this.scopedGuards.get(scope)
+    if (layer === undefined) {
+      layer = new Set()
+      this.scopedGuards.set(scope, layer)
+    }
+    return layer
+  }
+
+  /** First monotonic denial from the global then matching scoped guard layers. */
+  private guardReason(exec: ToolExecution): string | undefined {
+    // Guards are policy, not another transform seam. The pipeline execution's
+    // identity and arguments are already protected; freeze a detached view so
+    // an untyped guard cannot replace the wrapper-mutable signal either.
+    const view: Readonly<ToolExecution> = Object.freeze({ ...exec })
+    for (const { guard } of this.globalGuards) {
+      const reason = guard(view)
+      if (reason !== undefined) return this.assertGuardReason(reason)
+    }
+    if (exec.agent !== undefined) {
+      for (const { guard } of this.scopedGuards.get(exec.agent) ?? []) {
+        const reason = guard(view)
+        if (reason !== undefined) return this.assertGuardReason(reason)
+      }
+    }
+    return undefined
+  }
+
+  /** Runtime boundary for JavaScript/casted guards: only strings can deny. */
+  private assertGuardReason(reason: unknown): string {
+    if (typeof reason !== 'string') {
+      throw new TypeError(`tools.guard() must return a denial string or undefined, got ${typeof reason}`)
+    }
+    return reason
+  }
+
   /** Whether every restriction registered for `scope` admits the global tool `name` (intersection semantics). */
   private admits(scope: ScopeKey | undefined, name: string): boolean {
     if (scope === undefined) return true
@@ -707,8 +888,9 @@ export class ToolRegistry extends Service {
   }
 
   /**
-   * Execute one tool call through the `tools/pre-execute` → `tools/execute`
-   * (around dispatch) → `tools/post-execute` pipeline. `pre-execute` is the gate
+   * Execute one tool call through the `tools/pre-execute` → guards →
+   * `tools/execute` (around dispatch) → `tools/post-execute` → `tools/result`
+   * pipeline. `pre-execute` is the extensible gate
    * (allow/deny), `tools/execute` wraps core dispatch (a timeout/retry/metrics
    * seam), and `post-execute` is the inspect/transform seam; core dispatch sits
    * as the base `next()` of the `tools/execute` waterfall. The whole thing is
@@ -719,74 +901,177 @@ export class ToolRegistry extends Service {
    * tool is not registered (or not visible to the calling agent — a
    * restricted-away global is exactly as absent as a nonexistent one), the
    * result is an `isError` carrying a `UNKNOWN_TOOL` structured error. A thrown
-   * {@link HarnessError} surfaces its `{ name, code }` on the result.
-   * @param exec - the call to run (name, parsed arguments, caller agent, signal).
+   * {@link HarnessError} surfaces its `{ name, code }` on the result. Before
+   * the final observe-only notification, the authoritative outcome must survive
+   * a lossless JSON round trip; an invalid outcome is normalized to an error.
+   * Caller-owned arguments must survive lossless-JSON validation before and
+   * after cloning; a violation normalizes to an error before policy or dispatch.
+   * @param exec - the single-use call input; its identity is snapshotted and
+   *   protected before policy runs.
    * @returns the final result after every waterfall; failures resolve as
    *   `isError` results, never rejections.
    */
-  async execute(exec: ToolExecution): Promise<ToolExecutionResult> {
+  async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult> {
+    let execution: ToolExecution
     try {
-      // --- Gate: tools/pre-execute. A deny (or an ask, which degrades to deny
-      // until the permission system lands) skips dispatch entirely. The
-      // carrier keys the dispatch by exec.agent, so an `agent.ctx` listener
-      // gates only its own agent's calls (agent-less calls are subject-less).
-      const carrier = scopeTarget(this, exec.agent)
-      const decision = await this.ctx.waterfall(
-        carrier, 'tools/pre-execute', exec,
-        () => Promise.resolve<PreToolDecision>({ kind: 'allow' }),
-      )
-      if (decision.kind !== 'allow') {
-        // deny → isError. ask has no permission UI yet, so degrade to deny
-        // (FIXME(permissions)): a forthcoming permission system turns `ask` into
-        // a real prompt; today it is the conservative "not allowed".
-        const reason = decision.kind === 'deny'
-          ? decision.reason
-          : decision.reason ?? `tool "${exec.name}" requires approval (not yet supported)`
-        const denied: ToolExecutionResult = {
-          callId: exec.callId,
-          content: [{ type: 'text', text: `Error: ${reason}` }],
-          isError: true,
-        }
-        return await this.postExecute(exec, denied)
-      }
-
-      // --- Around-dispatch: tools/execute. The base `next` is the dispatch-
-      // with-normalization thunk — the tool body's own try/catch turns a throw
-      // into an isError result so a wrapper (and post-execute) can inspect it;
-      // an unknown tool routes through the same catch. A `tools/execute` listener
-      // (e.g. a timeout plugin) wraps this thunk: it may mutate `exec` before
-      // delegating and inspect the normalized result after. Dispatched with the
-      // same carrier as the gate, so an `agent.ctx` wrapper wraps only its own
-      // agent's calls. ---
-      const result = await this.ctx.waterfall(
-        carrier, 'tools/execute', exec,
-        async (): Promise<ToolExecutionResult> => {
-          try {
-            // Resolve through the CALLER's visible view ({@link get}): a scoped
-            // tool shadows its global name-twin for that agent, and a
-            // restricted-away global tool is exactly as absent as a nonexistent
-            // one — same UNKNOWN_TOOL result, no capability leak in the error.
-            const tool = this.get(exec.name, exec.agent)
-            if (!tool) throw new ToolNotFoundError(exec.name)
-            // Normalize the two `execute` return shapes: a bare ContentBlock[] (no
-            // meta) or a { content, meta } object (a tool attaching a private
-            // presentation payload). An array IS the content; the object carries it.
-            const returned = await tool.execute(exec.arguments, exec)
-            const content = Array.isArray(returned) ? returned : returned.content
-            const meta = Array.isArray(returned) ? undefined : returned.meta
-            return { callId: exec.callId, content, isError: false, ...meta !== undefined ? { meta } : {} }
-          } catch (error: unknown) {
-            return toolErrorResult(exec.callId, error)
-          }
-        },
-      )
-
-      return await this.postExecute(exec, result)
+      execution = this.prepareExecution(exec)
     } catch (error: unknown) {
-      // Outer backstop: a throwing pre/post-execute listener (or the waterfall
-      // machinery) becomes an isError result, never a turn failure.
-      return toolErrorResult(exec.callId, error)
+      // Contract-violating non-JSON or non-cloneable arguments cannot enter a
+      // pipeline whose logged and executed forms must agree. Still publish one
+      // scoped final outcome, using an immutable identity shell, so result
+      // observers retain their every-call guarantee without seeing the invalid
+      // value.
+      execution = Object.freeze({
+        token: createExecutionToken(),
+        callId: exec.callId,
+        name: exec.name,
+        arguments: undefined,
+        ...exec.agent !== undefined ? { agent: exec.agent } : {},
+        ...isExecutionToken(exec.parent) ? { parent: exec.parent } : {},
+        ...exec.signal !== undefined ? { signal: exec.signal } : {},
+      })
+      const result = toolErrorResult(execution.callId, error)
+      await this.notifyResult(execution, result)
+      return result
     }
+    let result: ToolExecutionResult
+    try {
+      // Validate the authoritative FINAL result, not merely the tool body's
+      // intermediate return. Post-policy may replace content or attach context,
+      // and every one of these fields is session-bound. Reject anything that
+      // cannot round-trip losslessly through the durable JSON log before the
+      // observe-only `tools/result` commit point sees success.
+      result = this.snapshotExecutionResult(execution, await this.executePipeline(execution))
+    } catch (error: unknown) {
+      // Outer backstop: a throwing pre/post-execute listener, guard, or the
+      // waterfall machinery becomes an isError result, never a turn failure.
+      result = toolErrorResult(execution.callId, error)
+    }
+    await this.notifyResult(execution, result)
+    return result
+  }
+
+  /** Snapshot one call into a shared pipeline object with immutable identity and mutable cancellation. */
+  private prepareExecution(input: ToolExecutionInput): ToolExecution {
+    if (input.parent !== undefined && !isExecutionToken(input.parent)) {
+      throw new TypeError('tool execution parent must be a registry-minted opaque token')
+    }
+    if (!isJsonValue(input.arguments)) {
+      throw new TypeError('tool execution arguments must be losslessly JSON-serializable')
+    }
+    const args = structuredClone(input.arguments)
+    if (!isJsonValue(args)) {
+      throw new TypeError('tool execution arguments must be stable losslessly JSON-serializable data')
+    }
+    const execution: ToolExecution = {
+      token: createExecutionToken(),
+      callId: input.callId,
+      name: input.name,
+      arguments: deepFreeze(args),
+      ...input.agent !== undefined ? { agent: input.agent } : {},
+      ...input.parent !== undefined ? { parent: input.parent } : {},
+      ...input.signal !== undefined ? { signal: input.signal } : {},
+    }
+    Object.defineProperties(execution, {
+      token: { value: execution.token, enumerable: true, writable: false, configurable: false },
+      callId: { value: execution.callId, enumerable: true, writable: false, configurable: false },
+      name: { value: execution.name, enumerable: true, writable: false, configurable: false },
+      arguments: { value: execution.arguments, enumerable: true, writable: false, configurable: false },
+      agent: { value: input.agent, enumerable: true, writable: false, configurable: false },
+      parent: { value: input.parent, enumerable: true, writable: false, configurable: false },
+    })
+    if (input.signal !== undefined) {
+      Object.defineProperty(execution, 'signal', {
+        value: input.signal,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+      })
+    }
+    return execution
+  }
+
+  /** Run the transformable pipeline; {@link execute} owns final normalization and notification. */
+  private async executePipeline(exec: ToolExecution): Promise<ToolExecutionResult> {
+    // --- Gate: tools/pre-execute. A deny (or an ask, which degrades to deny
+    // until the permission system lands) skips dispatch entirely. The
+    // carrier keys the dispatch by exec.agent, so an `agent.ctx` listener
+    // gates only its own agent's calls (agent-less calls are subject-less).
+    const carrier = scopeTarget(this, exec.agent)
+    const decision = await this.ctx.waterfall(
+      carrier, 'tools/pre-execute', exec,
+      () => Promise.resolve<PreToolDecision>({ kind: 'allow' }),
+    )
+    const denialReason = decision.kind === 'allow'
+      ? this.guardReason(exec)
+      : decision.kind === 'deny'
+        ? decision.reason
+        : decision.reason ?? `tool "${exec.name}" requires approval (not yet supported)`
+    if (denialReason !== undefined) {
+      // deny → isError. ask has no permission UI yet, so degrade to deny
+      // (FIXME(permissions)): a forthcoming permission system turns `ask` into
+      // a real prompt; today it is the conservative "not allowed".
+      const denied: ToolExecutionResult = {
+        callId: exec.callId,
+        content: [{ type: 'text', text: `Error: ${denialReason}` }],
+        isError: true,
+      }
+      return await this.postExecute(exec, denied)
+    }
+
+    // --- Around-dispatch: tools/execute. The base `next` is the dispatch-
+    // with-normalization thunk — the tool body's own try/catch turns a throw
+    // into an isError result so a wrapper (and post-execute) can inspect it;
+    // an unknown tool routes through the same catch. A `tools/execute` listener
+    // (e.g. a timeout plugin) wraps this thunk: it may replace `exec.signal`
+    // before delegating and inspect the normalized result after. Dispatched with the
+    // same carrier as the gate, so an `agent.ctx` wrapper wraps only its own
+    // agent's calls. ---
+    const result = this.snapshotExecutionResult(exec, await this.ctx.waterfall(
+      carrier, 'tools/execute', exec,
+      async (): Promise<ToolExecutionResult> => {
+        try {
+          // Resolve through the CALLER's visible view ({@link get}): a scoped
+          // tool shadows its global name-twin for that agent, and a
+          // restricted-away global tool is exactly as absent as a nonexistent
+          // one — same UNKNOWN_TOOL result, no capability leak in the error.
+          const tool = this.get(exec.name, exec.agent)
+          if (!tool) throw new ToolNotFoundError(exec.name)
+          // Normalize the two `execute` return shapes: a bare ContentBlock[] (no
+          // meta) or a { content, meta } object (a tool attaching a private
+          // presentation payload). An array IS the content; the object carries it.
+          const returned = await tool.execute(exec.arguments, exec)
+          const content = Array.isArray(returned) ? returned : returned.content
+          const meta = Array.isArray(returned) ? undefined : returned.meta
+          return { callId: exec.callId, content, isError: false, ...meta !== undefined ? { meta } : {} }
+        } catch (error: unknown) {
+          return toolErrorResult(exec.callId, error)
+        }
+      },
+    ))
+
+    return await this.postExecute(exec, result)
+  }
+
+  /** Notify final-result observers without giving them a mutation/error channel into the outcome. */
+  private async notifyResult(exec: ToolExecution, result: ToolExecutionResult): Promise<void> {
+    // The pipeline is over: freeze the remaining mutable signal slot so every
+    // observer sees the SAME WeakMap-keyable execution without a mutation race.
+    Object.freeze(exec)
+    // postExecute clones every accepted result/decision before rebuilding the
+    // outcome; all error paths construct plain data. The final result is thus
+    // structurally cloneable before it reaches this observe-only boundary.
+    const snapshot = deepFreeze(structuredClone(result))
+    const callbacks = this.ctx.events.dispatch('parallel', [
+      scopeTarget(this, exec.agent), 'tools/result', exec, snapshot,
+    ])
+    await Promise.all(callbacks.map(async (callback) => {
+      try {
+        await callback(exec, snapshot)
+      } catch (error: unknown) {
+        this.ctx.logger.warn(`tool "${exec.name}" (${exec.callId}): tools/result observer failed: ${errorMessage(error)}`)
+      }
+    }))
   }
 
   /**
@@ -804,21 +1089,14 @@ export class ToolRegistry extends Service {
     // authoritative-call-id requirement and the "preserve the dispatched
     // isError/error" contract. The decision is the ONLY sanctioned channel for a
     // listener to change the outcome (block, or accept-with-replacement); the
-    // call id is always the authoritative `exec.callId`. `content` is copied into
-    // a fresh array so a listener's in-place `push`/`splice` on `result.content`
-    // cannot leak into the returned content either (the elements are the same
-    // references — the snapshot guards the array structure, not deep immutability).
-    const dispatched = {
-      callId: exec.callId,
-      content: [...result.content],
-      isError: result.isError,
-      ...result.error ? { error: result.error } : {},
-      ...result.meta !== undefined ? { meta: result.meta } : {},
-    }
-    const decision = await this.ctx.waterfall(
+    // call id is always the authoritative `exec.callId`. Deep cloning protects
+    // nested content, error, and meta data from in-place listener mutation.
+    const dispatched = this.snapshotExecutionResult(exec, result)
+    const decision = structuredClone(await this.ctx.waterfall(
       scopeTarget(this, exec.agent), 'tools/post-execute', exec, result,
       () => Promise.resolve<PostToolDecision>({ kind: 'accept' }),
-    )
+    ))
+    this.assertPostDecision(decision)
     const additionalContext = decision.additionalContext
     if (decision.kind === 'block') {
       return {
@@ -835,6 +1113,74 @@ export class ToolRegistry extends Service {
       ...additionalContext ? { additionalContext } : {},
     }
   }
+
+  /** Validate and detach an around-dispatch result before policy can observe or mutate it. */
+  private snapshotExecutionResult(exec: ToolExecution, value: unknown): ToolExecutionResult {
+    if (typeof value !== 'object' || value === null) {
+      throw new TypeError('tools/execute must return a ToolExecutionResult object')
+    }
+    const result = value as Partial<ToolExecutionResult>
+    if (!Array.isArray(result.content) || typeof result.isError !== 'boolean') {
+      throw new TypeError('tools/execute must return a ToolExecutionResult with content[] and boolean isError')
+    }
+    if (result.callId !== exec.callId) {
+      throw new TypeError(`tools/execute returned callId "${String(result.callId)}" for authoritative call "${exec.callId}"`)
+    }
+    const candidate = {
+      callId: exec.callId,
+      content: result.content,
+      isError: result.isError,
+      ...result.error !== undefined ? { error: result.error } : {},
+      ...result.additionalContext !== undefined ? { additionalContext: result.additionalContext } : {},
+      ...result.meta !== undefined ? { meta: result.meta } : {},
+    }
+    // Validate BEFORE cloning: structuredClone turns some forbidden exotic or
+    // class instances into plain objects, which would hide a lossy JSON
+    // boundary violation. Validate the detached clone again to contain hostile
+    // getters whose value changes between inspection and snapshotting.
+    if (!isJsonValue(candidate)) {
+      throw new TypeError('tools/execute must return a losslessly JSON-serializable ToolExecutionResult')
+    }
+    const snapshot = structuredClone(candidate)
+    if (!isJsonValue(snapshot)) {
+      throw new TypeError('tools/execute must return a stable losslessly JSON-serializable ToolExecutionResult')
+    }
+    return snapshot
+  }
+
+  /** Reject malformed JavaScript/casted post decisions at the public event boundary. */
+  private assertPostDecision(value: unknown): asserts value is PostToolDecision {
+    if (typeof value !== 'object' || value === null) {
+      throw new TypeError('tools/post-execute must return a PostToolDecision object')
+    }
+    const decision = value as Partial<PostToolDecision>
+    switch (decision.kind) {
+      case 'accept':
+        if (decision.content !== undefined && !Array.isArray(decision.content)) {
+          throw new TypeError('tools/post-execute accept content must be an array')
+        }
+        return
+      case 'block':
+        if (!Array.isArray(decision.feedback)) {
+          throw new TypeError('tools/post-execute block feedback must be an array')
+        }
+        return
+      default:
+        throw new TypeError('tools/post-execute must return an accept or block decision')
+    }
+  }
+}
+
+/** Mint a frozen, property-free correlation token whose identity is its value. */
+function createExecutionToken(): ToolExecutionToken {
+  const token = Object.freeze(Object.create(null)) as ToolExecutionToken
+  executionTokens.add(token)
+  return token
+}
+
+/** Runtime counterpart of the opaque token type, including `undefined` input. */
+function isExecutionToken(value: unknown): value is ToolExecutionToken {
+  return typeof value === 'object' && value !== null && executionTokens.has(value)
 }
 
 function toolErrorResult(callId: ToolExecution['callId'], error: unknown): ToolExecutionResult {