fix(session): preserve tool metadata across pending→running transition

The AI SDK fires tool execute() as a detached promise before the
processor handles the tool-call stream event. When execute() calls
ctx.metadata({sessionId}), the processor's tool-call handler
overwrites the DB with a fresh running state that has no metadata,
making subagent sessions unclickable in the TUI.

- Add synchronous toolMetadata side-channel on processor context
- setToolMetadata() on Handle writes to the map immediately
- tool-call handler reads and merges metadata from the side-channel
- prompt.ts metadata callback calls setToolMetadata() before the
  async DB update, ensuring metadata is captured regardless of
  event ordering
- Add E2E regression test using fake Anthropic HTTP server through
  the real AI SDK streamText pipeline with gate-based assertion of
  running-state metadata

Closes #20184

Author: rmk40

packages/opencode/src/session/processor.ts

@@ -30,6 +30,7 @@ export namespace SessionProcessor {
   export interface Handle {
     readonly message: MessageV2.Assistant
     readonly partFromToolCall: (toolCallID: string) => MessageV2.ToolPart | undefined
+    readonly setToolMetadata: (toolCallID: string, val: { title?: string; metadata?: Record<string, any> }) => void
     readonly abort: () => Effect.Effect<void>
     readonly process: (streamInput: LLM.StreamInput) => Effect.Effect<Result>
   }
@@ -46,6 +47,7 @@ export namespace SessionProcessor {
 
   interface ProcessorContext extends Input {
     toolcalls: Record<string, MessageV2.ToolPart>
+    toolMetadata: Record<string, { title?: string; metadata?: Record<string, any> }>
     shouldBreak: boolean
     snapshot: string | undefined
     blocked: boolean
@@ -89,6 +91,7 @@ export namespace SessionProcessor {
           sessionID: input.sessionID,
           model: input.model,
           toolcalls: {},
+          toolMetadata: {},
           shouldBreak: false,
           snapshot: undefined,
           blocked: false,
@@ -173,10 +176,18 @@ export namespace SessionProcessor {
               }
               const match = ctx.toolcalls[value.toolCallId]
               if (!match) return
+              const pending = ctx.toolMetadata[value.toolCallId]
+              delete ctx.toolMetadata[value.toolCallId]
               ctx.toolcalls[value.toolCallId] = yield* session.updatePart({
                 ...match,
                 tool: value.toolName,
-                state: { status: "running", input: value.input, time: { start: Date.now() } },
+                state: {
+                  status: "running",
+                  input: value.input,
+                  time: { start: Date.now() },
+                  title: pending?.title,
+                  metadata: pending?.metadata,
+                },
                 metadata: value.providerMetadata,
               } satisfies MessageV2.ToolPart)
 
@@ -224,6 +235,7 @@ export namespace SessionProcessor {
                 },
               })
               delete ctx.toolcalls[value.toolCallId]
+              delete ctx.toolMetadata[value.toolCallId]
               return
             }
 
@@ -243,6 +255,7 @@ export namespace SessionProcessor {
                 ctx.blocked = ctx.shouldBreak
               }
               delete ctx.toolcalls[value.toolCallId]
+              delete ctx.toolMetadata[value.toolCallId]
               return
             }
 
@@ -494,6 +507,9 @@ export namespace SessionProcessor {
           partFromToolCall(toolCallID: string) {
             return ctx.toolcalls[toolCallID]
           },
+          setToolMetadata(toolCallID: string, val: { title?: string; metadata?: Record<string, any> }) {
+            ctx.toolMetadata[toolCallID] = val
+          },
           abort,
           process,
         } satisfies Handle

packages/opencode/src/session/prompt.ts

@@ -384,7 +384,7 @@ NOTE: At any point in time through this workflow you should feel free to ask the
         model: Provider.Model
         session: Session.Info
         tools?: Record<string, boolean>
