[FEATURE]: Root session id header on LLM requests

Feature hasn't been suggested before.

I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Every sub-agent gets its own session in OpenCode, so on the wire x-opencode-session-id is the current session's id and x-opencode-parent-session-id names only the direct parent. No header on a request reaches past the direct parent, so once sub-agents nest nothing on the wire says which root session the program belongs to. A router grouping by program then has to remember parent links from earlier requests and walk to the root itself, which breaks when the links are spread across router replicas.

Could requests also carry the root session id, for example as a header?

x-opencode-root-session-id: <root of this session's parent chain>

On a root session it would just equal x-opencode-session-id, and following parentID links only means a fork stays its own root. Nothing changes for anyone who doesn't read the header. All request kinds build headers in one place (SessionModelRequest.prepare in packages/core/src/session/model-request.ts), so it should cover primary, generate, title and compaction alike. This seems related to the TODO in model-request.ts about persisting cache lineage so nested forks reuse the root session's cache key.

Why I'm asking: llm-d, an open-source inference gateway, has an agent-identity plugin that picks a per-session identity out of agent headers, and the router derives its fairness queue and per-session scheduling state from it. Claude Code and Codex both send one program-level id (x-claude-code-session-id / session_id = root thread id), so all requests of a program land in the same queue. With OpenCode the identity only reaches one level up, so programs with nested sub-agents fragment across queues instead of grouping as one program. I'am currently extending agent-identity toward session/thread/parent-aware scheduling for agentic traffic, and for OpenCode that means maintaining a stateful, per-replica parent map to derive the root session. A root header would make that unnecessary.

Thanks for the detailed request. You're asking for LLM requests to also carry the root session id of the sub-agent chain (for example x-opencode-root-session-id), so gateways like llm-d can group every request from one program without keeping their own parent map. Maintainers will consider it.

Until then, a plugin can add the header. In v2, the session model.request hook runs for every request kind (primary, generate, title, compaction) and can change the outgoing headers. Save this as .opencode/plugins/root-session-header.ts in your project, or in your global OpenCode config plugins/ directory:

import { Plugin } from "@opencode/plugin"

export default Plugin.define({
  id: "root-session-header",
  setup: async (ctx) => {
    // Session parent links never change, so cache the root for each session id.
    const roots = new Map<string, string>()
    const rootOf = async (id: string): Promise<string> => {
      const cached = roots.get(id)
      if (cached) return cached
      const session = await ctx.session.get({ sessionID: id })
      const root = session.parentID ? await rootOf(session.parentID) : id
      roots.set(id, root)
      return root
    }
    await ctx.session.hook("model.request", async (event) => {
      event.headers["x-opencode-root-session-id"] = await rootOf(event.sessionID)
    })
  },
})

It follows parentID links only. On a root session the header equals x-opencode-session-id, and a fork stays its own root, as you described. It type-checks against @opencode/plugin 2.0.27, but I haven't run it end to end, so please check that the header shows up on your gateway.

I didn't find an existing request for this. #46011 also involves session headers on outgoing requests (x-opencode-session), but it's a different problem.

happy to open a PR as well.

Navigation Menu

Repository navigation

[FEATURE]: Root session id header on LLM requests #54881

Feature hasn't been suggested before.

Describe the enhancement you want to request

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[FEATURE]: Root session id header on LLM requests #54881

Description

Feature hasn't been suggested before.

Describe the enhancement you want to request

Activity

opencode-agent commented on Oct 12, 2026

D-Sai-Venkatesh commented on Oct 23, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions