Repository navigation
[FEATURE]: Propagate session ID to tool subprocesses via environment variable #15739
Description
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
Feature Request
Problem
When OpenCode executes a tool (e.g., a bash command), it spawns a subprocess. That subprocess has no way to discover which OpenCode session triggered it. This makes it impossible for external systems — or even
the tool itself — to correlate their work back to a specific session.
Use Case
If you build tooling that wraps or extends OpenCode's tool execution (e.g., logging, metrics, multi-session orchestration), you need to know which session a tool invocation belongs to. Today, the only way to
attempt this is fragile heuristics like FIFO matching or content-based comparison, because the subprocess environment contains no session context.
Proposed Solution
Set environment variables on tool subprocesses before they are spawned:
OPENCODE_SESSION_ID— the session that triggered the tool callOPENCODE_TOOL_PART_ID(optional) — the part ID of the tool invocation within the message, for finer-grained correlation
This is a minimal, non-breaking change. Tools that don't need the information simply ignore the env vars.
Precedent
PR #12932 already propagates session context (as HTTP headers) for LLM requests. This proposal extends the same pattern to tool subprocess execution.
Activity
github-actions commentedon Mar 2, 2026
This issue might be a duplicate of existing issues. Please check:
OPENCODE_SESSION_IDon bash tool/shell subprocessesIf your request is distinct from those, please clarify how it differs.
feat: propagate session ID to tool subprocesses
taxilian commentedon Apr 9, 2026
#21756 would make it possible to have a plugin do this
XJfyrh commentedon Aug 3, 2026
This request would also directly prevent a class of correctness bugs I hit with concurrent sessions. Posting here rather than opening a duplicate issue, since this is the same root cause.
Real-world failure caused by the missing env var
I ran two opencode sessions in parallel, one per project directory (proj-a/ and proj-b/). Both agents created a temporary helper script with the same generic name (gen_appendix.py) in the shared pre-approved temp directory (%TEMP%\opencode).
Because there is no session identifier available in the subprocess environment, the agent could not name its scratch file uniquely. Session B overwrote the file while session A was still using it; session A then executed session B's script content (different paths, different logic) and wrote its output into the wrong project directory. The corruption was only caught because the script happened to print the output path.
Why this matters beyond external-tool correlation
The issue body frames OPENCODE_SESSION_ID as a need for external tooling (logging, orchestration). My case shows the env var is also needed for agent-internal correctness: an agent cannot isolate its own scratch files across concurrent sessions without it. That makes this a reliability/feature-availability gap, not just an observability nicety.
Concrete benefit if implemented
Agents could name temp files as ${OPENCODE_SESSION_ID} (or use a session-scoped dir such as %TEMP%\opencode<session-id>), eliminating last-writer-wins collisions entirely. This matches the project's own pattern of unique names in the tool-output store (e.g. tool).
Happy to provide more details or test once implemented.
ebuildy commentedon Sep 22, 2026
I have just found this bug too, tmp files are shared across sessions !!! 1 session create a file, other session overrides it ..... this is so dangerous.
Any news about it?
rekram1-node commentedon Sep 29, 2026
Implemented for the shell-tool subprocesses in #51975: commands (including background commands) receive
OPENCODE_SESSION_IDfrom the current tool session, replacing any stale inherited value. Child processes launched by those commands inherit it. This does not inject the ID into arbitrary plugin subprocesses or provide the optionalOPENCODE_TOOL_PART_ID.