effect-agent 0.1.0-beta.9 → 0.1.0-beta.91

package/src/engine/internal/tool-exposure.ts

@@ -0,0 +1,224 @@
+import { Context, Effect, Schema } from "effect";
+import { Tool, type LanguageModel } from "effect/unstable/ai";
+
+import type { AnyDefinition } from "../../core/Agent.ts";
+import { ModelProtocolError } from "../../core/AgentError.ts";
+import { utf8ByteLength } from "../../core/internal/utf8.ts";
+import {
+  getToolExecutionKind,
+  isSubagentToolAllowed,
+  type SubagentGrant,
+} from "../../core/SubagentContract.ts";
+import {
+  AdditionalToolCatalog,
+  IncludesCatalogDocumentation,
+  DiscoveryTool,
+  Limits,
+  PinnedTool,
+  Selection,
+  Snapshot,
+  ToolNames,
+  ToolNamespace,
+} from "../../core/ToolExposure.ts";
+import { ContextRolloverTool } from "../ContextWindow.ts";
+import { getToolExecutionClass } from "../DurableStep.ts";
+import { RunToolVisibility, type CatalogEntry, type VisibilityRequest } from "../ToolExposure.ts";
+
+const invalid = (message: string) => ModelProtocolError.make({ message });
+
+export const decodeSelection = (value: unknown) =>
+  Schema.decodeUnknownEffect(Selection)(value).pipe(
+    Effect.mapError(() => invalid("Invalid Tool exposure selection")),
+  );
+
+export const decodeSnapshot = (value: unknown) =>
+  Schema.decodeUnknownEffect(Snapshot)(value).pipe(
+    Effect.mapError(() => invalid("Invalid recorded Tool exposure snapshot")),
+    Effect.map((snapshot) =>
+      Object.freeze(
+        Snapshot.make({
+          exposedToolNames: Object.freeze([...snapshot.exposedToolNames]),
+          ...(snapshot.selection === undefined
+            ? {}
+            : {
+                selection: Object.freeze(
+                  Selection.make({ toolNames: Object.freeze([...snapshot.selection.toolNames]) }),
+                ),
+              }),
+        }),
+      ),
+    ),
+  );
+
+export const eligibleCatalog = Effect.fn("ToolExposure.eligibleCatalog")(function* (
+  definition: AnyDefinition,
+  request: Omit<VisibilityRequest, "toolNames">,
+  grant: SubagentGrant | undefined,
+  depth: number,
+) {
+  const visibility = yield* RunToolVisibility;
+  const entries: Array<CatalogEntry> = [];
+
+  for (const tool of Object.values(definition.toolkit.tools)) {
+    if (
+      Context.get(tool.annotations, DiscoveryTool) &&
+      (getToolExecutionKind(tool.annotations) !== "ordinary" ||
+        getToolExecutionClass(tool) !== "readonly")
+    )
+      return yield* invalid("Discovery requires ordinary readonly Tools");
+    const namespace = Context.get(tool.annotations, ToolNamespace);
+
+    entries.push({
+      kind: "native",
+      tool,
+      nativeToolName: tool.name,
+      ...(namespace === undefined ? {} : { namespace }),
+    });
+    for (const extra of Context.get(tool.annotations, AdditionalToolCatalog)) {
+      entries.push({ kind: "code-mode", ...extra, nativeToolName: tool.name });
+    }
+  }
+  const names = [...new Set(entries.map((entry) => entry.tool.name))];
+
+  const visible =
+    visibility === undefined ? names : yield* visibility.visible({ ...request, toolNames: names });
+
+  const checked =
+    visibility === undefined
+      ? visible
+      : yield* Schema.decodeEffect(ToolNames)(visible).pipe(
+          Effect.mapError(() => invalid("Host Tool visibility returned invalid names")),
+        );
+
+  if (checked.some((name) => !names.includes(name)))
+    return yield* invalid("Host Tool visibility returned an unregistered name");
+  const allowed = new Set(checked);
+
+  const permits = (tool: Tool.Any) =>
+    allowed.has(tool.name) && isSubagentToolAllowed(grant, depth, tool.name, tool.annotations);
+
+  for (const outer of Object.values(definition.toolkit.tools)) {
+    if (
+      permits(outer) &&
+      Context.get(outer.annotations, IncludesCatalogDocumentation) &&
+      Context.get(outer.annotations, AdditionalToolCatalog).some((entry) => !permits(entry.tool))
+    ) {
+      return yield* invalid(
+        "A Tool description includes hidden catalogue declarations; configure includeDeclarations: false",
+      );
+    }
+  }
+
+  return Object.freeze(
+    entries
+      .filter((entry) => {
+        const outer = definition.toolkit.tools[entry.nativeToolName];
+
+        return outer !== undefined && permits(outer) && permits(entry.tool);
+      })
+      .map((entry) => Object.freeze(entry)),
+  );
+});
+
+export const validateSelection = Effect.fn("ToolExposure.validateSelection")(function* (
+  value: unknown,
+  definition: AnyDefinition,
+  entries: ReadonlyArray<CatalogEntry>,
+  requireEligible = true,
+) {
+  const selection = yield* decodeSelection(value);
+
+  const eligible = new Set(
+    entries.filter((entry) => entry.kind === "native").map((entry) => entry.nativeToolName),
+  );
+
+  if (
+    selection.toolNames.some(
+      (name) =>
+        !Object.hasOwn(definition.toolkit.tools, name) || (requireEligible && !eligible.has(name)),
+    )
+  ) {
+    return yield* invalid("Tool selection names a Tool outside the eligible registered toolkit");
+  }
+
+  return Selection.make({ toolNames: Object.freeze([...selection.toolNames]) });
+});
+
+export const exposureSnapshot = Effect.fn("ToolExposure.exposureSnapshot")(function* (
+  definition: AnyDefinition,
+  selection: Selection | undefined,
+  entries: ReadonlyArray<CatalogEntry>,
+  transformer?: LanguageModel.CodecTransformer,
+  only?: ReadonlyArray<string>,
+) {
+  const native = entries.filter((entry) => entry.kind === "native").map((entry) => entry.tool);
+  const progressive = definition.toolExposure !== undefined || selection !== undefined;
+
+  const mandatory = Object.values(definition.toolkit.tools).filter(
+    (tool) =>
+      Context.get(tool.annotations, DiscoveryTool) ||
+      Context.get(tool.annotations, ContextRolloverTool) ||
+      (definition.completion?.required === true && definition.completion.tool === tool.name),
+  );
+
+  if (
+    progressive &&
+    mandatory.some((tool) => !native.some((candidate) => candidate.name === tool.name))
+  ) {
+    return yield* invalid("A mandatory Tool is excluded by host visibility or the inherited grant");
+  }
+
+  // Explicit pins affect selection, never eligibility. Hosts may disable a common action
+  // without disabling the Run; protocol-required Tools still fail closed above.
+  const pinned = native.filter(
+    (tool) => Context.get(tool.annotations, PinnedTool) || mandatory.includes(tool),
+  );
+
+  if (selection !== undefined) yield* validateSelection(selection, definition, entries, false);
+  const selected = selection === undefined ? undefined : new Set(selection.toolNames);
+
+  const names = native
+    .filter((tool) => selected === undefined || selected.has(tool.name) || pinned.includes(tool))
+    .map((tool) => tool.name)
+    .filter((name) => only === undefined || only.includes(name));
+
+  if (progressive) {
+    const limits = yield* Schema.decodeEffect(Limits)({
+      maxTools: definition.toolExposure?.maxTools ?? 64,
+      maxSchemaBytes: definition.toolExposure?.maxSchemaBytes ?? 262_144,
+    }).pipe(Effect.mapError(() => invalid("Invalid Tool exposure bounds")));
+
+    if (names.length > limits.maxTools)
+      return yield* invalid("Tool exposure exceeds the configured Tool count bound");
+
+    const bytes = yield* Effect.try({
+      try: () =>
+        utf8ByteLength(
+          JSON.stringify(
+            names.map((name) => {
+              const tool = definition.toolkit.tools[name];
+
+              if (tool === undefined) throw new Error("Selected Tool is unavailable");
+
+              return Tool.isProviderDefined(tool)
+                ? { type: tool.providerName, args: tool.args }
+                : {
+                    name,
+                    description: Tool.getDescription(tool),
+                    parameters: Tool.getJsonSchema(tool, { transformer }),
+                  };
+            }),
+          ),
+        ),
+      catch: () => invalid("A selected Tool schema cannot be rendered"),
+    });
+
+    if (bytes > limits.maxSchemaBytes)
+      return yield* invalid("Tool exposure exceeds the configured schema byte bound");
+  }
+
+  return yield* decodeSnapshot({
+    exposedToolNames: names,
+    ...(selection === undefined ? {} : { selection }),
+  });
+});

