feat: send x-session-id and x-parent-session-id headers in LLM API requests

[jverkoey]

Summary

Forward opencode session identifiers as HTTP headers on all outgoing LLM API requests:

• x-session-id: Always present — identifies the current opencode session
• x-parent-session-id: Present only for sub-agent (task tool) sessions — identifies the parent session that spawned it

This enables any OpenAI-compatible backend to correlate requests belonging to the same session and reconstruct the full agent workflow tree when sub-agents are spawned.

Motivation

When running opencode against a local OpenAI-compatible server, there is currently no way for the server to determine which session a request belongs to, or whether it comes from a sub-agent. All requests arrive as independent /v1/chat/completions calls with no identifying metadata.

With these headers, a server can trivially build a tree view:

▼ ses_abc123 - "Help me refactor the auth module"
    ├─ ses_def456 - [task] glob search "src/**/*.ts"
    ├─ ses_ghi789 - [task] grep "authenticate"
    └─ ses_jkl012 - [task] reading 3 files

Changes

• packages/opencode/src/session/llm.ts: Add optional parentSessionID to StreamInput type; send x-session-id and x-parent-session-id headers on all LLM requests
• packages/opencode/src/session/prompt.ts: Pass session.parentID through as parentSessionID when building the stream input

Design

• Non-breaking: parentSessionID is optional — existing callers (summary, title agents) that don't pass it simply omit the parent header
• Additive headers: Providers that don't use these headers will ignore them
• Minimal diff: 4 lines added across 2 files
• Leverages existing data: session.parentID is already set by the task tool when creating sub-agent sessions (see tool/task.ts:73)

Related

• Closes [FEATURE]: Forward session & parent-session IDs as HTTP headers in LLM API requests #12930
• Related to Feature Request: Add Langfuse Tracing #219 (Langfuse tracing), Feature: Add sessionID to experimental.chat.system.transform hook for tracing integration #6142 (sessionID in hooks), [FEATURE]: Expose session context to child processes via environment variables #9292 (session context in env vars), [FEATURE]: Mistral Provider: Support x-affinity header for session continuation #11466 (Mistral x-affinity header)

Test plan

• Verify x-session-id header is present on all outgoing LLM requests
• Verify x-parent-session-id is present when a task tool sub-agent makes requests
• Verify x-parent-session-id is absent for top-level session requests
• Verify existing functionality (summary, title agents) continues working

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

Based on the search results, I found the following potentially related PRs (excluding the current PR #12932):

1. PR feat: add mistral session affinity header #11474 - feat: add mistral session affinity header

   • Related because it also deals with adding custom headers to LLM API requests for session correlation, similar to the x-session-id headers approach

2. PR feat(task): Add subagent-to-subagent delegation with budgets, persistent sessions, and hierarchical session navigation #7756 - feat(task): Add subagent-to-subagent delegation with budgets, persistent sessions, and hierarchical session navigation

   • Related because it involves session hierarchy and parent-child session relationships, which aligns with the parent-session-id functionality in PR feat: send x-session-id and x-parent-session-id headers in LLM API requests #12932

The current PR (#12932) appears to be addressing a specific issue (mentioned in "Closes #12930") by extending existing session handling mechanisms that were laid out in previous work.

[Pnlvfx]

I'm also dealing with this issue, any plan to merge this?