feat(tui): inherit terminal environment per session

packages/ai/src/protocols/anthropic-messages.ts

@@ -30,6 +30,7 @@ import { ToolSchemaProjection } from "./utils/tool-schema.js"
 import { ToolStream } from "./utils/tool-stream.js"
 
 const ADAPTER = "anthropic-messages"
+const MEDIA_MIMES = new Set<string>([...ProviderShared.IMAGE_MIMES, ...ProviderShared.PDF_MIMES])
 export const DEFAULT_BASE_URL = "https://api.anthropic.com/v1"
 export const PATH = "/messages"
 
@@ -399,7 +400,7 @@ const lowerServerToolResult = Effect.fn("AnthropicMessages.lowerServerToolResult
 })
 
 const lowerMedia = Effect.fn("AnthropicMessages.lowerMedia")(function* (part: MediaPart) {
-  const media = ProviderShared.normalizeMedia(part)
+  const media = yield* ProviderShared.validateMedia("Anthropic Messages", part, MEDIA_MIMES)
   if (media.mime === "application/pdf")
     return {
       type: "document" as const,
@@ -409,8 +410,6 @@ const lowerMedia = Effect.fn("AnthropicMessages.lowerMedia")(function* (part: Me
         data: media.base64,
       },
     } satisfies AnthropicDocumentBlock
-  if (!media.mime.startsWith("image/"))
-    return yield* invalid(`Anthropic Messages does not support media type ${part.mediaType}`)
   return {
     type: "image" as const,
     source: {

packages/ai/src/protocols/gemini.ts

@@ -24,6 +24,7 @@ import { Lifecycle } from "./utils/lifecycle.js"
 import { ToolSchemaProjection } from "./utils/tool-schema.js"
 
 const ADAPTER = "gemini"
+const MEDIA_MIMES = new Set<string>(ProviderShared.MEDIA_MIMES)
 // Google documents this sentinel for replaying Gemini 3 function calls after their original signature was lost.
 const SKIP_THOUGHT_SIGNATURE_VALIDATOR = "skip_thought_signature_validator"
 export const DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
@@ -247,7 +248,7 @@ const lowerToolConfig = (toolChoice: NonNullable<LLMRequest["toolChoice"]>) =>
 
 const lowerUserPart = Effect.fn("Gemini.lowerUserPart")(function* (part: TextPart | MediaPart) {
   if (part.type === "text") return { text: part.text }
-  const media = ProviderShared.normalizeMedia(part)
+  const media = yield* ProviderShared.validateMedia("Gemini", part, MEDIA_MIMES)
   return { inlineData: { mimeType: media.mime, data: media.base64 } }
 })
 
@@ -352,7 +353,7 @@ const lowerMessages = Effect.fn("Gemini.lowerMessages")(function* (request: LLMR
       const media: GeminiInlineDataPart[] = []
       for (const item of content) {
         if (item.type === "text") continue
-        const value = ProviderShared.normalizeToolFile(item)
+        const value = yield* ProviderShared.validateToolFile("Gemini", item, MEDIA_MIMES)
         media.push({ inlineData: { mimeType: value.mime, data: value.base64 } })
       }
       parts.push({

packages/ai/src/protocols/open-responses.ts

@@ -26,6 +26,7 @@ import { ToolStream } from "./utils/tool-stream.js"
 
 const ADAPTER = "open-responses"
 const NAME = "Open Responses"
+const MEDIA_MIMES = new Set<string>([...ProviderShared.IMAGE_MIMES, ...ProviderShared.PDF_MIMES])
 export const PATH = "/responses"
 
 // =============================================================================
@@ -284,7 +285,7 @@ export interface Extension {
   readonly name: string
   readonly lowerMedia?: (input: {
     readonly part: MediaPart
-    readonly media: ProviderShared.NormalizedMedia
+    readonly media: ProviderShared.ValidatedMedia
     readonly request: LLMRequest
   }) => MediaInput | undefined
   readonly messagePhase?: (value: unknown) => MessagePhase | null | undefined
@@ -379,13 +380,13 @@ const lowerMedia = Effect.fn("OpenResponses.lowerMedia")(function* (
   request: LLMRequest,
   extension: Extension,
 ) {
-  const media = ProviderShared.normalizeMedia(part)
+  const media = yield* ProviderShared.validateMedia(extension.name, part, MEDIA_MIMES)
   const extended = extension.lowerMedia?.({ part, media, request })
   if (extended) return extended
-  if (!media.mime.startsWith("image/")) {
+  if (media.mime === "application/pdf") {
     return {
       type: "input_file" as const,
-      filename: part.filename ?? (media.mime === "application/pdf" ? "document.pdf" : "file"),
+      filename: part.filename ?? "document.pdf",
       file_data: media.dataUrl,
     }
   }

packages/ai/src/protocols/openai-chat.ts

@@ -28,6 +28,7 @@ import { ToolSchemaProjection } from "./utils/tool-schema.js"
 import { ToolStream } from "./utils/tool-stream.js"
 
 const ADAPTER = "openai-chat"
+const IMAGE_MIMES = new Set<string>(ProviderShared.IMAGE_MIMES)
 const RESERVED_REASONING_FIELDS = new Set(["role", "content", "tool_calls"])
 export const DEFAULT_BASE_URL = "https://api.openai.com/v1"
 export const PATH = "/chat/completions"
@@ -283,9 +284,7 @@ const lowerToolCall = (part: ToolCallPart): OpenAIChatAssistantToolCall => ({
 })
 
 const lowerMedia = Effect.fn("OpenAIChat.lowerMedia")(function* (part: MediaPart) {
-  const media = ProviderShared.normalizeMedia(part)
-  if (!media.mime.startsWith("image/"))
-    return yield* ProviderShared.invalidRequest(`OpenAI Chat does not support media type ${part.mediaType}`)
+  const media = yield* ProviderShared.validateMedia("OpenAI Chat", part, IMAGE_MIMES)
   return { type: "image_url" as const, image_url: { url: media.dataUrl } }
 })
 

packages/ai/src/protocols/shared.ts

@@ -155,24 +155,59 @@ export const wrappedSystemUpdate = Effect.fn("ProviderShared.wrappedSystemUpdate
 export const parseToolInput = (route: string, name: string, raw: string) =>
   parseJson(route, raw || "{}", `Invalid JSON input for ${route} tool call ${name}`)
 
-export interface NormalizedMedia {
+export const IMAGE_MIMES = ["image/png", "image/jpeg", "image/gif", "image/webp"] as const
+export const VIDEO_MIMES = ["video/mp4", "video/webm", "video/quicktime"] as const
+export const AUDIO_MIMES = ["audio/wav", "audio/mp3", "audio/aiff", "audio/aac", "audio/ogg", "audio/flac"] as const
+export const PDF_MIMES = ["application/pdf"] as const
+export const MEDIA_MIMES = [...IMAGE_MIMES, ...VIDEO_MIMES, ...AUDIO_MIMES, ...PDF_MIMES] as const
+export const MAX_MEDIA_ENCODED_BYTES = 28 * 1024 * 1024
+export const MAX_MEDIA_DECODED_BYTES = 20 * 1024 * 1024
+
+const base64Pattern = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/
+
+export interface ValidatedMedia {
   readonly mime: string
   readonly base64: string
   readonly dataUrl: string
+  readonly bytes: Uint8Array
 }
 
-export const normalizeMedia = (part: MediaPart): NormalizedMedia => {
+export const validateMedia = Effect.fn("ProviderShared.validateMedia")(function* (
+  route: string,
+  part: MediaPart,
+  supportedMimes: ReadonlySet<string>,
+) {
   const mime = part.mediaType.toLowerCase()
-  if (typeof part.data !== "string") {
-    const base64 = Buffer.from(part.data).toString("base64")
-    return { mime, base64, dataUrl: `data:${mime};base64,${base64}` }
-  }
-  if (!part.data.startsWith("data:")) return { mime, base64: part.data, dataUrl: `data:${mime};base64,${part.data}` }
-  return { mime, base64: part.data.slice(part.data.indexOf(",") + 1), dataUrl: part.data }
-}
+  if (!supportedMimes.has(mime)) return yield* invalidRequest(`${route} does not support media type ${part.mediaType}`)
 
-export const normalizeToolFile = (part: Tool.FileContent) =>
-  normalizeMedia({ type: "media", mediaType: part.mime, data: part.uri, filename: part.name })
+  let base64: string
+  if (typeof part.data !== "string") {
+    if (part.data.byteLength > MAX_MEDIA_DECODED_BYTES)
+      return yield* invalidRequest(`${route} media exceeds the ${MAX_MEDIA_DECODED_BYTES} byte decoded limit`)
+    base64 = Buffer.from(part.data).toString("base64")
+  } else if (part.data.startsWith("data:")) {
+    const match = /^data:([^;,]+);base64,([A-Za-z0-9+/]*={0,2})$/s.exec(part.data)
+    if (!match) return yield* invalidRequest(`${route} media data URL must contain valid base64`)
+    if (match[1]!.toLowerCase() !== mime)
+      return yield* invalidRequest(`${route} media type ${part.mediaType} does not match data URL type ${match[1]}`)
+    base64 = match[2]!
+  } else {
+    base64 = part.data
+  }
+
+  if (Buffer.byteLength(base64, "utf8") > MAX_MEDIA_ENCODED_BYTES)
+    return yield* invalidRequest(`${route} media exceeds the ${MAX_MEDIA_ENCODED_BYTES} byte encoded limit`)
+  if (!base64 || base64.length % 4 !== 0 || !base64Pattern.test(base64))
+    return yield* invalidRequest(`${route} media must contain valid base64`)
+  const bytes = Buffer.from(base64, "base64")
+  if (bytes.byteLength > MAX_MEDIA_DECODED_BYTES)
+    return yield* invalidRequest(`${route} media exceeds the ${MAX_MEDIA_DECODED_BYTES} byte decoded limit`)
+  if (bytes.toString("base64") !== base64) return yield* invalidRequest(`${route} media must contain canonical base64`)
+  return { mime, base64, dataUrl: `data:${mime};base64,${base64}`, bytes } satisfies ValidatedMedia
+})
+
+export const validateToolFile = (route: string, part: Tool.FileContent, supportedMimes: ReadonlySet<string>) =>
+  validateMedia(route, { type: "media", mediaType: part.mime, data: part.uri, filename: part.name }, supportedMimes)
 
 export const trimBaseUrl = (value: string) => value.replace(/\/+$/, "")
 

packages/ai/src/protocols/utils/bedrock-media.ts

@@ -66,7 +66,11 @@ export const lower = Effect.fn("BedrockMedia.lower")(function* (part: MediaPart)
   const mime = part.mediaType.toLowerCase()
   const imageFormat = IMAGE_FORMATS[mime as keyof typeof IMAGE_FORMATS]
   if (imageFormat) {
-    const media = ProviderShared.normalizeMedia(part)
+    const media = yield* ProviderShared.validateMedia(
+      "Bedrock Converse",
+      part,
+      new Set<string>(Object.keys(IMAGE_FORMATS)),
+    )
     return { image: { format: imageFormat, source: { bytes: media.base64 } } } satisfies ImageBlock
   }
   if (mime.startsWith("image/"))
@@ -75,7 +79,11 @@ export const lower = Effect.fn("BedrockMedia.lower")(function* (part: MediaPart)
   if (documentFormat) {
     if (!part.filename)
       return yield* ProviderShared.invalidRequest("Bedrock Converse document media requires a filename")
-    const media = ProviderShared.normalizeMedia(part)
+    const media = yield* ProviderShared.validateMedia(
+      "Bedrock Converse",
+      part,
+      new Set<string>(Object.keys(DOCUMENT_FORMATS)),
+    )
     return documentBlock(part.filename, documentFormat, media.base64)
   }
   return yield* ProviderShared.invalidRequest(`Bedrock Converse does not support media type ${part.mediaType}`)

packages/ai/test/provider/anthropic-messages.test.ts

@@ -399,7 +399,7 @@ describe("Anthropic Messages route", () => {
     }),
   )
 
-  it.effect("rejects tool-result media that cannot be lowered", () =>
+  it.effect("rejects unsupported media in tool-result content with a clear error", () =>
     Effect.gen(function* () {
       const error = yield* compileRequest(
         LLM.request({
@@ -418,7 +418,8 @@ describe("Anthropic Messages route", () => {
         }),
       ).pipe(Effect.flip)
 
-      expect(error.message).toContain("Anthropic Messages does not support media type audio/mpeg")
+      expect(error.message).toContain("Anthropic Messages")
+      expect(error.message).toContain("audio/mpeg")
     }),
   )
 

packages/ai/test/provider/gemini.test.ts

@@ -4,6 +4,7 @@ import { LLM, AIError, LLMRequest, Message, ToolCallPart, ToolDefinition, Usage
 import { Auth, LLMClient } from "../../src/route.js"
 import { compileRequest } from "../../src/route/client.js"
 import * as Gemini from "../../src/protocols/gemini.js"
+import { ProviderShared } from "../../src/protocols/shared.js"
 import { it } from "../lib/effect.js"
 import { fixedResponse } from "../lib/http.js"
 import { sseEvents, sseRaw } from "../lib/sse.js"
@@ -290,30 +291,35 @@ describe("Gemini route", () => {
     }),
   )
 
-  it.effect("passes encoded media through without local validation", () =>
+  for (const [name, media] of [
+    ["mismatched data URL MIME", { mediaType: "image/png", data: "data:image/jpeg;base64,/9j/" }],
+    ["malformed base64", { mediaType: "image/png", data: "%%%=" }],
+    ["unsupported SVG", { mediaType: "image/svg+xml", data: "PHN2Zz4=" }],
+  ] as const)
+    it.effect(`rejects ${name}`, () =>
+      Effect.gen(function* () {
+        const error = yield* compileRequest(
+          LLM.request({ model, messages: [Message.user({ type: "media", ...media })] }),
+        ).pipe(Effect.flip)
+        expect(error.message).toMatch(/does not support|does not match|valid base64/)
+      }),
+    )
+
+  it.effect("rejects oversized image input", () =>
     Effect.gen(function* () {
-      const prepared = yield* compileRequest(
+      const error = yield* compileRequest(
         LLM.request({
           model,
           messages: [
-            Message.user([
-              { type: "media", mediaType: "image/png", data: "%%%=" },
-              { type: "media", mediaType: "image/png", data: "data:image/jpeg;base64,/9j/" },
-              { type: "media", mediaType: "image/svg+xml", data: "PHN2Zz4=" },
-            ]),
+            Message.user({
+              type: "media",
+              mediaType: "image/png",
+              data: "A".repeat(ProviderShared.MAX_MEDIA_ENCODED_BYTES + 4),
+            }),
           ],
         }),
-      )
-      expect(prepared.body.contents).toEqual([
-        {
-          role: "user",
-          parts: [
-            { inlineData: { mimeType: "image/png", data: "%%%=" } },
-            { inlineData: { mimeType: "image/png", data: "/9j/" } },
-            { inlineData: { mimeType: "image/svg+xml", data: "PHN2Zz4=" } },
-          ],
-        },
-      ])
+      ).pipe(Effect.flip)
+      expect(error.message).toContain("encoded limit")
     }),
   )
 

packages/ai/test/provider/openai-chat.test.ts

@@ -527,42 +527,35 @@ describe("OpenAI Chat route", () => {
     }),
   )
 
-  it.effect("passes encoded image media through without local validation", () =>
-    Effect.gen(function* () {
-      const prepared = yield* compileRequest(
-        LLM.request({
-          model,
-          messages: [
-            Message.user([
-              { type: "media", mediaType: "image/png", data: "not-base64" },
-              { type: "media", mediaType: "image/png", data: "data:image/jpeg;base64,/9j/" },
-              { type: "media", mediaType: "image/svg+xml", data: "PHN2Zz4=" },
-            ]),
-          ],
-        }),
-      )
-      expect(prepared.body.messages).toEqual([
-        {
-          role: "user",
-          content: [
-            { type: "image_url", image_url: { url: "data:image/png;base64,not-base64" } },
-            { type: "image_url", image_url: { url: "data:image/jpeg;base64,/9j/" } },
-            { type: "image_url", image_url: { url: "data:image/svg+xml;base64,PHN2Zz4=" } },
-          ],
-        },
-      ])
-    }),
-  )
+  for (const [name, media] of [
+    ["mismatched data URL MIME", { mediaType: "image/png", data: "data:image/jpeg;base64,/9j/" }],
+    ["malformed base64", { mediaType: "image/png", data: "not-base64" }],
+    ["unsupported SVG", { mediaType: "image/svg+xml", data: "PHN2Zz4=" }],
+  ] as const)
+    it.effect(`rejects ${name}`, () =>
+      Effect.gen(function* () {
+        const error = yield* compileRequest(
+          LLM.request({ model, messages: [Message.user({ type: "media", ...media })] }),
+        ).pipe(Effect.flip)
+        expect(error.message).toMatch(/does not support|does not match|valid base64/)
+      }),
+    )
 
-  it.effect("rejects non-image media that cannot be lowered", () =>
+  it.effect("rejects oversized image input", () =>
     Effect.gen(function* () {
       const error = yield* compileRequest(
         LLM.request({
           model,
-          messages: [Message.user({ type: "media", mediaType: "audio/mpeg", data: "AAECAw==" })],
+          messages: [
+            Message.user({
+              type: "media",
+              mediaType: "image/png",
+              data: "A".repeat(ProviderShared.MAX_MEDIA_ENCODED_BYTES + 4),
+            }),
+          ],
         }),
       ).pipe(Effect.flip)
-      expect(error.message).toContain("OpenAI Chat does not support media type audio/mpeg")
+      expect(error.message).toContain("encoded limit")
     }),
   )
 

packages/ai/test/provider/openai-responses.test.ts

@@ -1149,32 +1149,6 @@ describe("OpenAI Responses route", () => {
     }),
   )
 
-  it.effect("passes large PDF tool-result content through", () =>
-    Effect.gen(function* () {
-      const base64 = "A".repeat(8_125_844)
-      const dataUrl = `data:application/pdf;base64,${base64}`
-      const prepared = yield* compileRequest(
-        LLM.request({
-          id: "req_tool_result_large_pdf",
-          model,
-          messages: [
-            Message.assistant([ToolCallPart.make({ id: "call_1", name: "read", input: {} })]),
-            Message.tool({
-              id: "call_1",
-              name: "read",
-              resultType: "content",
-              result: [{ type: "file", uri: dataUrl, mime: "application/pdf", name: "report.pdf" }],
-            }),
-          ],
-        }),
-      )
-
-      expect(expectToolOutput(prepared.body).output).toEqual([
-        { type: "input_file", filename: "report.pdf", file_data: dataUrl },
-      ])
-    }),
-  )
-
   it.effect("uses xAI inline file encoding for PDF tool results", () =>
     Effect.gen(function* () {
       const prepared = yield* compileRequest(
@@ -1210,9 +1184,9 @@ describe("OpenAI Responses route", () => {
     }),
   )
 
-  it.effect("passes non-image tool-result content through as an input file", () =>
+  it.effect("rejects unsupported media in tool-result content with a clear error", () =>
     Effect.gen(function* () {
-      const prepared = yield* compileRequest(
+      const error = yield* compileRequest(
         LLM.request({
           id: "req_tool_result_unsupported_media",
           model,
@@ -1226,11 +1200,10 @@ describe("OpenAI Responses route", () => {
             }),
           ],
         }),
-      )
+      ).pipe(Effect.flip)
 
-      expect(expectToolOutput(prepared.body).output).toEqual([
-        { type: "input_file", filename: "file", file_data: "data:audio/mpeg;base64,AAECAw==" },
-      ])
+      expect(error.message).toContain("OpenAI Responses")
+      expect(error.message).toContain("audio/mpeg")
     }),
   )
 
@@ -2421,28 +2394,17 @@ describe("OpenAI Responses route", () => {
     }),
   )
 
-  it.effect("passes non-image user media through as an input file", () =>
+  it.effect("rejects unsupported user media content", () =>
     Effect.gen(function* () {
-      const prepared = yield* compileRequest(
+      const error = yield* compileRequest(
         LLM.request({
           id: "req_media",
           model,
           messages: [Message.user({ type: "media", mediaType: "application/x-tar", data: "AAECAw==" })],
         }),
-      )
+      ).pipe(Effect.flip)
 
-      expect(prepared.body.input).toEqual([
-        {
-          role: "user",
-          content: [
-            {
-              type: "input_file",
-              filename: "file",
-              file_data: "data:application/x-tar;base64,AAECAw==",
-            },
-          ],
-        },
-      ])
+      expect(error.message).toContain("OpenAI Responses does not support media type application/x-tar")
     }),
   )
 

packages/cli/src/commands/handlers/default.ts

@@ -10,15 +10,17 @@ import { Updater } from "../../services/updater"
 import { UpdatePreflight } from "../../services/update-preflight"
 import { Npm } from "@opencode-ai/util/npm"
 import { OPENCODE_CHANNEL, OPENCODE_VERSION } from "../../version"
+import { Env } from "../../env"
 
 export default Runtime.handler(Commands, (input) =>
   Effect.gen(function* () {
     const requestedDirectory = Option.getOrUndefined(input.directory)
+    const requestedServer = Option.getOrUndefined(input.server)
     if (requestedDirectory !== undefined) process.chdir(requestedDirectory)
     const preflight = UpdatePreflight.make()
     yield* Effect.addFinalizer(() => Effect.promise(() => preflight.close()))
     const server = yield* ServerConnection.resolve({
-      server: Option.getOrUndefined(input.server),
+      server: requestedServer,
       standalone: input.standalone,
       mismatch: "replace",
       onStart: (reason, previousVersion) => {
@@ -75,6 +77,7 @@ export default Runtime.handler(Commands, (input) =>
         resolve: (spec) =>
           runPromise(npm.add(spec, { subpaths: ["tui"] }).pipe(Effect.map((result) => result.entrypoint))),
       },
+      environment: requestedServer === undefined ? Env.session() : undefined,
       terminalHandoff: () => preflight.finish(),
       log: (level, message, tags) => {
         const effect =

packages/cli/src/env.ts

@@ -12,4 +12,13 @@ export const password = Config.redacted("OPENCODE_PASSWORD").pipe(
   Config.withDefault(undefined),
 )
 
+export function session() {
+  return Object.fromEntries(
+    Object.entries(process.env).filter(
+      (entry): entry is [string, string] =>
+        entry[1] !== undefined && entry[0] !== "OPENCODE_PASSWORD" && entry[0] !== "OPENCODE_SERVER_PASSWORD",
+    ),
+  )
+}
+
 export * as Env from "./env"

packages/cli/test/env.test.ts

@@ -0,0 +1,24 @@
+import { expect, test } from "bun:test"
+import { Env } from "../src/env"
+
+test("session environment omits server credentials", () => {
+  const previousPassword = process.env.OPENCODE_PASSWORD
+  const previousLegacyPassword = process.env.OPENCODE_SERVER_PASSWORD
+  const previousValue = process.env.OPENCODE_SESSION_ENV_TEST
+  process.env.OPENCODE_PASSWORD = "password"
+  process.env.OPENCODE_SERVER_PASSWORD = "legacy"
+  process.env.OPENCODE_SESSION_ENV_TEST = "included"
+
+  const environment = Env.session()
+
+  if (previousPassword === undefined) delete process.env.OPENCODE_PASSWORD
+  else process.env.OPENCODE_PASSWORD = previousPassword
+  if (previousLegacyPassword === undefined) delete process.env.OPENCODE_SERVER_PASSWORD
+  else process.env.OPENCODE_SERVER_PASSWORD = previousLegacyPassword
+  if (previousValue === undefined) delete process.env.OPENCODE_SESSION_ENV_TEST
+  else process.env.OPENCODE_SESSION_ENV_TEST = previousValue
+
+  expect(environment.OPENCODE_PASSWORD).toBeUndefined()
+  expect(environment.OPENCODE_SERVER_PASSWORD).toBeUndefined()
+  expect(environment.OPENCODE_SESSION_ENV_TEST).toBe("included")
+})

packages/client/src/effect/api/api.ts

@@ -914,6 +914,10 @@ export type Endpoint5_34Input = { readonly sessionID: Session.ID; readonly messa
 export type Endpoint5_34Output = SessionMessage.Info
 export type SessionMessageOperation<E = never> = (input: Endpoint5_34Input) => Effect.Effect<Endpoint5_34Output, E>
 
+export type Endpoint5_35Input = { readonly sessionID: Session.ID; readonly variables: { readonly [x: string]: string } }
+export type Endpoint5_35Output = void
+export type SessionEnvironmentOperation<E = never> = (input: Endpoint5_35Input) => Effect.Effect<Endpoint5_35Output, E>
+
 export interface SessionApi<E = never> {
   readonly list: SessionListOperation<E>
   readonly create: SessionCreateOperation<E>
@@ -958,6 +962,7 @@ export interface SessionApi<E = never> {
   readonly interrupt: SessionInterruptOperation<E>
   readonly background: SessionBackgroundOperation<E>
   readonly message: SessionMessageOperation<E>
+  readonly environment: SessionEnvironmentOperation<E>
 }
 
 export type Endpoint6_0Input = {

packages/client/src/effect/generated/client.ts

@@ -86,6 +86,8 @@ import type {
   Endpoint5_33Output,
   Endpoint5_34Input,
   Endpoint5_34Output,
+  Endpoint5_35Input,
+  Endpoint5_35Output,
   Endpoint6_0Input,
   Endpoint6_0Output,
   Endpoint7_0Input,
@@ -610,6 +612,14 @@ const Endpoint5_34 = (raw: RawClient["server.session"]) => (input: Endpoint5_34I
     ),
   )
 
+const Endpoint5_35 = (raw: RawClient["server.session"]) => (input: Endpoint5_35Input) =>
+  preserveEffect<Endpoint5_35Output>()(
+    raw["session.environment"]({
+      params: { sessionID: input["sessionID"] },
+      payload: { variables: input["variables"] },
+    }).pipe(Effect.mapError(mapClientError)),
+  )
+
 const adaptGroup5 = (raw: RawClient["server.session"]) => ({
   list: Endpoint5_0(raw),
   create: Endpoint5_1(raw),
@@ -639,6 +649,7 @@ const adaptGroup5 = (raw: RawClient["server.session"]) => ({
   interrupt: Endpoint5_32(raw),
   background: Endpoint5_33(raw),
   message: Endpoint5_34(raw),
+  environment: Endpoint5_35(raw),
 })
 
 const Endpoint6_0 = (raw: RawClient["server.message"]) => (input: Endpoint6_0Input) =>

packages/client/src/promise/generated/client.ts

@@ -80,6 +80,8 @@ import type {
   SessionBackgroundOutput,
   SessionMessageInput,
   SessionMessageOutput,
+  SessionEnvironmentInput,
+  SessionEnvironmentOutput,
   MessageListInput,
   MessageListOutput,
   ModelListInput,
@@ -896,6 +898,18 @@ export function make(options: ClientOptions) {
           },
           requestOptions,
         ).then((value) => value.data),
+      environment: (input: SessionEnvironmentInput, requestOptions?: RequestOptions) =>
+        request<SessionEnvironmentOutput>(
+          {
+            method: "PUT",
+            path: `/api/session/${encodeURIComponent(input.sessionID)}/environment`,
+            body: { variables: input["variables"] },
+            successStatus: 204,
+            declaredStatuses: [404, 401, 400],
+            empty: true,
+          },
+          requestOptions,
+        ),
     },
     message: {
       list: (input: MessageListInput, requestOptions?: RequestOptions) =>

packages/client/src/promise/generated/types.ts

@@ -3936,6 +3936,13 @@ export type SessionMessageInput = {
 
 export type SessionMessageOutput = { data: SessionMessageInfo }["data"]
 
+export type SessionEnvironmentInput = {
+  readonly sessionID: { readonly sessionID: string }["sessionID"]
+  readonly variables: { readonly variables: { readonly [x: string]: string } }["variables"]
+}
+
+export type SessionEnvironmentOutput = void
+
 export type MessageListInput = {
   readonly sessionID: { readonly sessionID: string }["sessionID"]
   readonly limit?: {

packages/core/src/aisdk.ts

@@ -435,22 +435,7 @@ function prompt(request: LLMRequest): LanguageModelV3Prompt {
     .map((part) => part.text)
     .filter(Boolean)
     .join("\n\n")
-  const pending: UserContent = []
-  const messages = request.messages.flatMap((input, index) => {
-    if (input.role !== "tool") return message(input)
-    const lowered = toolMessage(input)
-    pending.push(...lowered.media)
-    if (request.messages[index + 1]?.role === "tool" || pending.length === 0) return lowered.messages
-    const media = [...pending]
-    pending.length = 0
-    return [
-      ...lowered.messages,
-      {
-        role: "user" as const,
-        content: [{ type: "text" as const, text: "Attached media from tool result:" }, ...media],
-      },
-    ]
-  })
+  const messages = request.messages.flatMap(message)
   if (!system.length) return messages
   return [{ role: "system", content: system }, ...messages]
 }
@@ -463,33 +448,10 @@ function message(input: LLMRequest["messages"][number]): LanguageModelV3Message[
       return [{ role: "user", content: input.content.flatMap(userPart) }]
     case "assistant":
       return [{ role: "assistant", content: input.content.flatMap(assistantPart) }]
-    case "tool":
-      return toolMessage(input).messages
-  }
-}
-
-function toolMessage(input: LLMRequest["messages"][number]) {
-  const media: UserContent = []
-  const content = input.content.flatMap((part) => {
-    if (part.type !== "tool-result" || part.result.type !== "content") return toolResultPart(part)
-    const value = part.result.value.filter((item) => {
-      if (item.type !== "file") return true
-      if (!item.mime.startsWith("image/") && item.mime !== "application/pdf") return true
-      const data = /^data:[^;,]+(?:;[^,]*)*;base64,(.*)$/s.exec(item.uri)?.[1] ?? item.uri
-      media.push({ type: "file", mediaType: item.mime, data, filename: item.name })
-      return false
-    })
-    return toolResultPart({
-      ...part,
-      result:
-        value.length === 0
-          ? { type: "text", value: "Media attached in the following user message." }
-          : { ...part.result, value },
-    })
-  })
-  return {
-    messages: content.length ? ([{ role: "tool", content }] satisfies LanguageModelV3Message[]) : [],
-    media,
+    case "tool": {
+      const content = input.content.flatMap(toolResultPart)
+      return content.length ? [{ role: "tool", content }] : []
+    }
   }
 }
 

packages/core/src/plugin/plan.ts

@@ -1,6 +1,6 @@
 export * as PlanPlugin from "./plan.js"
 
-import { Message, ToolFailure } from "@opencode-ai/ai"
+import { ToolFailure } from "@opencode-ai/ai"
 import { define } from "@opencode-ai/plugin/effect/plugin"
 import { Effect, Stream } from "effect"
 import { Agent } from "../agent.js"
@@ -38,33 +38,13 @@ export const Plugin = define({
       })
     })
 
-    // Compaction and committed reverts can strip reminders while the session's agent stays
-    // put. Reconcile per request, appending near the tail so the cached prefix stays warm.
-    yield* ctx.session.hook("context", (event) => {
-      const reminder = lastReminder(event.messages)
-      const missing = event.agent === plan && reminder !== enter
-      const stale = event.agent !== plan && reminder === enter
-      const text = missing ? enter : stale ? leave : undefined
-      if (!text) return Effect.void
-      // Before the user's prompt, matching where agent-switch reminders land.
-      const at = event.messages.at(-1)?.role === "user" ? event.messages.length - 1 : event.messages.length
-      event.messages.splice(at, 0, Message.user(text))
-      return ctx.session
-        .synthetic({ sessionID: event.sessionID, text, resume: false })
-        .pipe(
-          Effect.catchCause((cause) =>
-            Effect.logWarning("failed to persist Plan mode reminder", { sessionID: event.sessionID, cause }),
-          ),
-        )
-    })
-
     yield* ctx.event.subscribe().pipe(
       Stream.filter(
         (event): event is SessionEvent.Created | SessionEvent.AgentSelected =>
           event.type === "session.created" || event.type === "session.agent.selected",
       ),
       Stream.runForEach((event) => {
-        const text = switchReminder(event)
+        const text = reminder(event)
         if (!text) return Effect.void
         return ctx.session
           .synthetic({
@@ -83,7 +63,7 @@ export const Plugin = define({
   }),
 })
 
-function switchReminder(event: SessionEvent.Created | SessionEvent.AgentSelected) {
+function reminder(event: SessionEvent.Created | SessionEvent.AgentSelected) {
   if (event.type === "session.created") {
     if (event.data.agent !== plan) return
     return enter
@@ -92,11 +72,3 @@ function switchReminder(event: SessionEvent.Created | SessionEvent.AgentSelected
   if (event.data.agent === plan) return enter
   if (event.data.previous === plan) return leave
 }
-
-function lastReminder(messages: ReadonlyArray<Message>) {
-  return messages.reduce<string | undefined>((found, message) => {
-    const part = message.role === "user" && message.content.length === 1 ? message.content[0] : undefined
-    if (part?.type !== "text") return found
-    return part.text === enter || part.text === leave ? part.text : found
-  }, undefined)
-}

packages/core/src/session.ts

@@ -51,6 +51,7 @@ import { Global } from "@opencode-ai/util/global"
 import { Shell as ShellSchema } from "@opencode-ai/schema/shell"
 import { KeyedMutex } from "./effect/keyed-mutex.js"
 import { fileURLToPath } from "url"
+import { SessionEnvironment } from "./session/environment.js"
 
 // get project -> project.locations
 //
@@ -165,6 +166,10 @@ export interface Interface {
     input: ForkInput,
   ) => Effect.Effect<SessionSchema.Info, NotFoundError | MessageNotFoundError | ForkEmptyError>
   readonly get: (sessionID: SessionSchema.ID) => Effect.Effect<SessionSchema.Info, NotFoundError>
+  readonly environment: (input: {
+    readonly sessionID: SessionSchema.ID
+    readonly variables?: SessionEnvironment.Variables
+  }) => Effect.Effect<SessionEnvironment.Variables | undefined, NotFoundError>
   readonly remove: (sessionID: SessionSchema.ID) => Effect.Effect<void, NotFoundError>
   readonly messages: (input: {
     sessionID: SessionSchema.ID
@@ -304,6 +309,7 @@ const layer = Layer.effect(
     const locations = yield* LocationServiceMap.Service
     const fs = yield* FSUtil.Service
     const jobs = yield* Job.Service
+    const environments = yield* SessionEnvironment.Service
     const scope = yield* Scope.Scope
     const activeShells = new Set<SessionSchema.ID>()
     const shellLocks = KeyedMutex.makeUnsafe<SessionSchema.ID>()
@@ -447,6 +453,11 @@ const layer = Layer.effect(
         if (!session) return yield* new NotFoundError({ sessionID })
         return session
       }),
+      environment: Effect.fn("Session.environment")(function* (input) {
+        yield* result.get(input.sessionID)
+        if (input.variables !== undefined) yield* environments.set(input.sessionID, input.variables)
+        return yield* environments.get(input.sessionID)
+      }),
       remove: Effect.fn("Session.remove")(function* (sessionID) {
         const session = yield* result.get(sessionID)
         yield* execution.interrupt(sessionID)
@@ -454,6 +465,7 @@ const layer = Layer.effect(
         yield* closeTransport(session)
         const children = yield* result.list({ parentID: sessionID })
         yield* Effect.forEach(children.data, (child) => result.remove(child.id), { concurrency: 1, discard: true })
+        yield* environments.clear(sessionID)
         yield* bus.publish(SessionEvent.Deleted, { sessionID })
         yield* bus.remove(sessionID)
       }),
@@ -652,7 +664,12 @@ const layer = Layer.effect(
             const started = yield* Effect.gen(function* () {
               const shell = yield* Shell.Service
               return yield* shell
-                .create({ command: input.command, cwd: session.location.directory, timeout: 0 })
+                .create({
+                  command: input.command,
+                  cwd: session.location.directory,
+                  timeout: 0,
+                  metadata: { sessionID: input.sessionID },
+                })
                 .pipe(Effect.orDie)
             }).pipe(Effect.provide(locations.get(session.location)))
             yield* bus.publish(
@@ -1102,6 +1119,7 @@ export const node = makeGlobalNode({
   layer: layer.pipe(Layer.orDie),
   deps: [
     Job.node,
+    SessionEnvironment.node,
     Database.node,
     Bus.node,
     Project.node,

packages/core/src/session/environment.ts

@@ -0,0 +1,41 @@
+export * as SessionEnvironment from "./environment.js"
+
+import { Context, Effect, Layer, Ref } from "effect"
+import { makeGlobalNode } from "@opencode-ai/util/effect/app-node"
+import { SessionSchema } from "./schema.js"
+
+export type Variables = Readonly<Record<string, string>>
+
+export interface Interface {
+  readonly get: (sessionID: SessionSchema.ID) => Effect.Effect<Variables | undefined>
+  readonly set: (sessionID: SessionSchema.ID, variables: Variables) => Effect.Effect<void>
+  readonly clear: (sessionID: SessionSchema.ID) => Effect.Effect<void>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@opencode/SessionEnvironment") {}
+
+const layer = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const environments = yield* Ref.make(new Map<SessionSchema.ID, Variables>())
+
+    return Service.of({
+      get: Effect.fn("SessionEnvironment.get")(function* (sessionID) {
+        return (yield* Ref.get(environments)).get(sessionID)
+      }),
+      set: Effect.fn("SessionEnvironment.set")(function* (sessionID, variables) {
+        yield* Ref.update(environments, (current) => new Map(current).set(sessionID, { ...variables }))
+      }),
+      clear: Effect.fn("SessionEnvironment.clear")(function* (sessionID) {
+        yield* Ref.update(environments, (current) => {
+          if (!current.has(sessionID)) return current
+          const next = new Map(current)
+          next.delete(sessionID)
+          return next
+        })
+      }),
+    })
+  }),
+)
+
+export const node = makeGlobalNode({ service: Service, layer, deps: [] })

packages/core/src/shell.ts

@@ -15,6 +15,8 @@ import { Global } from "@opencode-ai/util/global"
 import { ShellSelect } from "./shell/select.js"
 import type { ShellCreateBefore } from "@opencode-ai/plugin/effect/shell"
 import { PluginHooks } from "./plugin/hooks.js"
+import { SessionEnvironment } from "./session/environment.js"
+import { SessionSchema } from "./session/schema.js"
 
 export class NotFoundError extends Schema.TaggedErrorClass<NotFoundError>()("Shell.NotFoundError", {
   id: Shell.ID,
@@ -76,6 +78,7 @@ export const layer = (options?: ShellSelect.Options) =>
       const global = yield* Global.Service
       const environment = yield* Environment.Service
       const hooks = yield* PluginHooks.Service
+      const environments = yield* SessionEnvironment.Service
       const context = yield* Effect.context()
       const runFork = Effect.runForkWith(context)
       const sessions = new Map<string, Active>()
@@ -184,13 +187,18 @@ export const layer = (options?: ShellSelect.Options) =>
         input: Shell.CreateInput,
         before?: (input: ShellCreateBefore) => Effect.Effect<void, E, R>,
       ) {
+        const sessionID = input.metadata?.sessionID
+        const sessionEnvironment =
+          location.workspaceID === undefined && Schema.is(SessionSchema.ID)(sessionID)
+            ? yield* environments.get(sessionID)
+            : undefined
         const invocation: ShellCreateBefore = {
           command: input.command,
           cwd: input.cwd ?? location.directory,
           timeout: input.timeout,
           shell: yield* resolve(),
           env: {
-            ...process.env,
+            ...(sessionEnvironment ?? process.env),
             TERM: "xterm-256color",
             OPENCODE_TERMINAL: "1",
           },
@@ -349,7 +357,15 @@ export function configured(options?: ShellSelect.Options) {
   return makeLocationNode({
     service: Service,
     layer: layer(options),
-    deps: [Bus.node, Location.node, Config.node, Global.node, Environment.node, PluginHooks.node],
+    deps: [
+      Bus.node,
+      Location.node,
+      Config.node,
+      Global.node,
+      Environment.node,
+      PluginHooks.node,
+      SessionEnvironment.node,
+    ],
   })
 }
 

packages/core/test/aisdk.test.ts

@@ -1,6 +1,5 @@
 import { APICallError } from "@ai-sdk/provider"
 import type { LanguageModelV3, LanguageModelV3StreamPart } from "@ai-sdk/provider"
-import { createMistral } from "@ai-sdk/mistral"
 import { AISDK } from "@opencode-ai/core/aisdk"
 import { SessionRunnerRetry } from "@opencode-ai/core/session/runner/retry"
 import { toSessionError } from "@opencode-ai/core/session/to-session-error"
@@ -278,88 +277,67 @@ it.effect("projects replay metadata onto AI SDK prompt parts", () =>
   }),
 )
 
-it.effect("moves a tool image through the real Mistral provider as a user message", () =>
+it.effect("preserves tool result content in AI SDK prompts", () =>
   Effect.gen(function* () {
     const aisdk = yield* AISDK.Service
-    let body: { messages?: unknown[] } | undefined
-    const mockFetch = Object.assign(
-      async (_input: Parameters<typeof fetch>[0], init?: RequestInit) => {
-        body = JSON.parse(String(init?.body))
-        const chunks = [
-          {
-            id: "response-1",
-            created: 0,
-            model: "pixtral-large-latest",
-            choices: [{ index: 0, delta: { content: [{ type: "text", text: "I see it." }] } }],
-          },
-          {
-            id: "response-1",
-            created: 0,
-            model: "pixtral-large-latest",
-            choices: [{ index: 0, delta: {}, finish_reason: "stop" }],
-            usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
-          },
-        ]
-        return new Response(chunks.map((chunk) => `data: ${JSON.stringify(chunk)}\n\n`).join(""), {
-          headers: { "Content-Type": "text/event-stream" },
-        })
-      },
-      { preconnect: fetch.preconnect },
-    )
     yield* aisdk.hook.sdk((event) => {
-      event.sdk = createMistral({ apiKey: "test", fetch: mockFetch })
+      event.sdk = { languageModel: () => ({ provider: event.model.providerID }) }
     })
 
-    const resolved = yield* aisdk.model({
-      ...model("@ai-sdk/mistral"),
-      modelID: Model.ID.make("pixtral-large-latest"),
-    })
-    yield* LLMClient.generate(
+    const resolved = yield* aisdk.model(model("test-ai-sdk"))
+    const prepared = yield* compileRequest(
       LLM.request({
         model: resolved,
         messages: [
-          Message.user("Inspect the screenshot."),
-          Message.assistant({ type: "tool-call", id: "call_1", name: "screenshot", input: {} }),
           Message.tool({
-            type: "tool-result",
             id: "call_1",
-            name: "screenshot",
+            name: "read",
             result: {
               type: "content",
               value: [
-                { type: "text", text: "Screenshot captured" },
-                { type: "file", uri: "data:image/png;base64,AAAA", mime: "image/png", name: "screen.png" },
+                { type: "text", text: "attachments" },
+                { type: "file", uri: "data:image/png;base64,AAAA", mime: "image/png", name: "pixel.png" },
+                {
+                  type: "file",
+                  uri: "data:application/pdf;charset=utf-8;base64,JVBERg==",
+                  mime: "application/pdf",
+                  name: "document.pdf",
+                },
+                { type: "file", uri: "data:audio/mpeg;base64,SUQz", mime: "audio/mpeg", name: "clip.mp3" },
+                { type: "file", uri: "https://example.com/pixel.png", mime: "image/png" },
+                { type: "file", uri: "https://example.com/document.pdf", mime: "application/pdf" },
               ],
             },
           }),
         ],
       }),
-    ).pipe(Effect.provide(client))
+    )
 
-    expect(body?.messages).toEqual([
-      { role: "user", content: [{ type: "text", text: "Inspect the screenshot." }] },
-      {
-        role: "assistant",
-        content: "",
-        tool_calls: [
-          {
-            id: "call_1",
-            type: "function",
-            function: { name: "screenshot", arguments: "{}" },
-          },
-        ],
-      },
+    expect(prepared.body.prompt).toEqual([
       {
         role: "tool",
-        name: "screenshot",
-        tool_call_id: "call_1",
-        content: '[{"type":"text","text":"Screenshot captured"}]',
-      },
-      {
-        role: "user",
         content: [
-          { type: "text", text: "Attached media from tool result:" },
-          { type: "image_url", image_url: "data:image/png;base64,AAAA" },
+          {
+            type: "tool-result",
+            toolCallId: "call_1",
+            toolName: "read",
+            output: {
+              type: "content",
+              value: [
+                { type: "text", text: "attachments" },
+                { type: "image-data", data: "AAAA", mediaType: "image/png" },
+                {
+                  type: "file-data",
+                  data: "JVBERg==",
+                  mediaType: "application/pdf",
+                  filename: "document.pdf",
+                },
+                { type: "file-data", data: "SUQz", mediaType: "audio/mpeg", filename: "clip.mp3" },
+                { type: "image-url", url: "https://example.com/pixel.png" },
+                { type: "file-url", url: "https://example.com/document.pdf" },
+              ],
+            },
+          },
         ],
       },
     ])

packages/core/test/plugin/plan.test.ts

@@ -1,180 +0,0 @@
-import { describe, expect } from "bun:test"
-import { Message } from "@opencode-ai/ai"
-import { DateTime, Effect, Stream } from "effect"
-import type { SessionContext } from "@opencode-ai/plugin/effect/session"
-import { Agent } from "@opencode-ai/core/agent"
-import { Event } from "@opencode-ai/schema/event"
-import { Model } from "@opencode-ai/core/model"
-import { PlanPlugin } from "@opencode-ai/core/plugin/plan"
-import { Provider } from "@opencode-ai/core/provider"
-import { Session } from "@opencode-ai/core/session"
-import { SessionEvent } from "@opencode-ai/core/session/event"
-import { SessionInbox } from "@opencode-ai/core/session/inbox"
-import { SessionMessage } from "@opencode-ai/core/session/message"
-import { it } from "../lib/effect"
-import { host } from "./host"
-
-const sessionID = Session.ID.make("ses_plan_test")
-const plan = Agent.ID.make("plan")
-const build = Agent.ID.make("build")
-
-const agentSelected = (agent: Agent.ID, previous: Agent.ID): SessionEvent.AgentSelected => ({
-  id: Event.ID.create(),
-  created: 0,
-  durable: { aggregateID: sessionID, seq: Event.Seq.make(0), version: Event.Version.make(1) },
-  type: "session.agent.selected",
-  data: { sessionID, agent, previous },
-})
-
-/** Runs the plan plugin against stubbed domains, capturing persisted reminders and the context hook. */
-const run = Effect.fnUntraced(function* (events: ReadonlyArray<SessionEvent.AgentSelected> = []) {
-  const persisted = new Array<string>()
-  let contextHook: ((input: SessionContext) => Effect.Effect<void>) | undefined
-  yield* PlanPlugin.Plugin.effect(
-    host({
-      agent: {
-        get: () => Effect.die("unused agent.get"),
-        list: () => Effect.die("unused agent.list"),
-        reload: () => Effect.die("unused agent.reload"),
-        transform: () => Effect.succeed({ dispose: Effect.void }),
-      },
-      tool: {
-        transform: () => Effect.die("unused tool.transform"),
-        hook: () => Effect.succeed({ dispose: Effect.void }),
-      },
-      event: {
-        subscribe: () => Stream.fromIterable(events),
-      },
-      session: {
-        hook: (name, callback) => {
-          if (name === "context") contextHook = callback as (input: SessionContext) => Effect.Effect<void>
-          return Effect.succeed({ dispose: Effect.void })
-        },
-        synthetic: (input) => {
-          persisted.push(input.text)
-          return Effect.succeed(
-            SessionInbox.Synthetic.make({
-              id: SessionMessage.ID.make("msg_plan_test"),
-              sessionID,
-              timeCreated: DateTime.makeUnsafe(0),
-              type: "synthetic",
-              payload: { text: input.text },
-              delivery: "steer",
-            }),
-          )
-        },
-      },
-    }),
-  )
-  if (!contextHook) return yield* Effect.die("plan plugin did not register a context hook")
-  return { persisted, contextHook }
-})
-
-const request = (agent: Agent.ID, messages: Array<Message>): SessionContext => ({
-  sessionID,
-  agent,
-  model: { id: Model.ID.make("test-model"), providerID: Provider.ID.make("test") },
-  system: [],
-  messages,
-  tools: {},
-})
-
-const settle = (persisted: ReadonlyArray<string>, expected: number, remaining = 1000): Effect.Effect<void, Error> =>
-  Effect.gen(function* () {
-    if (persisted.length >= expected) return
-    if (remaining === 0) {
-      return yield* Effect.fail(new Error(`Timed out waiting for ${expected} reminders, saw ${persisted.length}`))
-    }
-    yield* Effect.promise(() => Bun.sleep(1))
-    yield* settle(persisted, expected, remaining - 1)
-  })
-
-/** The exact reminder texts, derived from plugin behavior rather than duplicated here. */
-const reminders = Effect.gen(function* () {
-  const planRun = yield* run()
-  yield* planRun.contextHook(request(plan, []))
-  const buildRun = yield* run()
-  yield* buildRun.contextHook(request(build, [Message.user(planRun.persisted[0]!)]))
-  return { enter: planRun.persisted[0]!, leave: buildRun.persisted[0]! }
-})
-
-describe("plan plugin reminders", () => {
-  it.effect("injects enter and leave reminders on agent switches", () =>
-    Effect.gen(function* () {
-      const { persisted } = yield* run([agentSelected(plan, build), agentSelected(build, plan)])
-      yield* settle(persisted, 2)
-      expect(persisted[0]).toContain("You are in Plan mode")
-      expect(persisted[1]).toContain("NO LONGER in Plan mode")
-    }),
-  )
-
-  it.effect("reconciles a missing enter reminder into the request and persists it", () =>
-    Effect.gen(function* () {
-      const { persisted, contextHook } = yield* run()
-      const messages = [Message.user("what agent are you?")]
-      yield* contextHook(request(plan, messages))
-      expect(messages).toHaveLength(2)
-      // Inserted before the user's prompt, matching where agent-switch reminders land.
-      const first = messages[0]?.content[0]
-      expect(first?.type === "text" && first.text).toContain("You are in Plan mode")
-      expect(persisted).toHaveLength(1)
-    }),
-  )
-
-  it.effect("does nothing when the transcript already has a live enter reminder", () =>
-    Effect.gen(function* () {
-      const { enter } = yield* reminders
-      const { persisted, contextHook } = yield* run()
-      const messages = [Message.user(enter), Message.user("hello")]
-      yield* contextHook(request(plan, messages))
-      expect(messages).toHaveLength(2)
-      expect(persisted).toHaveLength(0)
-    }),
-  )
-
-  it.effect("reconciles a stale enter reminder with a leave reminder", () =>
-    Effect.gen(function* () {
-      const { enter } = yield* reminders
-      const { persisted, contextHook } = yield* run()
-      const messages = [Message.user(enter), Message.user("ok implement it")]
-      yield* contextHook(request(build, messages))
-      expect(messages).toHaveLength(3)
-      const middle = messages[1]?.content[0]
-      expect(middle?.type === "text" && middle.text).toContain("NO LONGER in Plan mode")
-      expect(persisted).toHaveLength(1)
-    }),
-  )
-
-  it.effect("does nothing for non-plan sessions without plan history", () =>
-    Effect.gen(function* () {
-      const { persisted, contextHook } = yield* run()
-      const messages = [Message.user("hello")]
-      yield* contextHook(request(build, messages))
-      expect(messages).toHaveLength(1)
-      expect(persisted).toHaveLength(0)
-    }),
-  )
-
-  it.effect("does nothing when a leave reminder already follows the enter reminder", () =>
-    Effect.gen(function* () {
-      const { enter, leave } = yield* reminders
-      const { persisted, contextHook } = yield* run()
-      const messages = [Message.user(enter), Message.user(leave), Message.user("continue")]
-      yield* contextHook(request(build, messages))
-      expect(messages).toHaveLength(3)
-      expect(persisted).toHaveLength(0)
-    }),
-  )
-
-  it.effect("treats reminder text quoted inside a larger message as not live", () =>
-    Effect.gen(function* () {
-      const { enter } = yield* reminders
-      const { persisted, contextHook } = yield* run()
-      // Mirrors a compaction checkpoint quoting the reminder inside <recent-context>.
-      const messages = [Message.user(`<conversation-checkpoint>\n${enter}\n</conversation-checkpoint>`)]
-      yield* contextHook(request(plan, messages))
-      expect(messages).toHaveLength(2)
-      expect(persisted).toHaveLength(1)
-    }),
-  )
-})

packages/core/test/session-create.test.ts

@@ -679,13 +679,18 @@ describe("Session.create", () => {
         const created = yield* session.create({
           location: Location.Ref.make({ directory: AbsolutePath.make(directory) }),
         })
+        yield* session.environment({ sessionID: created.id, variables: { OPENCODE_SESSION_ENV_TEST: "attached" } })
 
-        yield* session.shell({ sessionID: created.id, command: "echo hello" })
+        const command =
+          process.platform === "win32"
+            ? "[Console]::Out.Write($env:OPENCODE_SESSION_ENV_TEST)"
+            : 'printf %s "$OPENCODE_SESSION_ENV_TEST"'
+        yield* session.shell({ sessionID: created.id, command })
 
         const messages = yield* session.messages({ sessionID: created.id, order: "asc" })
         const shell = messages.find((message): message is SessionMessage.Shell => message.type === "shell")
-        expect(shell).toMatchObject({ type: "shell", command: "echo hello", status: "exited", exit: 0 })
-        expect(shell?.output?.output).toContain("hello")
+        expect(shell).toMatchObject({ type: "shell", command, status: "exited", exit: 0 })
+        expect(shell?.output?.output).toContain("attached")
         expect(shell?.output?.truncated).toBe(false)
         expect(shell?.time.completed).toBeDefined()
       }),

packages/core/test/session-environment.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
+import { Session } from "@opencode-ai/core/session"
+import { SessionEnvironment } from "@opencode-ai/core/session/environment"
+import { testEffect } from "./lib/effect"
+
+const it = testEffect(AppNodeBuilder.build(SessionEnvironment.node))
+
+describe("SessionEnvironment", () => {
+  it.effect("stores replacement snapshots by session", () =>
+    Effect.gen(function* () {
+      const environments = yield* SessionEnvironment.Service
+      const first = Session.ID.make("ses_environment_first")
+      const second = Session.ID.make("ses_environment_second")
+
+      yield* environments.set(first, { TOOLCHAIN: "first", PATH: "/first/bin" })
+      yield* environments.set(second, { TOOLCHAIN: "second" })
+      yield* environments.set(first, { TOOLCHAIN: "updated" })
+
+      expect(yield* environments.get(first)).toEqual({ TOOLCHAIN: "updated" })
+      expect(yield* environments.get(second)).toEqual({ TOOLCHAIN: "second" })
+
+      yield* environments.clear(first)
+
+      expect(yield* environments.get(first)).toBeUndefined()
+      expect(yield* environments.get(second)).toEqual({ TOOLCHAIN: "second" })
+    }),
+  )
+})

packages/core/test/session-remove.test.ts

@@ -12,6 +12,7 @@ import { SessionExecution } from "@opencode-ai/core/session/execution"
 import { SessionModelTransport } from "@opencode-ai/core/session/model-transport"
 import { SessionProjector } from "@opencode-ai/core/session/projector"
 import { SessionStore } from "@opencode-ai/core/session/store"
+import { SessionEnvironment } from "@opencode-ai/core/session/environment"
 import { LocationServiceMap } from "@opencode-ai/core/location-services"
 import { testEffect } from "./lib/effect"
 import { globalProjectLayer } from "./lib/project"
@@ -32,6 +33,7 @@ const it = testEffect(
       Bus.node,
       SessionProjector.node,
       SessionStore.node,
+      SessionEnvironment.node,
       Session.node,
       LocationServiceMap.node,
     ]),
@@ -50,6 +52,8 @@ describe("Session.remove", () => {
       const session = yield* Session.Service
       const parent = yield* session.create({ location })
       const child = yield* session.create({ parentID: parent.id })
+      yield* session.environment({ sessionID: parent.id, variables: { SESSION_ENV: "parent" } })
+      yield* session.environment({ sessionID: child.id, variables: { SESSION_ENV: "child" } })
       yield* (yield* LocationServiceMap.Service).contextEffect(location)
       closed.length = 0
 
@@ -57,6 +61,9 @@ describe("Session.remove", () => {
 
       expect((yield* session.list()).data).toEqual([])
       expect(closed).toEqual([parent.id, child.id])
+      const environments = yield* SessionEnvironment.Service
+      expect(yield* environments.get(parent.id)).toBeUndefined()
+      expect(yield* environments.get(child.id)).toBeUndefined()
       expect(yield* Effect.result(session.get(parent.id))).toMatchObject({ _tag: "Failure" })
       expect(yield* Effect.result(session.get(child.id))).toMatchObject({ _tag: "Failure" })
     }),

packages/core/test/tool-shell.test.ts

@@ -260,6 +260,36 @@ describe("ShellTool", () => {
     { timeout: 15_000 },
   )
 
+  productionIt.live(
+    "uses the session environment instead of the server environment",
+    () =>
+      Effect.acquireUseRelease(
+        Effect.promise(() => tmpdir()),
+        (tmp) => {
+          reset()
+          return withSession(tmp.path, (registry) =>
+            Effect.gen(function* () {
+              const sessions = yield* Session.Service
+              yield* sessions.environment({
+                sessionID,
+                variables: { OPENCODE_SESSION_ENV_TEST: "from-session" },
+              })
+              const command = isWindows
+                ? "[Console]::Out.Write($env:OPENCODE_SESSION_ENV_TEST)"
+                : 'printf %s "$OPENCODE_SESSION_ENV_TEST"'
+
+              const settled = yield* executeTool(registry, call({ command }))
+
+              expect(settled.status).toBe("completed")
+              expect(settled.content?.[0]).toEqual({ type: "text", text: "from-session" })
+            }),
+          )
+        },
+        (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]().then(() => undefined)),
+      ),
+    { timeout: 15_000 },
+  )
+
   it.live("resolves a relative workdir from the active Location", () =>
     Effect.acquireUseRelease(
       Effect.promise(() => tmpdir()),

packages/protocol/src/groups/session.ts

@@ -693,6 +693,20 @@ export const makeSessionGroup = <I extends HttpApiMiddleware.AnyId, S>(sessionLo
         }),
       ),
     )
+    .add(
+      HttpApiEndpoint.put("session.environment", "/api/session/:sessionID/environment", {
+        params: { sessionID: Session.ID },
+        payload: Schema.Struct({ variables: Schema.Record(Schema.String, Schema.String) }),
+        success: HttpApiSchema.NoContent,
+        error: SessionNotFoundError,
+      }).annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.session.environment",
+          summary: "Set session environment",
+          description: "Replace the process environment used by local shell commands for this session.",
+        }),
+      ),
+    )
     .annotateMerge(
       OpenApi.annotations({
         title: "session",

packages/server/src/handlers/session.ts

@@ -196,6 +196,22 @@ export const SessionHandler = HttpApiBuilder.group(Api, "server.session", (handl
           return HttpApiSchema.NoContent.make()
         }),
       )
+      .handle(
+        "session.environment",
+        Effect.fn(function* (ctx) {
+          yield* session.environment({ sessionID: ctx.params.sessionID, variables: ctx.payload.variables }).pipe(
+            Effect.catchTag(
+              "Session.NotFoundError",
+              (error) =>
+                new SessionNotFoundError({
+                  sessionID: error.sessionID,
+                  message: `Session not found: ${error.sessionID}`,
+                }),
+            ),
+          )
+          return HttpApiSchema.NoContent.make()
+        }),
+      )
       .handle(
         "session.fork",
         Effect.fn(function* (ctx) {

packages/tui/src/app.tsx

@@ -41,6 +41,7 @@ import {
   useTuiApp,
   useTuiPaths,
   useTuiStartup,
+  useTuiTerminalEnvironment,
   type TuiApp,
 } from "./context/runtime"
 import { DialogProvider, useDialog } from "./ui/dialog"
@@ -185,6 +186,7 @@ export type TuiInput = {
   args: Args
   config: Config.Interface
   packages: PackageResolver
+  environment?: Readonly<Record<string, string>>
   terminalHandoff?: () => Promise<
     | {
         readonly renderer: CliRenderer
@@ -332,6 +334,7 @@ export const run = Effect.fn("Tui.run")(function* (input: TuiInput) {
                                   : process.env.DISPLAY
                                     ? "x11"
                                     : undefined,
+                                variables: input.environment,
                               }}
                             >
                               <TuiStartupProvider
@@ -480,6 +483,17 @@ function App(props: { pair?: DialogPairCredentials }) {
   const promptRef = usePromptRef()
   const plugins = usePlugin()
   const clipboard = useClipboard()
+  const terminalEnvironment = useTuiTerminalEnvironment()
+  createEffect(() => {
+    if (client.connection.status() !== "connected") return
+    if (route.data.type !== "session") return
+    const session = data.session.get(route.data.sessionID)
+    if (!session) return
+    if (session.location.workspaceID !== undefined || terminalEnvironment.variables === undefined) return
+    void client.api.session
+      .environment({ sessionID: session.id, variables: terminalEnvironment.variables })
+      .catch(toast.error)
+  })
   const [layout, updateLayout] = useStorage().store<{ verticalTabsWidth?: number }>("layout", {
     initial: { verticalTabsWidth: SESSION_SIDEBAR_WIDTH },
   })

packages/tui/src/component/prompt/index.tsx

@@ -1206,6 +1206,19 @@ export function Prompt(props: PromptProps) {
 
       sessionID = created.id
       session = created
+      if (created.location.workspaceID === undefined && terminalEnvironment.variables !== undefined) {
+        const error = await client.api.session
+          .environment({ sessionID, variables: terminalEnvironment.variables })
+          .then(
+            () => undefined,
+            (error) => error,
+          )
+        if (error) {
+          if (finishMoveProgress) move.finishSubmit()
+          toast.show({ title: "Failed to set session environment", message: errorMessage(error), variant: "error" })
+          return true
+        }
+      }
     }
 
     // Capture mode before it gets reset

packages/tui/src/context/local.tsx

@@ -10,7 +10,6 @@ import { useClient } from "./client"
 import { RGBA } from "@opentui/core"
 import { readJson, writeJsonAtomic } from "../util/persistence"
 import {
-  availableModelVariant,
   createModelPreferenceRepository,
   cycleModelVariant,
   modelPreferenceKey,
@@ -222,14 +221,7 @@ export const { use: useLocal, provider: LocalProvider } = createSimpleContext({
         if (route.data.type === "session") return sessionSelection(route.data.sessionID)
         const model = newSessionModel()
         if (!model) return
-        const info = models()?.find((item) => item.providerID === model.providerID && item.id === model.modelID)
-        return {
-          ...model,
-          variant: availableModelVariant(
-            preferences.variant[modelPreferenceKey(model)],
-            info?.variants?.map((item) => item.id) ?? [],
-          ),
-        }
+        return { ...model, variant: normalizeModelVariant(preferences.variant[modelPreferenceKey(model)]) }
       })
 
       const currentModel = createMemo(() => {
@@ -270,12 +262,13 @@ export const { use: useLocal, provider: LocalProvider } = createSimpleContext({
         if (route.data.type === "session") {
           const sessionID = route.data.sessionID
           const current = sessionSelection(sessionID)
-          const preferred =
+          const preferred = normalizeModelVariant(
             current?.providerID === model.providerID && current.modelID === model.modelID
               ? current.variant
-              : preferences.variant[modelPreferenceKey(model)]
+              : preferences.variant[modelPreferenceKey(model)],
+          )
           const info = models()?.find((item) => item.providerID === model.providerID && item.id === model.modelID)
-          const variant = availableModelVariant(preferred, info?.variants?.map((item) => item.id) ?? [])
+          const variant = preferred && info?.variants?.some((item) => item.id === preferred) ? preferred : undefined
           setSessionDraft(sessionID, { ...model, variant })
           return true
         }

packages/tui/src/context/runtime.tsx

@@ -17,6 +17,7 @@ export type TuiTerminalEnvironment = Readonly<{
   platform: string
   multiplexer?: "tmux" | "screen"
   displayServer?: "wayland" | "x11"
+  variables?: Readonly<Record<string, string>>
 }>
 
 export type TuiStartup = Readonly<{

packages/tui/src/model-preference.ts

@@ -39,11 +39,6 @@ export function normalizeModelVariant(value: string | undefined) {
   return value === "default" ? undefined : value
 }
 
-export function availableModelVariant(value: string | undefined, variants: string[]) {
-  const variant = normalizeModelVariant(value)
-  return variant && variants.includes(variant) ? variant : undefined
-}
-
 export function modelPreferenceKey(model: ModelPreferenceModel) {
   return `${model.providerID}/${model.modelID}`
 }

packages/tui/test/model-preference.test.ts

@@ -1,6 +1,6 @@
 import { expect, test } from "bun:test"
 import path from "node:path"
-import { availableModelVariant, createModelPreferenceRepository, decodeModelPreference } from "../src/model-preference"
+import { createModelPreferenceRepository, decodeModelPreference } from "../src/model-preference"
 import { tmpdir } from "./fixture/fixture"
 
 test("repairs known model preferences and preserves unrelated fields", () => {
@@ -19,12 +19,6 @@ test("repairs known model preferences and preserves unrelated fields", () => {
   })
 })
 
-test("drops a saved variant that is no longer available", () => {
-  expect(availableModelVariant("medium", [])).toBeUndefined()
-  expect(availableModelVariant("medium", ["low", "high"])).toBeUndefined()
-  expect(availableModelVariant("medium", ["low", "medium", "high"])).toBe("medium")
-})
-
 test("atomically serializes patches and variant updates", async () => {
   await using tmp = await tmpdir()
   const file = path.join(tmp.path, "model.json")