kitlangton · Nov 9, 2026 · Nov 9, 2026 · Nov 9, 2026
diff --git a/packages/core/src/session/runner/step.ts b/packages/core/src/session/runner/step.ts
@@ -76,9 +76,13 @@ export const make = Effect.gen(function* () {
     const pendingStartSnapshot = yield* snapshots.capture().pipe(Effect.forkScoped)
     const started = yield* Clock.currentTimeMillis
     let firstOutputAt: number | undefined
-    yield* Effect.annotateCurrentSpan({
+    const modelAttributes = {
       "gen_ai.provider.name": input.model.ref.providerID,
       "gen_ai.request.model": input.model.ref.id,
+    }
+    yield* Effect.annotateCurrentSpan({
+      ...modelAttributes,
+      "gen_ai.agent.name": input.agent,
       ...(input.retryAttempt === undefined ? {} : { "opencode.retry.attempt": input.retryAttempt }),
     })
     const publisher = createLLMEventPublisher(bus, {
@@ -110,7 +114,9 @@ export const make = Effect.gen(function* () {
     // Provider and tool fibers retain per-source order without a shared writer queue.
     // A local execution starts only after its Tool.Called publication completes.
     // Read to the end, not just the finish event, so the next request can reuse this response.
+    // The span covers only the provider stream, so model time separates from tools, which run in this consumer.
     const providerStream = llm.stream(input.prepared.request, input.prepared.options).pipe(
+      Stream.withSpan("LLM.stream", { attributes: modelAttributes }),
       Stream.runForEach((event) =>
         Effect.gen(function* () {
           if (publisher.record().providerFailed) return

diff --git a/packages/core/src/session/subagent-job.ts b/packages/core/src/session/subagent-job.ts
@@ -36,6 +36,8 @@ const make: Effect.Effect<Interface, never, Session.Service | Job.Service | Scop
       if (info) yield* SubagentCompletion.deliver(sessions, jobs, { ...info, recovery })
     }).pipe(
       Effect.ensuring(Effect.sync(() => notifications.delete(key))),
+      // The global context drops the caller's span annotations; delivery is the parent session's work.
+      Effect.annotateSpans("session.id", recovery.parentSessionID),
       Effect.forkIn(scope, { startImmediately: true }),
       Effect.setContext(context),
     )

diff --git a/packages/core/src/shell.ts b/packages/core/src/shell.ts
@@ -32,6 +32,7 @@ export class NotFoundError extends Schema.TaggedError<NotFoundError>()("Shell.No
 const EXITED_LIMIT = 25
 export const RETENTION = Duration.days(7)
 export const DIRECTORY = "shell"
+const SPAN_COMMAND_LIMIT = 200
 
 type Info = Shell.Info
 type CreateInput = Shell.CreateInput & {
@@ -182,7 +183,7 @@ const layer = () =>
       })
 
       const remove = Effect.fn("Shell.remove")(function* (id: Shell.ID) {
-        yield* require(id)
+        yield* annotate((yield* require(id)).info)
         yield* removeCommand(id)
       })
 
@@ -193,15 +194,22 @@ const layer = () =>
       })
 
       const get = Effect.fn("Shell.get")(function* (id: Shell.ID) {
-        return (yield* require(id)).info
+        const { info } = yield* require(id)
+        yield* annotate(info)
+        return info
       })
 
       const wait = Effect.fn("Shell.wait")(function* (id: Shell.ID) {
-        return yield* Deferred.await((yield* require(id)).done)
+        const command = yield* require(id)
+        yield* annotate(command.info)
+        const info = yield* Deferred.await(command.done)
+        yield* annotate(info)
+        return info
       })
 
       const timeout = Effect.fn("Shell.timeout")(function* (id: Shell.ID, duration: number) {
         const command = yield* require(id)
+        yield* annotate(command.info)
         if (command.info.status !== "running" || !command.timeout) return command.info
         yield* command.timeout(duration)
         return command.info
@@ -242,11 +250,13 @@ const layer = () =>
       })
 
       const result = Effect.fn("Shell.result")(function* (started: Shell.Info) {
+        yield* annotate(started)
         const info = yield* wait(started.id).pipe(
           Effect.catchTag("Shell.NotFoundError", () =>
             Effect.succeed({ ...started, status: "killed" as const, time: { ...started.time, completed: Date.now() } }),
           ),
         )
+        yield* annotate(info)
         const capture = yield* Effect.gen(function* () {
           const limits = Config.latest(yield* config.entries(), "tool_output")
           const maxLines = limits?.max_lines ?? ToolOutput.MAX_LINES
@@ -322,6 +332,7 @@ const layer = () =>
           metadata: input.metadata ?? {},
           time: { started: Date.now() },
         }
+        yield* annotate(info)
 
         // Spawn through the Environment and stream combined output to the file. The handle is scope-bound, so
         // the managing fiber keeps its scope open until the command terminates (it awaits `done` at the
@@ -486,6 +497,26 @@ const layer = () =>
     }),
   )
 
+// Spans carry only the command text, truncated; never env, stdin or output. Shells outlive the turn that started
+// them, so the session comes from the shell's own metadata rather than the caller's span annotations.
+function annotate(info: Info) {
+  const sessionID = info.metadata.sessionID
+  return Effect.annotateCurrentSpan({
+    "opencode.shell.id": info.id,
+    "opencode.shell.command": spanCommand(info.command),
+    ...(typeof sessionID === "string" ? { "session.id": sessionID } : {}),
+    ...(info.metadata.background === true ? { "opencode.shell.background": true } : {}),
+    ...(info.status === "running" ? {} : { "opencode.shell.status": info.status }),
+    ...(info.exit === undefined ? {} : { "process.exit.code": info.exit }),
+  })
+}
+
+// Strict OTLP JSON parsers reject a lone surrogate, which a cut through an emoji would leave.
+function spanCommand(command: string) {
+  if (command.length <= SPAN_COMMAND_LIMIT) return command.toWellFormed()
+  return `${command.slice(0, SPAN_COMMAND_LIMIT).toWellFormed()}…`
+}
+
 // Moves past UTF-8 continuation bytes (at most 3) so a byte cut never splits a character.
 function charBoundary(bytes: Buffer, offset: number) {
   const limit = Math.min(bytes.length, offset + 3)

diff --git a/packages/core/src/tool.ts b/packages/core/src/tool.ts
@@ -140,6 +140,7 @@ const layer = Layer.effect(
         "gen_ai.tool.name": name,
         "gen_ai.tool.call.id": context.id,
         "session.id": context.sessionID,
+        "gen_ai.agent.name": context.agent,
       })
       const execution = yield* execute(tool, input, context).pipe(
         Effect.map((value) => ({ value })),

diff --git a/packages/core/src/tool/plugin/shell.ts b/packages/core/src/tool/plugin/shell.ts
@@ -252,6 +252,11 @@ export const Plugin = {
 
               return yield* Deferred.await(settled)
             }).pipe(
+              // Shell spans, including the job that waits for a backgrounded command, name the call that started them.
+              Effect.annotateSpans({
+                "gen_ai.tool.call.id": context.id,
+                ...(input.background === true ? { "opencode.shell.background": true } : {}),
+              }),
               Effect.map((output) => toolResult(output, finalTimeout)),
               Effect.mapError(
                 (error) => new ToolFailure({ message: `Unable to execute command: ${input.command}`, error }),

diff --git a/packages/core/test/session-runner-recorded.test.ts b/packages/core/test/session-runner-recorded.test.ts
@@ -263,6 +263,7 @@ describe("SessionRunnerLLM recorded", () => {
       )
       const attempt = turn.find((span) => span.name === "SessionStep.attempt")
       expect(Object.fromEntries(attempt?.attributes ?? [])).toMatchObject({
+        "gen_ai.agent.name": "build",
         "gen_ai.provider.name": "openai",
         "gen_ai.request.model": "gpt-4o-mini",
         "gen_ai.response.finish_reasons": ["stop"],
@@ -271,6 +272,14 @@ describe("SessionRunnerLLM recorded", () => {
         "opencode.usage.cost_usd": 0,
       })
       expect(attempt?.attributes.get("opencode.llm.first_output_ms")).toBeNumber()
+      // The provider stream has its own span under the attempt, so model time splits from tool time.
+      const stream = turn.find((span) => span.name === "LLM.stream")
+      expect(Option.getOrUndefined(stream!.parent)?.spanId).toBe(attempt!.spanId)
+      expect(Object.fromEntries(stream!.attributes)).toMatchObject({
+        "gen_ai.provider.name": "openai",
+        "gen_ai.request.model": "gpt-4o-mini",
+      })
+      expect(stream!.status._tag).toBe("Ended")
     }).pipe(Effect.withSpan("fixture.request")),
   )
 })
diff --git a/packages/core/test/session-shell.test.ts b/packages/core/test/session-shell.test.ts
@@ -1,7 +1,7 @@
 import { describe, expect, setDefaultTimeout } from "bun:test"
 import fs from "fs/promises"
 import path from "path"
-import { Cause, Context, Deferred, Effect, Exit, Fiber, Layer, Option, Schedule, Stream } from "effect"
+import { Cause, Context, Deferred, Effect, Exit, Fiber, Layer, Option, Schedule, Stream, Tracer } from "effect"
 import { Bus } from "@opencode/core/bus"
 import { AppNodeBuilder } from "@opencode/core/effect/app-node-builder"
 import { Location } from "@opencode/core/location"
@@ -75,6 +75,18 @@ const setup = Effect.gen(function* () {
   return { tmp, session, created, shell, control, execution }
 })
 
+const recordSpans = () => {
+  const spans: Tracer.NativeSpan[] = []
+  const tracer = Tracer.make({
+    span(options) {
+      const span = new Tracer.NativeSpan(options)
+      spans.push(span)
+      return span
+    },
+  })
+  return { spans, tracer }
+}
+
 const log = (session: Session.Interface, sessionID: Session.ID, follow = false) =>
   session.log({ sessionID, follow }).pipe(Stream.filter((event) => !Bus.isSynced(event)))
 
@@ -327,6 +339,37 @@ describe("Session.shell", () => {
     )
   }
 
+  it.live("names the session, a truncated command and the exit on shell spans outside any turn", () =>
+    Effect.gen(function* () {
+      const { spans, tracer } = recordSpans()
+      const fixture = yield* setup
+      // The emoji's two UTF-16 units sit at indexes 199 and 200, across the 200-unit cut.
+      const command = `exit 3 # ${"x".repeat(190)}😀${"x".repeat(100)}`
+      const truncated = `exit 3 # ${"x".repeat(190)}\uFFFD…`
+      yield* fixture.session.shell({ sessionID: fixture.created.id, command }).pipe(Effect.withTracer(tracer))
+
+      const create = spans.find((span) => span.name === "Shell.create")
+      const result = spans.find((span) => span.name === "Shell.result")
+      const shellID = create?.attributes.get("opencode.shell.id")
+      expect(shellID).toBeString()
+      expect(truncated.isWellFormed()).toBe(true)
+      expect(Object.fromEntries(create?.attributes ?? [])).toEqual({
+        "opencode.shell.id": shellID,
+        "opencode.shell.command": truncated,
+        "session.id": fixture.created.id,
+        "opencode.shell.background": true,
+      })
+      expect(Object.fromEntries(result?.attributes ?? [])).toEqual({
+        "opencode.shell.id": shellID,
+        "opencode.shell.command": truncated,
+        "session.id": fixture.created.id,
+        "opencode.shell.background": true,
+        "opencode.shell.status": "exited",
+        "process.exit.code": 3,
+      })
+    }),
+  )
+
   it.live("admits a spawn failure without waking the model before failing the caller", () =>
     Effect.gen(function* () {
       const fixture = yield* setup

diff --git a/packages/core/test/tool-shell.test.ts b/packages/core/test/tool-shell.test.ts
@@ -3,7 +3,7 @@ import { realpathSync, watch } from "node:fs"
 import os from "os"
 import path from "path"
 import { describe, expect } from "bun:test"
-import { Cause, Deferred, Duration, Effect, Exit, Fiber, Layer, Queue, Scope, Stream } from "effect"
+import { Cause, Deferred, Duration, Effect, Exit, Fiber, Layer, Queue, Scope, Stream, Tracer } from "effect"
 import { Money } from "@opencode/schema/money"
 import { AppNodeBuilder } from "@opencode/core/effect/app-node-builder"
 import { LayerNode } from "@opencode/util/effect/layer-node"
@@ -1503,6 +1503,46 @@ describe("ShellTool", () => {
     { timeout: 15_000 },
   )
 
+  it.live("names the tool call and background on the spans of the shell it starts", () =>
+    withTempDir((tmp) => {
+      reset()
+      const spans: Tracer.NativeSpan[] = []
+      const tracer = Tracer.make({
+        span(options) {
+          const span = new Tracer.NativeSpan(options)
+          spans.push(span)
+          return span
+        },
+      })
+      return withSession(tmp.path, (registry) =>
+        Effect.gen(function* () {
+          yield* executeTool(registry, call({ command: bodyExitCommand }, "call-traced"))
+          yield* executeTool(registry, call({ command: helloCommand, background: true }, "call-traced-background"))
+        }),
+      ).pipe(
+        Effect.withTracer(tracer),
+        Effect.andThen(
+          Effect.sync(() => {
+            const attributes = (name: string, callID: string) =>
+              spans
+                .filter((span) => span.name === name && span.attributes.get("gen_ai.tool.call.id") === callID)
+                .map((span) => Object.fromEntries(span.attributes))
+            expect(attributes("Shell.create", "call-traced")).toEqual([
+              expect.objectContaining({ "session.id": sessionID, "opencode.shell.command": bodyExitCommand }),
+            ])
+            expect(attributes("Shell.create", "call-traced")[0]).not.toHaveProperty("opencode.shell.background")
+            expect(attributes("Shell.result", "call-traced")).toEqual([
+              expect.objectContaining({ "session.id": sessionID, "process.exit.code": 7 }),
+            ])
+            expect(attributes("Shell.create", "call-traced-background")).toEqual([
+              expect.objectContaining({ "session.id": sessionID, "opencode.shell.background": true }),
+            ])
+          }),
+        ),
+      )
+    }),
+  )
+
   it.live("returns the shell id for a background command", () =>
     withTempDir((tmp) => {
       reset()