-        processor: Pick<SessionProcessor.Handle, "message" | "partFromToolCall">
+        processor: Pick<SessionProcessor.Handle, "message" | "partFromToolCall" | "setToolMetadata">
         bypassAgentCheck: boolean
         messages: MessageV2.WithParts[]
       }) {
@@ -399,23 +399,23 @@ NOTE: At any point in time through this workflow you should feel free to ask the
           extra: { model: input.model, bypassAgentCheck: input.bypassAgentCheck },
           agent: input.agent.name,
           messages: input.messages,
-          metadata: (val) =>
-            Effect.runPromise(
+          metadata: (val) => {
+            input.processor.setToolMetadata(options.toolCallId, val)
+            return Effect.runPromise(
               Effect.gen(function* () {
                 const match = input.processor.partFromToolCall(options.toolCallId)
                 if (!match || match.state.status !== "running") return
                 yield* sessions.updatePart({
                   ...match,
                   state: {
+                    ...match.state,
                     title: val.title,
                     metadata: val.metadata,
-                    status: "running",
-                    input: args,
-                    time: { start: Date.now() },
                   },
                 })
               }),
-            ),
+            )
+          },
           ask: (req) =>
             Effect.runPromise(
               permission.ask({

packages/opencode/test/session/compaction.test.ts

@@ -149,6 +149,7 @@ function fake(
         state: { status: "pending", input: {}, raw: "" },
       }
     },
+    setToolMetadata() {},
     process: Effect.fn("TestSessionProcessor.process")(() => Effect.succeed(result)),
   } satisfies SessionProcessorModule.SessionProcessor.Handle
 }

packages/opencode/test/session/metadata-race.test.ts

@@ -0,0 +1,132 @@
+import { afterAll, beforeAll, beforeEach, describe, expect } from "bun:test"
+import { Effect, Fiber } from "effect"
+import z from "zod"
+import { ProviderID, ModelID } from "../../src/provider/schema"
+import { Session } from "../../src/session"
+import { MessageV2 } from "../../src/session/message-v2"
+import { SessionPrompt } from "../../src/session/prompt"
+import { MessageID, PartID } from "../../src/session/schema"
+import { Tool } from "../../src/tool/tool"
+import { ToolRegistry } from "../../src/tool/registry"
+import { Log } from "../../src/util/log"
+import { server, waitRequest, toolResponse, textResponse, deferred } from "../fixture/anthropic"
+import { env } from "../fixture/prompt-layers"
+import { provideTmpdirInstance } from "../fixture/fixture"
+import { testEffect } from "../lib/effect"
+
+Log.init({ print: false })
+
+beforeAll(() => server.start())
+beforeEach(() => server.reset())
+afterAll(() => server.stop())
+
+const it = testEffect(env)
+
+describe("session.processor.metadata-race", () => {
+  it.effect(
+    "ctx.metadata() survives pending→running transition through full prompt pipeline",
+    () =>
+      provideTmpdirInstance(
+        (_dir) =>
+          Effect.gen(function* () {
+            const signal = deferred<void>()
+            const gate = deferred<void>()
+
+            // 1. Register custom tool that calls ctx.metadata()
+            const reg = yield* ToolRegistry.Service
+            yield* reg.register(
+              Tool.define("test_metadata", {
+                description: "Test tool for metadata race",
+                parameters: z.object({ key: z.string() }),
+                async execute(_args, ctx) {
+                  ctx.metadata({ title: "test-task", metadata: { sessionId: "sess-123" } })
+                  signal.resolve()
+                  await gate.promise
+                  return { title: "test-task", metadata: {}, output: "done" }
+                },
+              }),
+            )
+
+            // 2. Create session with non-default title (suppresses title generation fork)
+            const sessions = yield* Session.Service
+            const chat = yield* sessions.create({ title: "Pinned" })
+
+            // 3. Create user message with anthropic model ref
+            const ref = {
+              providerID: ProviderID.make("anthropic"),
+              modelID: ModelID.make("claude-3-5-sonnet-20241022"),
+            }
+            const parent = yield* sessions.updateMessage({
+              id: MessageID.ascending(),
+              role: "user",
+              sessionID: chat.id,
+              agent: "build",
+              model: ref,
+              time: { created: Date.now() },
+            })
+            yield* sessions.updatePart({
+              id: PartID.ascending(),
+              messageID: parent.id,
+              sessionID: chat.id,
+              type: "text",
+              text: "call test_metadata",
+            })
+
+            // 4. Queue SSE responses: tool_use then text (for second loop iteration)
+            waitRequest("/messages", toolResponse("toolu_01", "test_metadata", { key: "value" }))
+            waitRequest("/messages", textResponse("Done"))
+
+            // 5. Fork prompt.loop on background fiber
+            const prompt = yield* SessionPrompt.Service
+            const fiber = yield* prompt.loop({ sessionID: chat.id }).pipe(Effect.forkChild)
+
+            // 6. Wait for tool execute to call ctx.metadata()
+            yield* Effect.promise(() => signal.promise)
+
+            // 7. Poll DB until tool part reaches running state
+            const deadline = Date.now() + 5_000
+            let tp: MessageV2.ToolPart | undefined
+            while (Date.now() < deadline) {
+              const msgs = yield* Effect.promise(() => MessageV2.filterCompacted(MessageV2.stream(chat.id)))
+              for (const m of msgs) {
+                if (m.info.role !== "assistant") continue
+                for (const p of m.parts) {
+                  if (p.type === "tool" && p.tool === "test_metadata" && p.state.status === "running") {
+                    tp = p as MessageV2.ToolPart
+                  }
+                }
+              }
+              if (tp) break
+              yield* Effect.promise(() => new Promise<void>((r) => setTimeout(r, 10)))
+            }
+
+            // 8. Assert: metadata must survive pending→running transition
+            expect(tp).toBeDefined()
+            expect(tp!.state.status).toBe("running")
+            const running = tp!.state as MessageV2.ToolStateRunning
+            expect(running.metadata).toBeDefined()
+            expect(running.metadata?.sessionId).toBe("sess-123")
+
+            // 9. Release gate to let tool complete
+            gate.resolve()
+
+            // 10. Wait for prompt.loop to finish
+            yield* Fiber.join(fiber)
+          }),
+        {
+          git: true,
+          config: {
+            provider: {
+              anthropic: {
+                options: {
+                  apiKey: "test-key",
+                  baseURL: `${server.origin}/v1`,
+                },
+              },
+            },
+          },
+        },
+      ),
+    60_000,
+  )
+})