package/src/engine/internal/tool-telemetry.ts

@@ -0,0 +1,484 @@
+import {
+  Cause,
+  Context,
+  Effect,
+  ErrorReporter,
+  Exit,
+  type Fiber,
+  Layer,
+  Option,
+  Stream,
+  Tracer,
+} from "effect";
+import { AiError, type Tool } from "effect/unstable/ai";
+
+import type { ToolFailureHandling } from "../../core/RunEvent.ts";
+import { isolateToolDerivative } from "./tool-derivative.ts";
+
+/**
+ * @internal Payload-free control signal used only to close the canonical Tool span with a failed
+ * Exit. It is removed immediately outside that span and never enters the public error channel.
+ */
+export class ToolSpanFailure extends AiError.AiError.extend<ToolSpanFailure>(
+  "@effect-agent/engine/ToolSpanFailure",
+)({}) {
+  override readonly name = "ToolCallFailed";
+
+  /** Schema-safe factory retaining the generated constructor required by Effect Schema. */
+  static marker(): ToolSpanFailure {
+    return ToolSpanFailure.make({
+      module: "effect-agent",
+      method: "execute_tool",
+      reason: AiError.UnknownError.make({
+        description: "Tool execution reached a failed terminal state",
+      }),
+    });
+  }
+}
+
+const TOOL_SPAN_FAILURE_MARKER_ATTRIBUTE = "@effect-agent/engine/ToolSpanFailureMarker";
+
+const terminalOutcomeTokens = new WeakMap<
+  object,
+  {
+    readonly outcome: "success" | "failure";
+    readonly failureMarker: ToolSpanFailure | undefined;
+    readonly failureHandling: ToolFailureHandling | undefined;
+    readonly failureMode: Tool.FailureMode | undefined;
+  }
+>();
+
+/** @internal Annotate one completed attempt and hand its existing marker to the isolated span. */
+export const annotateToolSpanTerminalOutcome = (
+  outcome: "success" | "failure",
+  failureMarker?: ToolSpanFailure,
+  failureHandling?: ToolFailureHandling,
+  failureMode?: Tool.FailureMode,
+): Effect.Effect<void> => {
+  const token = {};
+
+  terminalOutcomeTokens.set(token, { outcome, failureMarker, failureHandling, failureMode });
+
+  return Effect.annotateCurrentSpan({
+    "effect_agent.tool.outcome": outcome,
+    [TOOL_SPAN_FAILURE_MARKER_ATTRIBUTE]: token,
+  });
+};
+
+export const stripToolSpanFailures = <E>(
+  cause: Cause.Cause<E | ToolSpanFailure>,
+  marker: ToolSpanFailure,
+): { readonly found: boolean; readonly residual: Cause.Cause<E | ToolSpanFailure> } => {
+  const found = cause.reasons.some(
+    (reason) => Cause.isFailReason(reason) && reason.error === marker,
+  );
+
+  if (!found) {
+    // Effect v4 Cause is a flat collection of Reasons. Object-identity absence proves only that
+    // this invocation's marker is absent: another ToolSpanFailure may still be a genuine handler
+    // failure, so retain both the exact Cause object and its complete error union.
+    return { found: false, residual: cause };
+  }
+
+  const reasons = cause.reasons.filter((reason) => {
+    if (Cause.isFailReason(reason) && reason.error === marker) {
+      return false;
+    }
+
+    return true;
+  });
+
+  return { found: true, residual: Cause.fromReasons(reasons) };
+};
+
+/** @internal Remove only the private marker and restore the saved Cause plus every residual. */
+export const restoreToolSpanFailureCause = <E, Original>(
+  cause: Cause.Cause<E | ToolSpanFailure>,
+  marker: ToolSpanFailure,
+  original: Cause.Cause<Original> | undefined,
+): {
+  readonly found: boolean;
+  readonly restored: Cause.Cause<E | Original | ToolSpanFailure>;
+} => {
+  const { found, residual } = stripToolSpanFailures(cause, marker);
+
+  return {
+    found,
+    restored: original === undefined ? residual : Cause.combine(original, residual),
+  };
+};
+
+const MAX_REPORTED_SPAN_LIFECYCLE_DEFECTS = 16;
+
+/** Content-free marker used only to close a delegate that cannot be wrapped safely. */
+class ToolSpanLifecycleFailure extends Error {
+  override readonly name = "ToolSpanLifecycleFailure";
+
+  constructor() {
+    super("Tool span lifecycle failed");
+  }
+}
+
+/**
+ * @internal Guard one host span so synchronous exporter defects cannot alter Tool execution.
+ * The wrapper retains the span contract for Effect while forwarding every measurement to the host.
+ */
+class IsolatedToolSpan implements Tracer.Span {
+  readonly _tag = "Span";
+  readonly name: string;
+  readonly spanId: string;
+  readonly traceId: string;
+  readonly parent: Tracer.Span["parent"];
+  readonly annotations: Tracer.Span["annotations"];
+  readonly attributes = new Map<string, unknown>();
+  readonly links: Array<Tracer.SpanLink>;
+  readonly sampled: boolean;
+  readonly kind: Tracer.SpanKind;
+  status: Tracer.SpanStatus;
+
+  readonly #delegate: Tracer.Span;
+  readonly #recordDefect: (defect: unknown) => void;
+  #terminalOutcome: "success" | "failure" | undefined;
+  #terminalFailure: ToolSpanFailure | undefined;
+  #terminalFailureHandling: ToolFailureHandling | undefined;
+  #terminalFailureMode: Tool.FailureMode | undefined;
+
+  constructor(
+    delegate: Tracer.Span,
+    options: Parameters<Tracer.Tracer["span"]>[0],
+    recordDefect: (defect: unknown) => void,
+  ) {
+    this.#delegate = delegate;
+    this.#recordDefect = recordDefect;
+    this.name = options.name;
+    this.spanId = delegate.spanId;
+    this.traceId = delegate.traceId;
+    this.parent = options.parent;
+    this.annotations = options.annotations;
+    this.links = [...options.links];
+    // The host tracer owns the final sampling decision. Reading it here keeps that access inside
+    // the caller's existing creation try/fallback together with span allocation and identifiers.
+    this.sampled = delegate.sampled;
+    this.kind = options.kind;
+    this.status = { _tag: "Started", startTime: options.startTime };
+  }
+
+  end(endTime: bigint, exit: Exit.Exit<unknown, unknown>): void {
+    if (this.status._tag === "Ended") return;
+
+    // Early downstream closure can own terminal telemetry from a no-fail stream finalizer, where
+    // the private typed marker is intentionally captured because there is no consumer left to
+    // observe it. Once present, the bounded outcome annotation is authoritative for this completed
+    // attempt even if downstream cancellation or telemetry interruption determines the channel Exit.
+    const exportedExit =
+      this.#terminalOutcome === "failure"
+        ? Exit.fail(this.#terminalFailure ?? new ToolSpanLifecycleFailure())
+        : this.#terminalOutcome === "success"
+          ? Exit.succeed(undefined)
+          : exit;
+
+    this.status = {
+      _tag: "Ended",
+      startTime: this.status.startTime,
+      endTime,
+      exit: exportedExit,
+    };
+    if (this.#terminalOutcome !== undefined) {
+      // The public attribute map is intentionally mutable for ordinary instrumentation. Restore
+      // this framework-owned value from the authenticated private token at the export boundary so
+      // handler or telemetry code cannot forge the canonical terminal classification.
+      this.attributes.set("effect_agent.tool.outcome", this.#terminalOutcome);
+      try {
+        this.#delegate.attribute("effect_agent.tool.outcome", this.#terminalOutcome);
+      } catch (defect) {
+        this.#recordDefect(defect);
+      }
+    }
+    for (const [key, value] of [
+      ["effect_agent.tool.failure_mode", this.#terminalFailureMode],
+      ["effect_agent.tool.failure_handling", this.#terminalFailureHandling],
+    ] as const) {
+      if (value !== undefined) {
+        this.attributes.set(key, value);
+        try {
+          this.#delegate.attribute(key, value);
+        } catch (defect) {
+          this.#recordDefect(defect);
+        }
+      } else if (key === "effect_agent.tool.failure_handling") {
+        this.attributes.delete(key);
+      }
+    }
+    try {
+      this.#delegate.end(endTime, exportedExit);
+    } catch (defect) {
+      this.#recordDefect(defect);
+    }
+  }
+
+  attribute(key: string, value: unknown): void {
+    if (key === TOOL_SPAN_FAILURE_MARKER_ATTRIBUTE) {
+      if (typeof value === "object" && value !== null) {
+        const terminal = terminalOutcomeTokens.get(value);
+
+        if (terminal !== undefined) {
+          this.#terminalOutcome = terminal.outcome;
+          this.#terminalFailure = terminal.failureMarker;
+          this.#terminalFailureHandling = terminal.failureHandling;
+          this.#terminalFailureMode = terminal.failureMode;
+        }
+      }
+
+      return;
+    }
+    // Only the authenticated terminal token may classify a failure's route.
+    if (key === "effect_agent.tool.failure_handling") return;
+    this.attributes.set(key, value);
+    try {
+      this.#delegate.attribute(key, value);
+    } catch (defect) {
+      this.#recordDefect(defect);
+    }
+  }
+
+  event(name: string, startTime: bigint, attributes?: Record<string, unknown>): void {
+    try {
+      this.#delegate.event(name, startTime, attributes);
+    } catch (defect) {
+      this.#recordDefect(defect);
+    }
+  }
+
+  addLinks(links: ReadonlyArray<Tracer.SpanLink>): void {
+    this.links.push(...links);
+    try {
+      this.#delegate.addLinks(links);
+    } catch (defect) {
+      this.#recordDefect(defect);
+    }
+  }
+}
+
+interface IsolatedToolTracer {
+  readonly tracer: Tracer.Tracer;
+  readonly reportLifecycleDefects: Effect.Effect<void>;
+}
+
+/**
+ * @internal Isolate the complete canonical span lifecycle. A creation defect receives a local,
+ * non-exported span so the handler still runs; delegate method/finalization defects are retained
+ * as bounded reporter diagnostics and never enter the handler stream Cause.
+ */
+export const makeIsolatedToolTracer = (delegate: Tracer.Tracer): IsolatedToolTracer => {
+  const defects: Array<unknown> = [];
+
+  const recordDefect = (defect: unknown): void => {
+    if (defects.length < MAX_REPORTED_SPAN_LIFECYCLE_DEFECTS) defects.push(defect);
+  };
+
+  let delegateContext: Tracer.Tracer["context"];
+
+  try {
+    delegateContext = delegate.context?.bind(delegate);
+  } catch (defect) {
+    recordDefect(defect);
+    delegateContext = undefined;
+  }
+
+  const context: Tracer.Tracer["context"] =
+    delegateContext === undefined
+      ? undefined
+      : <X>(primitive: Tracer.EffectPrimitive<X>, fiber: Fiber.Fiber<unknown, unknown>): X => {
+          type Evaluation =
+            | { readonly _tag: "Pending" }
+            | { readonly _tag: "Succeeded"; readonly value: X }
+            | { readonly _tag: "Failed"; readonly error: unknown };
+          let evaluation: Evaluation = { _tag: "Pending" };
+          const currentEvaluation = (): Evaluation => evaluation;
+
+          const evaluate = (currentFiber: Fiber.Fiber<unknown, unknown>): X => {
+            switch (evaluation._tag) {
+              case "Succeeded":
+                return evaluation.value;
+              case "Failed":
+                throw evaluation.error;
+              case "Pending": {
+                try {
+                  const value = primitive["~effect/Effect/evaluate"](currentFiber);
+
+                  evaluation = { _tag: "Succeeded", value };
+
+                  return value;
+                } catch (error) {
+                  evaluation = { _tag: "Failed", error };
+                  throw error;
+                }
+              }
+            }
+          };
+
+          const guardedPrimitive: Tracer.EffectPrimitive<X> = {
+            ["~effect/Effect/evaluate"]: evaluate,
+          };
+
+          try {
+            delegateContext(guardedPrimitive, fiber);
+          } catch (defect) {
+            const observed = currentEvaluation();
+
+            switch (observed._tag) {
+              case "Failed":
+                throw observed.error;
+              case "Succeeded":
+                recordDefect(defect);
+
+                return observed.value;
+              case "Pending":
+                recordDefect(defect);
+
+                return evaluate(fiber);
+            }
+          }
+          const observed = currentEvaluation();
+
+          switch (observed._tag) {
+            case "Failed":
+              throw observed.error;
+            case "Succeeded":
+              return observed.value;
+            case "Pending":
+              return evaluate(fiber);
+          }
+        };
+
+  const tracer = Tracer.make({
+    context,
+    span(options) {
+      let delegateSpan: Tracer.Span;
+
+      try {
+        delegateSpan = delegate.span(options);
+      } catch (defect) {
+        recordDefect(defect);
+
+        // This native span is deliberately not handed to the host exporter. It only preserves
+        // Effect's current-span contract so Tool behavior continues without observable tracing.
+        return new Tracer.NativeSpan(options);
+      }
+      try {
+        return new IsolatedToolSpan(delegateSpan, options, recordDefect);
+      } catch (defect) {
+        recordDefect(defect);
+        try {
+          // Allocation succeeded, so best-effort close the host span without attaching the raw
+          // wrapper defect. The start time gives this abandoned measurement a bounded duration.
+          delegateSpan.end(options.startTime, Exit.fail(new ToolSpanLifecycleFailure()));
+        } catch (closeDefect) {
+          recordDefect(closeDefect);
+        }
+
+        return new Tracer.NativeSpan(options);
+      }
+    },
+  });
+
+  const reportLifecycleDefects = Effect.suspend(() => {
+    const pending = defects.splice(0);
+
+    return Effect.forEach(
+      pending,
+      (defect) => isolateToolDerivative(ErrorReporter.report(Cause.die(defect))),
+      { discard: true },
+    );
+  });
+
+  return { tracer, reportLifecycleDefects };
+};
+
+export interface ToolSpanTelemetryService {
+  /** Measure one Tool handler attempt while isolating every host span-lifecycle defect. */
+  readonly isolateSpanLifecycle: <A, E, R>(
+    stream: Stream.Stream<A, E, R>,
+  ) => Stream.Stream<A, E, R>;
+  /** Effect counterpart used by programmatic Tool handlers nested inside an outer Tool stream. */
+  readonly isolateEffectSpanLifecycle: <A, E, R>(
+    effect: Effect.Effect<A, E, R>,
+  ) => Effect.Effect<A, E, R>;
+  /** Keep Effect AI implementation annotations local while preserving host-owned handler spans. */
+  readonly isolateToolkitHandle: <A, E, R>(
+    effect: Effect.Effect<A, E, R>,
+  ) => Effect.Effect<A, E, R>;
+}
+
+/**
+ * @internal Engine-owned span-lifecycle policy. The AgentRuntime composition boundary builds this
+ * capability from the host's ambient Tracer; Tool execution consumes it without selecting,
+ * decorating, or locally providing a Tracer implementation.
+ */
+export class ToolSpanTelemetry extends Context.Service<
+  ToolSpanTelemetry,
+  ToolSpanTelemetryService
+>()("@effect-agent/engine/ToolSpanTelemetry") {
+  static readonly layer: Layer.Layer<ToolSpanTelemetry> = Layer.effect(
+    ToolSpanTelemetry,
+    Effect.map(Tracer.Tracer, (delegate) =>
+      ToolSpanTelemetry.of({
+        isolateEffectSpanLifecycle: (effect) =>
+          Effect.suspend(() => {
+            const isolated = makeIsolatedToolTracer(delegate);
+
+            return effect.pipe(
+              Effect.provideService(Tracer.Tracer, isolated.tracer),
+              // `Effect.ensuring` runs after the measured span's finalizer, matching the Stream
+              // boundary below while keeping the broker's value and error channels unchanged.
+              Effect.ensuring(isolated.reportLifecycleDefects),
+            );
+          }),
+        isolateToolkitHandle: (effect) =>
+          Effect.currentSpan.pipe(
+            Effect.option,
+            Effect.flatMap((parentOption) => {
+              if (Option.isNone(parentOption)) return effect;
+              const parent = parentOption.value;
+
+              // Effect AI annotates its current span with decoded Tool parameters before forking
+              // the handler. Keep those annotations on a local span that is never handed to the
+              // host tracer. DisablePropagation makes explicit handler spans filter past this
+              // implementation parent and attach to the canonical execute_tool span instead.
+              const local = new Tracer.NativeSpan({
+                name: "AgentRuntime.toolkit.handle",
+                parent: Option.some(parent),
+                annotations: Context.add(Context.empty(), Tracer.DisablePropagation, true),
+                links: [],
+                startTime: 0n,
+                kind: "internal",
+                sampled: parent.sampled,
+              });
+
+              return effect.pipe(
+                Effect.withParentSpan(local),
+                Effect.onExit((exit) =>
+                  Effect.sync(() => {
+                    local.end(0n, exit);
+                  }),
+                ),
+              );
+            }),
+          ),
+        isolateSpanLifecycle: (stream) =>
+          Stream.unwrap(
+            Effect.sync(() => {
+              const isolated = makeIsolatedToolTracer(delegate);
+
+              return stream.pipe(
+                Stream.provideService(Tracer.Tracer, isolated.tracer),
+                // `Stream.ensuring` runs after the canonical span's own finalizer, so creation,
+                // annotation, and close defects are reported outside this execution's measurement.
+                Stream.ensuring(isolated.reportLifecycleDefects),
+              );
+            }),
+          ),
+      }),
+    ),
+  );
+}