fix(bash): compose plugin PATH instead of stomping system PATH

When plugins return PATH entries via the shell.env hook, prepend them
to the existing system PATH instead of replacing it entirely. This
preserves standard paths like /usr/bin.

Author: micuintus

packages/opencode/src/pty/index.ts

@@ -4,6 +4,7 @@ import { InstanceState } from "@/effect/instance-state"
 import { makeRuntime } from "@/effect/run-service"
 import { Instance } from "@/project/instance"
 import type { Proc } from "#pty"
+import path from "path"
 import z from "zod"
 import { Log } from "../util/log"
 import { lazy } from "@opencode-ai/util/lazy"
@@ -183,10 +184,16 @@ export namespace Pty {
 
         const cwd = input.cwd || s.dir
         const shell = yield* plugin.trigger("shell.env", { cwd }, { env: {} })
+        // Extract plugin PATH before spreading to compose rather than stomp
+        const pluginEnv: Record<string, string> = { ...shell.env }
+        const pluginPath = pluginEnv.PATH ?? ""
+        delete pluginEnv.PATH
         const env = {
           ...process.env,
           ...input.env,
-          ...shell.env,
+          ...pluginEnv,
+          // Compose PATH: plugin bins prepended, system PATH preserved
+          ...(pluginPath && { PATH: `${pluginPath}${path.delimiter}${process.env.PATH ?? ""}` }),
           TERM: "xterm-256color",
           OPENCODE_TERMINAL: "1",
         } as Record<string, string>

packages/opencode/src/tool/bash.ts

@@ -363,9 +363,15 @@ export const BashTool = Tool.define(
         { cwd, sessionID: ctx.sessionID, callID: ctx.callID },
         { env: {} },
       )
+      // Extract plugin PATH before spreading to compose rather than stomp
+      const env: Record<string, string> = { ...extra.env }
+      const paths = env.PATH ?? ""
+      delete env.PATH
       return {
         ...process.env,
-        ...extra.env,
+        ...env,
+        // Compose PATH: plugin bins prepended, system PATH preserved
+        ...(paths && { PATH: `${paths}${path.delimiter}${process.env.PATH ?? ""}` }),
       }
     })
 

packages/opencode/test/tool/path-composition.test.ts

@@ -0,0 +1,65 @@
+import { describe, test, expect } from "bun:test"
+import { readFileSync } from "fs"
+import { resolve } from "path"
+import path from "path"
+
+const bashSrc = readFileSync(resolve(import.meta.dir, "../../src/tool/bash.ts"), "utf-8")
+
+describe("shellEnv PATH composition", () => {
+  // Regression: plugin PATH entries via shell.env hook used to stomp the
+  // system PATH entirely (via spread ...extra.env). Commands like `ls` and
+  // `git` broke because /usr/bin was gone. The fix extracts plugin PATH
+  // before spreading, then prepends it to process.env.PATH.
+
+  test("extracts PATH from plugin env before spreading", () => {
+    // The fix must extract PATH, delete it, then compose
+    expect(bashSrc).toContain("const paths = env.PATH")
+    expect(bashSrc).toContain("delete env.PATH")
+  })
+
+  test("prepends plugin PATH to system PATH with delimiter", () => {
+    // Must use path.delimiter for cross-platform support (: on Unix, ; on Windows)
+    expect(bashSrc).toContain("path.delimiter")
+    // Must reference process.env.PATH to preserve system PATH
+    expect(bashSrc).toContain("process.env.PATH")
+  })
+
+  test("does not stomp system PATH when plugin provides PATH", () => {
+    // The old bug: ...extra.env would overwrite process.env.PATH
+    // The fix: spread env (without PATH), then compose PATH separately
+    const shellEnvMatch = bashSrc.match(/async function shellEnv[\s\S]*?^}/m)
+    expect(shellEnvMatch).not.toBeNull()
+    const body = shellEnvMatch![0]
+
+    // The return object must NOT spread ...extra.env directly (the old bug).
+    // It's fine in a copy (`{ ...extra.env }`) — the key is the return spreads
+    // the sanitized `...env` (with PATH removed) instead.
+    const returnMatch = body.match(/return \{[\s\S]*\}/)
+    expect(returnMatch).not.toBeNull()
+    expect(returnMatch![0]).not.toContain("...extra.env")
+
+    // Must spread the sanitized env (PATH removed)
+    expect(returnMatch![0]).toContain("...env")
+    // Must compose PATH in a separate spread
+    expect(body).toMatch(/paths && \{.*PATH:/)
+  })
+
+  test("handles empty plugin PATH (no PATH override)", () => {
+    // When plugin doesn't set PATH, paths === "" which is falsy,
+    // so the conditional spread is skipped and system PATH from
+    // ...process.env is preserved.
+    const shellEnvMatch = bashSrc.match(/async function shellEnv[\s\S]*?^}/m)
+    expect(shellEnvMatch).not.toBeNull()
+    const body = shellEnvMatch![0]
+
+    // The conditional must use a truthy check on paths
+    expect(body).toMatch(/paths && \{/)
+  })
+
+  // Verify the composition formula is correct
+  test("composition formula: plugin PATH + delimiter + system PATH", () => {
+    // The composed PATH must be: `${pluginPath}${delimiter}${systemPath}`
+    // This ensures plugin binaries are found first, system commands still work
+    expect(bashSrc).toMatch(/`\$\{paths\}\$\{path\.delimiter\}\$\{process\.env\.PATH \?\? ""\}`/)
+  })
+})