feat(environment): introduce disable_omo_env configuration option

- Added a new configuration option `disable_omo_env` to control the injection of the `<omo-env>` block in agent prompts.
- Updated relevant functions and tests to support this feature, ensuring that the environment context can be toggled on or off as needed.
- Enhanced documentation to reflect the new option and its implications for API cost and cache hit rates.

src/agents/builtin-agents.ts

@@ -69,8 +69,10 @@ export async function createBuiltinAgents(
   browserProvider?: BrowserAutomationProvider,
   uiSelectedModel?: string,
   disabledSkills?: Set<string>,
-  useTaskSystem = false
+  useTaskSystem = false,
+  disableOmoEnv = false
 ): Promise<Record<string, AgentConfig>> {
+
   const connectedProviders = readConnectedProvidersCache()
   const providerModelsConnected = connectedProviders
     ? (readProviderModelsCache()?.connected ?? [])
@@ -112,6 +114,7 @@ export async function createBuiltinAgents(
     uiSelectedModel,
     availableModels,
     disabledSkills,
+    disableOmoEnv,
   })
 
   const registeredAgents = parseRegisteredAgentSummaries(customAgentSummaries)
@@ -145,6 +148,7 @@ export async function createBuiltinAgents(
     directory,
     userCategories: categories,
     useTaskSystem,
+    disableOmoEnv,
   })
   if (sisyphusConfig) {
     result["sisyphus"] = sisyphusConfig
@@ -162,6 +166,7 @@ export async function createBuiltinAgents(
     mergedCategories,
     directory,
     useTaskSystem,
+    disableOmoEnv,
   })
   if (hephaestusConfig) {
     result["hephaestus"] = hephaestusConfig

src/agents/builtin-agents/environment-context.ts

@@ -1,8 +1,16 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
 import { createEnvContext } from "../env-context"
 
-export function applyEnvironmentContext(config: AgentConfig, directory?: string): AgentConfig {
-  if (!directory || !config.prompt) return config
+type ApplyEnvironmentContextOptions = {
+  disableOmoEnv?: boolean
+}
+
+export function applyEnvironmentContext(
+  config: AgentConfig,
+  directory?: string,
+  options: ApplyEnvironmentContextOptions = {}
+): AgentConfig {
+  if (options.disableOmoEnv || !directory || !config.prompt) return config
   const envContext = createEnvContext()
   return { ...config, prompt: config.prompt + envContext }
 }

src/agents/builtin-agents/general-agents.ts

@@ -23,6 +23,7 @@ export function collectPendingBuiltinAgents(input: {
   availableModels: Set<string>
   disabledSkills?: Set<string>
   useTaskSystem?: boolean
+  disableOmoEnv?: boolean
 }): { pendingAgentConfigs: Map<string, AgentConfig>; availableAgents: AvailableAgent[] } {
   const {
     agentSources,
@@ -37,6 +38,7 @@ export function collectPendingBuiltinAgents(input: {
     uiSelectedModel,
     availableModels,
     disabledSkills,
+    disableOmoEnv = false,
   } = input
 
   const availableAgents: AvailableAgent[] = []
@@ -81,7 +83,7 @@ export function collectPendingBuiltinAgents(input: {
     }
 
     if (agentName === "librarian") {
-      config = applyEnvironmentContext(config, directory)
+      config = applyEnvironmentContext(config, directory, { disableOmoEnv })
     }
 
     config = applyOverrides(config, override, mergedCategories, directory)

src/agents/builtin-agents/hephaestus-agent.ts

@@ -4,7 +4,7 @@ import type { CategoryConfig } from "../../config/schema"
 import type { AvailableAgent, AvailableCategory, AvailableSkill } from "../dynamic-agent-prompt-builder"
 import { AGENT_MODEL_REQUIREMENTS, isAnyProviderConnected } from "../../shared"
 import { createHephaestusAgent } from "../hephaestus"
-import { createEnvContext } from "../env-context"
+import { applyEnvironmentContext } from "./environment-context"
 import { applyCategoryOverride, mergeAgentConfig } from "./agent-overrides"
 import { applyModelResolution, getFirstFallbackModel } from "./model-resolution"
 
@@ -20,6 +20,7 @@ export function maybeCreateHephaestusConfig(input: {
   mergedCategories: Record<string, CategoryConfig>
   directory?: string
   useTaskSystem: boolean
+  disableOmoEnv?: boolean
 }): AgentConfig | undefined {
   const {
     disabledAgents,
@@ -33,6 +34,7 @@ export function maybeCreateHephaestusConfig(input: {
     mergedCategories,
     directory,
     useTaskSystem,
+    disableOmoEnv = false,
   } = input
 
   if (disabledAgents.includes("hephaestus")) return undefined
@@ -79,10 +81,7 @@ export function maybeCreateHephaestusConfig(input: {
     hephaestusConfig = applyCategoryOverride(hephaestusConfig, hepOverrideCategory, mergedCategories)
   }
 
-  if (directory && hephaestusConfig.prompt) {
-    const envContext = createEnvContext()
-    hephaestusConfig = { ...hephaestusConfig, prompt: hephaestusConfig.prompt + envContext }
-  }
+  hephaestusConfig = applyEnvironmentContext(hephaestusConfig, directory, { disableOmoEnv })
 
   if (hephaestusOverride) {
     hephaestusConfig = mergeAgentConfig(hephaestusConfig, hephaestusOverride, directory)

src/agents/builtin-agents/sisyphus-agent.ts

@@ -22,6 +22,7 @@ export function maybeCreateSisyphusConfig(input: {
   directory?: string
   userCategories?: CategoriesConfig
   useTaskSystem: boolean
+  disableOmoEnv?: boolean
 }): AgentConfig | undefined {
   const {
     disabledAgents,
@@ -36,6 +37,7 @@ export function maybeCreateSisyphusConfig(input: {
     mergedCategories,
     directory,
     useTaskSystem,
+    disableOmoEnv = false,
   } = input
 
   const sisyphusOverride = agentOverrides["sisyphus"]
@@ -78,7 +80,9 @@ export function maybeCreateSisyphusConfig(input: {
   }
 
   sisyphusConfig = applyOverrides(sisyphusConfig, sisyphusOverride, mergedCategories, directory)
-  sisyphusConfig = applyEnvironmentContext(sisyphusConfig, directory)
+  sisyphusConfig = applyEnvironmentContext(sisyphusConfig, directory, {
+    disableOmoEnv,
+  })
 
   return sisyphusConfig
 }

src/agents/utils.test.ts

@@ -662,6 +662,178 @@ describe("createBuiltinAgents with requiresProvider gating (hephaestus)", () =>
   })
 })
 
+describe("Hephaestus environment context toggle", () => {
+  let fetchSpy: ReturnType<typeof spyOn>
+
+  beforeEach(() => {
+    fetchSpy = spyOn(shared, "fetchAvailableModels").mockResolvedValue(
+      new Set(["openai/gpt-5.3-codex"])
+    )
+  })
+
+  afterEach(() => {
+    fetchSpy.mockRestore()
+  })
+
+  async function buildAgents(disableFlag?: boolean) {
+    return createBuiltinAgents(
+      [],
+      {},
+      "/tmp/work",
+      TEST_DEFAULT_MODEL,
+      undefined,
+      undefined,
+      [],
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      disableFlag
+    )
+  }
+
+  test("includes <omo-env> tag when disable flag is unset", async () => {
+    // #when
+    const agents = await buildAgents(undefined)
+
+    // #then
+    expect(agents.hephaestus).toBeDefined()
+    expect(agents.hephaestus.prompt).toContain("<omo-env>")
+  })
+
+  test("includes <omo-env> tag when disable flag is false", async () => {
+    // #when
+    const agents = await buildAgents(false)
+
+    // #then
+    expect(agents.hephaestus).toBeDefined()
+    expect(agents.hephaestus.prompt).toContain("<omo-env>")
+  })
+
+  test("omits <omo-env> tag when disable flag is true", async () => {
+    // #when
+    const agents = await buildAgents(true)
+
+    // #then
+    expect(agents.hephaestus).toBeDefined()
+    expect(agents.hephaestus.prompt).not.toContain("<omo-env>")
+  })
+})
+
+describe("Sisyphus and Librarian environment context toggle", () => {
+  let fetchSpy: ReturnType<typeof spyOn>
+
+  beforeEach(() => {
+    fetchSpy = spyOn(shared, "fetchAvailableModels").mockResolvedValue(
+      new Set(["anthropic/claude-opus-4-6", "google/gemini-3-flash"])
+    )
+  })
+
+  afterEach(() => {
+    fetchSpy.mockRestore()
+  })
+
+  async function buildAgents(disableFlag?: boolean) {
+    return createBuiltinAgents(
+      [],
+      {},
+      "/tmp/work",
+      TEST_DEFAULT_MODEL,
+      undefined,
+      undefined,
+      [],
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      disableFlag
+    )
+  }
+
+  test("includes <omo-env> for sisyphus and librarian when disable flag is unset", async () => {
+    const agents = await buildAgents(undefined)
+
+    expect(agents.sisyphus).toBeDefined()
+    expect(agents.librarian).toBeDefined()
+    expect(agents.sisyphus.prompt).toContain("<omo-env>")
+    expect(agents.librarian.prompt).toContain("<omo-env>")
+  })
+
+  test("includes <omo-env> for sisyphus and librarian when disable flag is false", async () => {
+    const agents = await buildAgents(false)
+
+    expect(agents.sisyphus).toBeDefined()
+    expect(agents.librarian).toBeDefined()
+    expect(agents.sisyphus.prompt).toContain("<omo-env>")
+    expect(agents.librarian.prompt).toContain("<omo-env>")
+  })
+
+  test("omits <omo-env> for sisyphus and librarian when disable flag is true", async () => {
+    const agents = await buildAgents(true)
+
+    expect(agents.sisyphus).toBeDefined()
+    expect(agents.librarian).toBeDefined()
+    expect(agents.sisyphus.prompt).not.toContain("<omo-env>")
+    expect(agents.librarian.prompt).not.toContain("<omo-env>")
+  })
+})
+
+describe("Atlas is unaffected by environment context toggle", () => {
+  let fetchSpy: ReturnType<typeof spyOn>
+
+  beforeEach(() => {
+    fetchSpy = spyOn(shared, "fetchAvailableModels").mockResolvedValue(
+      new Set(["anthropic/claude-opus-4-6", "openai/gpt-5.2"])
+    )
+  })
+
+  afterEach(() => {
+    fetchSpy.mockRestore()
+  })
+
+  test("atlas prompt is unchanged and never contains <omo-env>", async () => {
+    const agentsDefault = await createBuiltinAgents(
+      [],
+      {},
+      "/tmp/work",
+      TEST_DEFAULT_MODEL,
+      undefined,
+      undefined,
+      [],
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      false
+    )
+
+    const agentsDisabled = await createBuiltinAgents(
+      [],
+      {},
+      "/tmp/work",
+      TEST_DEFAULT_MODEL,
+      undefined,
+      undefined,
+      [],
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      true
+    )
+
+    expect(agentsDefault.atlas).toBeDefined()
+    expect(agentsDisabled.atlas).toBeDefined()
+    expect(agentsDefault.atlas.prompt).not.toContain("<omo-env>")
+    expect(agentsDisabled.atlas.prompt).not.toContain("<omo-env>")
+    expect(agentsDisabled.atlas.prompt).toBe(agentsDefault.atlas.prompt)
+  })
+})
+
 describe("createBuiltinAgents with requiresAnyModel gating (sisyphus)", () => {
   test("sisyphus is created when at least one fallback model is available", async () => {
     // #given