feat(core): discover AGENTS.md up to the home directory

packages/app/src/components/prompt-input/submit.ts

@@ -76,27 +76,6 @@ export async function sendFollowupDraft(input: FollowupSendInput) {
     return true
   }
 
-  const select = async () => {
-    const session = input.session()
-    if (session?.agent !== input.draft.agent) {
-      await input.api.switchAgent({ sessionID: input.draft.sessionID, agent: input.draft.agent })
-    }
-    if (
-      session?.model?.providerID === input.draft.model.providerID &&
-      session.model.id === input.draft.model.modelID &&
-      (session.model.variant ?? "default") === (input.draft.variant ?? "default")
-    )
-      return
-    await input.api.switchModel({
-      sessionID: input.draft.sessionID,
-      model: {
-        id: input.draft.model.modelID,
-        providerID: input.draft.model.providerID,
-        variant: input.draft.variant,
-      },
-    })
-  }
-
   const [head, ...tail] = text.split(" ")
   const cmd = head?.startsWith("/") ? head.slice(1) : undefined
   if (cmd && input.sync.data.command.find((item) => item.name === cmd)) {
@@ -107,13 +86,18 @@ export async function sendFollowupDraft(input: FollowupSendInput) {
         return false
       }
 
-      await select()
       const messageID = Identifier.ascending("message")
       await input.api.command({
         sessionID: input.draft.sessionID,
         id: messageID,
         command: cmd,
         arguments: tail.join(" "),
+        agent: input.draft.agent,
+        model: {
+          id: input.draft.model.modelID,
+          providerID: input.draft.model.providerID,
+          variant: input.draft.variant,
+        },
         files: await Promise.all(
           images.map(async (attachment) => ({
             uri: await blobDataUrl(attachment.blob, attachment.mime),
@@ -183,7 +167,24 @@ export async function sendFollowupDraft(input: FollowupSendInput) {
       return false
     }
 
-    await select()
+    const session = input.session()
+    if (session?.agent !== input.draft.agent) {
+      await input.api.switchAgent({ sessionID: input.draft.sessionID, agent: input.draft.agent })
+    }
+    if (
+      session?.model?.providerID !== input.draft.model.providerID ||
+      session.model.id !== input.draft.model.modelID ||
+      (session.model.variant ?? "default") !== (input.draft.variant ?? "default")
+    ) {
+      await input.api.switchModel({
+        sessionID: input.draft.sessionID,
+        model: {
+          id: input.draft.model.modelID,
+          providerID: input.draft.model.providerID,
+          variant: input.draft.variant,
+        },
+      })
+    }
 
     await input.api.prompt({
       sessionID: input.draft.sessionID,
@@ -523,22 +524,14 @@ export function createPromptSubmit(input: PromptSubmitInput) {
         clearInput()
         const messageID = Identifier.ascending("message")
         serverSync().session.set("session_status", session.id, { type: "busy" })
-        void (async () => {
-          if (session.agent !== agent) await sdk().api.session.switchAgent({ sessionID: session.id, agent })
-          if (
-            session.model?.providerID !== model.providerID ||
-            session.model.id !== model.modelID ||
-            (session.model.variant ?? "default") !== (variant ?? "default")
-          )
-            await sdk().api.session.switchModel({
-              sessionID: session.id,
-              model: { id: model.modelID, providerID: model.providerID, variant },
-            })
-          await sdk().api.session.command({
+        sdk()
+          .api.session.command({
             sessionID: session.id,
             id: messageID,
             command: commandName,
             arguments: args.join(" "),
+            agent,
+            model: { id: model.modelID, providerID: model.providerID, variant },
             files: await Promise.all(
               images.map(async (attachment) => ({
                 uri: await blobDataUrl(attachment.blob, attachment.mime),
@@ -546,14 +539,14 @@ export function createPromptSubmit(input: PromptSubmitInput) {
               })),
             ),
           })
-        })().catch((err) => {
-          serverSync().session.set("session_status", session.id, { type: "idle" })
-          showToast({
-            title: language.t("prompt.toast.commandSendFailed.title"),
-            description: formatServerError(err, language.t, language.t("common.requestFailed")),
+          .catch((err) => {
+            serverSync().session.set("session_status", session.id, { type: "idle" })
+            showToast({
+              title: language.t("prompt.toast.commandSendFailed.title"),
+              description: formatServerError(err, language.t, language.t("common.requestFailed")),
+            })
+            restoreInput()
           })
-          restoreInput()
-        })
         return
       }
     }

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

@@ -193,6 +193,8 @@ export type Endpoint5_13Input = {
   readonly id?: SessionMessage.ID | undefined
   readonly command: string
   readonly arguments?: string | undefined
+  readonly agent?: Agent.ID | undefined
+  readonly model?: Model.Ref | undefined
   readonly files?: ReadonlyArray<PromptInput.FileAttachment> | undefined
   readonly agents?: ReadonlyArray<AgentAttachment> | undefined
   readonly skills?: ReadonlyArray<PromptInput.SkillAttachment> | undefined

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

@@ -431,6 +431,8 @@ const Endpoint5_13 = (raw: RawClient["server.session"]) => (input: Endpoint5_13I
         id: input["id"],
         command: input["command"],
         arguments: input["arguments"],
+        agent: input["agent"],
+        model: input["model"],
         files: input["files"],
         agents: input["agents"],
         skills: input["skills"],

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

@@ -635,6 +635,8 @@ export function make(options: ClientOptions) {
               id: input["id"],
               command: input["command"],
               arguments: input["arguments"],
+              agent: input["agent"],
+              model: input["model"],
               files: input["files"],
               agents: input["agents"],
               skills: input["skills"],

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

@@ -3485,6 +3485,8 @@ export type SessionCommandInput = {
     readonly id?: string | null
     readonly command: string
     readonly arguments?: string | null
+    readonly agent?: string | null
+    readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string } | null
     readonly files?: ReadonlyArray<{
       readonly uri: string
       readonly name?: string
@@ -3506,6 +3508,8 @@ export type SessionCommandInput = {
     readonly id?: string | null
     readonly command: string
     readonly arguments?: string | null
+    readonly agent?: string | null
+    readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string } | null
     readonly files?: ReadonlyArray<{
       readonly uri: string
       readonly name?: string
@@ -3527,6 +3531,8 @@ export type SessionCommandInput = {
     readonly id?: string | null
     readonly command: string
     readonly arguments?: string | null
+    readonly agent?: string | null
+    readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string } | null
     readonly files?: ReadonlyArray<{
       readonly uri: string
       readonly name?: string
@@ -3544,10 +3550,58 @@ export type SessionCommandInput = {
     readonly delivery?: "steer" | "queue" | null
     readonly resume?: boolean | null
   }["arguments"]
+  readonly agent?: {
+    readonly id?: string | null
+    readonly command: string
+    readonly arguments?: string | null
+    readonly agent?: string | null
+    readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string } | null
+    readonly files?: ReadonlyArray<{
+      readonly uri: string
+      readonly name?: string
+      readonly description?: string
+      readonly mention?: { readonly start: number; readonly end: number; readonly text: string }
+    }>
+    readonly agents?: ReadonlyArray<{
+      readonly name: string
+      readonly mention?: { readonly start: number; readonly end: number; readonly text: string }
+    }>
+    readonly skills?: ReadonlyArray<{
+      readonly id: string
+      readonly mention?: { readonly start: number; readonly end: number; readonly text: string }
+    }>
+    readonly delivery?: "steer" | "queue" | null
+    readonly resume?: boolean | null
+  }["agent"]
+  readonly model?: {
+    readonly id?: string | null
+    readonly command: string
+    readonly arguments?: string | null
+    readonly agent?: string | null
+    readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string } | null
+    readonly files?: ReadonlyArray<{
+      readonly uri: string
+      readonly name?: string
+      readonly description?: string
+      readonly mention?: { readonly start: number; readonly end: number; readonly text: string }
+    }>
+    readonly agents?: ReadonlyArray<{
+      readonly name: string
+      readonly mention?: { readonly start: number; readonly end: number; readonly text: string }
+    }>
+    readonly skills?: ReadonlyArray<{
+      readonly id: string
+      readonly mention?: { readonly start: number; readonly end: number; readonly text: string }
+    }>
+    readonly delivery?: "steer" | "queue" | null
+    readonly resume?: boolean | null
+  }["model"]
   readonly files?: {
     readonly id?: string | null
     readonly command: string
     readonly arguments?: string | null
+    readonly agent?: string | null
+    readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string } | null
     readonly files?: ReadonlyArray<{
       readonly uri: string
       readonly name?: string
@@ -3569,6 +3623,8 @@ export type SessionCommandInput = {
     readonly id?: string | null
     readonly command: string
     readonly arguments?: string | null
+    readonly agent?: string | null
+    readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string } | null
     readonly files?: ReadonlyArray<{
       readonly uri: string
       readonly name?: string
@@ -3590,6 +3646,8 @@ export type SessionCommandInput = {
     readonly id?: string | null
     readonly command: string
     readonly arguments?: string | null
+    readonly agent?: string | null
+    readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string } | null
     readonly files?: ReadonlyArray<{
       readonly uri: string
       readonly name?: string
@@ -3611,6 +3669,8 @@ export type SessionCommandInput = {
     readonly id?: string | null
     readonly command: string
     readonly arguments?: string | null
+    readonly agent?: string | null
+    readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string } | null
     readonly files?: ReadonlyArray<{
       readonly uri: string
       readonly name?: string
@@ -3632,6 +3692,8 @@ export type SessionCommandInput = {
     readonly id?: string | null
     readonly command: string
     readonly arguments?: string | null
+    readonly agent?: string | null
+    readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string } | null
     readonly files?: ReadonlyArray<{
       readonly uri: string
       readonly name?: string

packages/core/src/config/plugin/instruction.ts

@@ -27,8 +27,10 @@ export const Plugin = define({
       const changes = yield* PubSub.sliding<string>(1)
       const lock = Semaphore.makeUnsafe(1)
       const start = yield* fs.resolve(location.directory)
-      const stop = yield* fs.resolve(location.project.directory)
-      const project = discovery.project && FSUtil.contains(stop, start)
+      const root = yield* fs.resolve(location.project.directory)
+      const home = yield* fs.resolve(global.home)
+      const project = discovery.project && FSUtil.contains(root, start)
+      const stop = FSUtil.contains(home, start) ? home : root
       const globalFile = yield* fs.resolve(join(global.config, "AGENTS.md"))
       const loaded: { current: Loaded } = { current: { type: "available", files: [] } }
 

packages/core/src/models-dev.ts

@@ -1,8 +1,11 @@
-import { Context, Duration, Effect, Layer, Option, Schedule, Schema, Semaphore } from "effect"
+import path from "path"
+import { Context, Duration, Effect, Layer, Option, Schedule, Schema } from "effect"
 import { HttpClient, HttpClientRequest } from "effect/unstable/http"
 import { ModelsDev } from "@opencode-ai/schema/models-dev"
 import { Money } from "@opencode-ai/schema/money"
 import { App } from "./app"
+import { Global } from "@opencode-ai/util/global"
+import { Flock } from "@opencode-ai/util/flock"
 import { Hash } from "@opencode-ai/util/hash"
 import { FSUtil } from "@opencode-ai/util/fs-util"
 import { Bus } from "./bus"
@@ -10,7 +13,6 @@ import { makeGlobalNode } from "@opencode-ai/util/effect/app-node"
 import { httpClient } from "@opencode-ai/util/effect/app-node-platform"
 import { Model } from "./model"
 import { Provider } from "./provider"
-import { KV } from "./kv"
 
 export const CatalogModelStatus = Schema.Literals(["alpha", "beta", "deprecated"])
 export type CatalogModelStatus = typeof CatalogModelStatus.Type
@@ -535,18 +537,6 @@ export type Options = typeof Options.Type
 
 export class Service extends Context.Service<Service, Interface>()("@opencode/ModelsDev") {}
 
-const CatalogJson = Schema.fromJsonString(Schema.Record(Schema.String, Schema.Unknown))
-const Cache = Schema.Struct({
-  updatedAt: Schema.Number,
-  body: CatalogJson,
-})
-const defaultSource = "https://models.opencode.ai"
-
-function cacheKey(source: string) {
-  if (source === defaultSource) return "models-dev:catalog"
-  return `models-dev:catalog:${Hash.fast(source)}`
-}
-
 export const layer = (options?: Options) =>
   Layer.effect(
     Service,
@@ -554,7 +544,7 @@ export const layer = (options?: Options) =>
       const fs = yield* FSUtil.Service
       const bus = yield* Bus.Service
       const app = yield* App.Metadata
-      const kv = yield* KV.Service
+      const global = yield* Global.Service
       const http = HttpClient.filterStatusOk(
         (yield* HttpClient.HttpClient).pipe(
           HttpClient.retryTransient({
@@ -565,28 +555,21 @@ export const layer = (options?: Options) =>
         ),
       )
 
-      const source = options?.url || defaultSource
+      const source = options?.url || "https://models.opencode.ai"
       const fetch = options?.fetch ?? true
       const userAgent = App.useragent(app)
-      const key = cacheKey(source)
+      const filepath = path.join(
+        global.cache,
+        source === "https://models.opencode.ai" ? "models.json" : `models-${Hash.fast(source)}.json`,
+      )
       const ttl = Duration.minutes(5)
-      const lock = Semaphore.makeUnsafe(1)
-
-      const loadFromCache = Effect.fnUntraced(function* () {
-        const value = yield* kv.get(key)
-        const cached = Schema.decodeUnknownOption(Cache)(value)
-        if (Option.isSome(cached))
-          return {
-            catalog: cached.value.body as Record<string, SourceProvider>,
-            updatedAt: cached.value.updatedAt,
-          }
-        if (value !== undefined) yield* kv.remove(key)
-      })
+      const lockKey = `models-dev:${filepath}`
 
       const fresh = Effect.fnUntraced(function* () {
-        const cached = yield* loadFromCache()
-        if (!cached) return false
-        return Date.now() - cached.updatedAt < Duration.toMillis(ttl)
+        const stat = yield* fs.stat(filepath).pipe(Effect.catch(() => Effect.succeed(undefined)))
+        if (!stat) return false
+        const mtime = Option.getOrElse(stat.mtime, () => new Date(0)).getTime()
+        return Date.now() - mtime < Duration.toMillis(ttl)
       })
 
       const fetchApi = Effect.fn("ModelsDev.fetchApi")(function* () {
@@ -598,12 +581,15 @@ export const layer = (options?: Options) =>
         )
       })
 
-      const loadFromFile = options?.file
-        ? fs.readJson(options.file).pipe(
-            Effect.map((input) => input as Record<string, SourceProvider>),
-            Effect.catch(() => Effect.succeed(undefined)),
-          )
-        : Effect.succeed(undefined)
+      const loadFromDisk = fs.readJson(options?.file ?? filepath).pipe(
+        Effect.map((input) => input as Record<string, SourceProvider>),
+        Effect.catch((error) => {
+          if (options?.file === undefined && error._tag === "FileSystemError" && error.method === "readJson") {
+            return fs.remove(filepath, { force: true }).pipe(Effect.ignore, Effect.as(undefined))
+          }
+          return Effect.succeed(undefined)
+        }),
+      )
 
       const loadSnapshot = Effect.sync(() =>
         typeof OPENCODE_MODELS_DEV === "undefined" ? undefined : OPENCODE_MODELS_DEV,
@@ -611,27 +597,33 @@ export const layer = (options?: Options) =>
 
       const fetchAndWrite = Effect.fn("ModelsDev.fetchAndWrite")(function* () {
         const text = yield* fetchApi()
-        const catalog = (yield* Schema.decodeUnknownEffect(CatalogJson)(text)) as Record<string, SourceProvider>
-        yield* kv.set(key, { updatedAt: Date.now(), body: text })
-        return catalog
+        const tempfile = `${filepath}.${process.pid}.${Date.now()}.tmp`
+        yield* fs.writeWithDirs(tempfile, text).pipe(
+          Effect.andThen(fs.rename(tempfile, filepath)),
+          Effect.catch((error) =>
+            Effect.gen(function* () {
+              yield* fs.remove(tempfile, { force: true }).pipe(Effect.ignore)
+              return yield* Effect.fail(error)
+            }),
+          ),
+        )
+        return text
       })
 
       const populate = Effect.gen(function* () {
-        const fromFile = yield* loadFromFile
-        if (fromFile) return normalize(fromFile)
-        const cached = options?.file ? undefined : yield* loadFromCache()
-        if (cached) return normalize(cached.catalog)
+        const fromDisk = yield* loadFromDisk
+        if (fromDisk) return normalize(fromDisk)
         const bundled = yield* loadSnapshot
         if (bundled) return normalize(bundled)
         if (!fetch) return []
-        const catalog = yield* lock.withPermit(
+        // Flock is cross-process: concurrent opencode CLIs can race on this cache file.
+        const text = yield* Effect.scoped(
           Effect.gen(function* () {
-            const stored = options?.file ? undefined : yield* loadFromCache()
-            if (stored) return stored.catalog
+            yield* Flock.effect(lockKey)
             return yield* fetchAndWrite()
           }),
         )
-        return normalize(catalog)
+        return normalize(JSON.parse(text) as Record<string, SourceProvider>)
       }).pipe(Effect.withSpan("ModelsDev.populate"), Effect.orDie)
 
       const [cachedGet, invalidate] = yield* Effect.cachedInvalidateWithTTL(populate, Duration.infinity)
@@ -639,19 +631,21 @@ export const layer = (options?: Options) =>
       const get = (): Effect.Effect<readonly Snapshot[]> => cachedGet
 
       const refresh = Effect.fn("ModelsDev.refresh")(function* (force = false) {
-        yield* lock
-          .withPermit(
-            Effect.gen(function* () {
-              if (!force && (yield* fresh())) return
-              yield* fetchAndWrite()
-              yield* invalidate
-              yield* bus.publish(ModelsDev.Event.Refreshed, {})
-            }),
-          )
-          .pipe(
-            Effect.tapCause((cause) => Effect.logError("Failed to fetch models.dev", { cause: cause })),
-            Effect.ignore,
-          )
+        if (!force && (yield* fresh())) return
+        yield* Effect.scoped(
+          Effect.gen(function* () {
+            yield* Flock.effect(lockKey)
+            // Re-check under the lock: another process may have refreshed between
+            // our outer check and lock acquisition.
+            if (!force && (yield* fresh())) return
+            yield* fetchAndWrite()
+            yield* invalidate
+            yield* bus.publish(ModelsDev.Event.Refreshed, {})
+          }),
+        ).pipe(
+          Effect.tapCause((cause) => Effect.logError("Failed to fetch models.dev", { cause: cause })),
+          Effect.ignore,
+        )
       })
 
       if (fetch && !process.argv.includes("--get-yargs-completions")) {
@@ -667,7 +661,7 @@ export function configured(options?: Options) {
   return makeGlobalNode({
     service: Service,
     layer: layer(options),
-    deps: [FSUtil.node, Bus.node, App.node, KV.node, httpClient],
+    deps: [FSUtil.node, Bus.node, App.node, Global.node, httpClient],
   })
 }
 

packages/core/src/plugin/promise.ts

@@ -310,6 +310,8 @@ export function fromPromise(plugin: Plugin) {
                   ...input,
                   sessionID: Session.ID.make(input.sessionID),
                   id: input.id == null ? undefined : SessionMessage.ID.make(input.id),
+                  agent: input.agent == null ? undefined : Agent.ID.make(input.agent),
+                  model: input.model == null ? undefined : model(input.model),
                   skills: input.skills?.map((skill) => ({ ...skill, id: Skill.ID.make(skill.id) })),
                   arguments: input.arguments ?? undefined,
                   delivery: input.delivery ?? undefined,

packages/core/src/session.ts

@@ -233,6 +233,8 @@ export interface Interface {
     sessionID: SessionSchema.ID
     command: string
     arguments?: string
+    agent?: Agent.ID
+    model?: Model.Ref
     files?: PromptInput.Prompt["files"]
     agents?: PromptInput.Prompt["agents"]
     skills?: PromptInput.Prompt["skills"]
@@ -623,13 +625,13 @@ const layer = Layer.effect(
         const evaluated = yield* commands.evaluate({ name: input.command, arguments: input.arguments })
 
         // TODO(v2 commands): decide whether command-level subtask/background execution belongs in v2 commands.
-        const agent = command.agent
+        const agent = command.agent ?? input.agent
         const commandAgent = yield* Effect.gen(function* () {
           if (!command.agent) return undefined
           const agents = yield* Agent.Service.pipe(Effect.provide(locations.get(session.location)))
           return yield* agents.get(Agent.ID.make(command.agent))
         })
-        const model = command.model ?? commandAgent?.model
+        const model = command.model ?? commandAgent?.model ?? input.model
         if (agent !== undefined && session.agent !== Agent.ID.make(agent))
           yield* result.switchAgent({ sessionID: input.sessionID, agent: Agent.ID.make(agent) })
         if (model !== undefined) yield* result.switchModel({ sessionID: input.sessionID, model })

packages/core/test/instruction-discovery.test.ts

@@ -24,6 +24,7 @@ const it = testEffect(Layer.empty)
 
 const instructionLayer = (input: {
   config?: string
+  home?: string
   locationServiceLayer: Layer.Layer<Location.Service>
   filesystemLayer?: Layer.Layer<FSUtil.Service>
   project?: boolean
@@ -34,7 +35,15 @@ const instructionLayer = (input: {
       LayerNode.group([InstructionDiscovery.node, Bus.node, FSUtil.node, Global.node, Location.node, Watcher.node]),
       [
         [InstructionDiscovery.node, InstructionDiscovery.configured({ project: input.project })],
-        [Global.node, input.config ? Global.layerWith({ config: input.config }) : tempGlobalLayer],
+        [
+          Global.node,
+          input.config || input.home
+            ? Global.layerWith({
+                ...(input.config ? { config: input.config } : {}),
+                ...(input.home ? { home: input.home } : {}),
+              })
+            : tempGlobalLayer,
+        ],
         [Location.node, input.locationServiceLayer],
         [Watcher.node, watcher],
         ...(input.filesystemLayer ? [[FSUtil.node, input.filesystemLayer] as const] : []),
@@ -112,10 +121,13 @@ describe("ConfigInstructionPlugin.Plugin", () => {
     ).pipe(
       Effect.flatMap((tmp) => {
         const global = path.join(tmp.path, "global")
-        const project = path.join(tmp.path, "project")
+        const home = path.join(tmp.path, "home")
+        const shared = path.join(home, "code")
+        const project = path.join(shared, "repo")
         const directory = path.join(project, "packages", "core")
         const outside = path.join(tmp.path, "AGENTS.md")
         const globalFile = path.join(global, "AGENTS.md")
+        const sharedFile = path.join(shared, "AGENTS.md")
         const projectFile = path.join(project, "AGENTS.md")
         const packageFile = path.join(directory, "AGENTS.md")
         return Effect.gen(function* () {
@@ -124,6 +136,7 @@ describe("ConfigInstructionPlugin.Plugin", () => {
             await fs.mkdir(directory, { recursive: true })
             await fs.writeFile(outside, "outside")
             await fs.writeFile(globalFile, "global")
+            await fs.writeFile(sharedFile, "shared")
             await fs.writeFile(projectFile, "project")
             await fs.writeFile(packageFile, "package")
           })
@@ -135,13 +148,20 @@ describe("ConfigInstructionPlugin.Plugin", () => {
             { path: packageFile, type: "file" },
             { path: path.join(project, "packages", "AGENTS.md"), type: "file" },
             { path: projectFile, type: "file" },
+            { path: sharedFile, type: "file" },
+            { path: path.join(home, "AGENTS.md"), type: "file" },
           ])
+          expect(yield* watcher.subscriptions()).not.toContainEqual({
+            path: path.join(tmp.path, "AGENTS.md"),
+            type: "file",
+          })
           const initialized = yield* readInitial(yield* discovery.load())
           expect(initialized.text).toBe(
             [
               `Instructions from: ${globalFile}\nglobal`,
               `Instructions from: ${packageFile}\npackage`,
               `Instructions from: ${projectFile}\nproject`,
+              `Instructions from: ${sharedFile}\nshared`,
             ].join("\n\n"),
           )
           expect(initialized.text).not.toContain("outside")
@@ -159,6 +179,7 @@ describe("ConfigInstructionPlugin.Plugin", () => {
               "These instructions replace all previously loaded ambient instructions.",
               `Instructions from: ${globalFile}\nglobal`,
               `Instructions from: ${projectFile}\nproject`,
+              `Instructions from: ${sharedFile}\nshared`,
             ].join("\n\n"),
           )
 
@@ -166,6 +187,8 @@ describe("ConfigInstructionPlugin.Plugin", () => {
           yield* emitAndWait({ type: "delete", path: globalFile })
           yield* Effect.promise(() => fs.rm(projectFile))
           yield* emitAndWait({ type: "delete", path: projectFile })
+          yield* Effect.promise(() => fs.rm(sharedFile))
+          yield* emitAndWait({ type: "delete", path: sharedFile })
           expect((yield* readUpdate(yield* discovery.load(), initialized)).text).toBe(
             "Previously loaded instructions no longer apply.",
           )
@@ -173,6 +196,7 @@ describe("ConfigInstructionPlugin.Plugin", () => {
           Effect.provide(
             instructionLayer({
               config: global,
+              home,
               locationServiceLayer: Layer.succeed(
                 Location.Service,
                 Location.Service.of(
@@ -215,15 +239,17 @@ describe("ConfigInstructionPlugin.Plugin", () => {
     ),
   )
 
-  it.live("discovers a newly created instruction file in an intermediate directory", () =>
+  it.live("discovers a newly created instruction file above the project root", () =>
     Effect.acquireRelease(
       Effect.promise(() => tmpdir()),
       (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
     ).pipe(
       Effect.flatMap((tmp) => {
-        const project = path.join(tmp.path, "project")
-        const intermediate = path.join(project, "packages", "AGENTS.md")
-        const directory = path.join(project, "packages", "core")
+        const home = path.join(tmp.path, "home")
+        const shared = path.join(home, "code")
+        const project = path.join(shared, "repo")
+        const intermediate = path.join(shared, "AGENTS.md")
+        const directory = path.join(project, "core")
         const projectFile = path.join(project, "AGENTS.md")
         return Effect.gen(function* () {
           yield* Effect.promise(() => fs.mkdir(directory, { recursive: true }))
@@ -235,7 +261,7 @@ describe("ConfigInstructionPlugin.Plugin", () => {
           yield* emitAndWait({ type: "create", path: intermediate })
 
           expect((yield* readInitial(yield* discovery.load())).text).toBe(
-            [`Instructions from: ${intermediate}\nintermediate`, `Instructions from: ${projectFile}\nproject`].join(
+            [`Instructions from: ${projectFile}\nproject`, `Instructions from: ${intermediate}\nintermediate`].join(
               "\n\n",
             ),
           )
@@ -243,6 +269,48 @@ describe("ConfigInstructionPlugin.Plugin", () => {
           Effect.provide(
             instructionLayer({
               config: path.join(tmp.path, "global"),
+              home,
+              locationServiceLayer: Layer.succeed(
+                Location.Service,
+                Location.Service.of(
+                  location(
+                    { directory: AbsolutePath.make(directory) },
+                    { projectDirectory: AbsolutePath.make(project) },
+                  ),
+                ),
+              ),
+            }),
+          ),
+        )
+      }),
+    ),
+  )
+
+  it.live("stops instruction candidates at the project root outside home", () =>
+    Effect.acquireRelease(
+      Effect.promise(() => tmpdir()),
+      (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
+    ).pipe(
+      Effect.flatMap((tmp) => {
+        const global = path.join(tmp.path, "global")
+        const home = path.join(tmp.path, "home")
+        const project = path.join(tmp.path, "scratch", "repo")
+        const directory = path.join(project, "packages", "core")
+        return Effect.gen(function* () {
+          yield* Effect.promise(() => fs.mkdir(directory, { recursive: true }))
+          yield* start()
+          const watcher = yield* Watcher.Test
+          expect(yield* watcher.subscriptions()).toEqual([
+            { path: path.join(global, "AGENTS.md"), type: "file" },
+            { path: path.join(directory, "AGENTS.md"), type: "file" },
+            { path: path.join(project, "packages", "AGENTS.md"), type: "file" },
+            { path: path.join(project, "AGENTS.md"), type: "file" },
+          ])
+        }).pipe(
+          Effect.provide(
+            instructionLayer({
+              config: global,
+              home,
               locationServiceLayer: Layer.succeed(
                 Location.Service,
                 Location.Service.of(

packages/core/test/models.test.ts

@@ -1,17 +1,19 @@
-import { describe, expect, test } from "bun:test"
+import { describe, expect, beforeEach, afterAll, test } from "bun:test"
 import { Money } from "@opencode-ai/schema/money"
 import { Effect, Layer, Ref } from "effect"
 import { HttpClient, HttpClientResponse } from "effect/unstable/http"
 import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
 import { LayerNodePlatform } from "@opencode-ai/util/effect/app-node-platform"
 import { LayerNode } from "@opencode-ai/util/effect/layer-node"
-import { KV } from "@opencode-ai/core/kv"
+import { Global } from "@opencode-ai/util/global"
 import { Model } from "@opencode-ai/core/model"
 import { ModelsDev } from "@opencode-ai/core/models-dev"
 import { Provider } from "@opencode-ai/core/provider"
 import { it } from "./lib/effect"
+import { readFile, rm, writeFile, utimes, mkdir } from "fs/promises"
+import path from "path"
 
-const cacheKey = "models-dev:catalog"
+const cacheFile = path.join(Global.Path.cache, "models.json")
 
 test("normalizes permissive interleaved values to compatibility", () => {
   expect(Model.compatibility("reasoning_text")).toEqual({ reasoningField: "reasoning_text" })
@@ -162,18 +164,7 @@ const makeMockClient = (state: Ref.Ref<MockState>) =>
     }),
   )
 
-interface MockCache {
-  readonly values: Map<string, KV.Value>
-}
-
-const makeMockKV = (cache: MockCache) =>
-  Layer.mock(KV.Service, {
-    get: (key) => Effect.sync(() => cache.values.get(key)),
-    set: (key, value) => Effect.sync(() => cache.values.set(key, value)).pipe(Effect.asVoid),
-    remove: (key) => Effect.sync(() => cache.values.delete(key)).pipe(Effect.asVoid),
-  })
-
-const buildLayer = (state: Ref.Ref<MockState>, cache: MockCache, options: ModelsDev.Options = { fetch: false }) =>
+const buildLayer = (state: Ref.Ref<MockState>, options: ModelsDev.Options = { fetch: false }) =>
   // Layer.fresh is required because the ModelsDev implementation is a module-level Layer constant,
   // and Effect.provide uses a process-global MemoMap by default — without fresh,
   // every test would reuse the cachedInvalidateWithTTL state from the first run.
@@ -181,20 +172,31 @@ const buildLayer = (state: Ref.Ref<MockState>, cache: MockCache, options: Models
     AppNodeBuilder.build(ModelsDev.node, [
       [ModelsDev.node, ModelsDev.configured(options)],
       [LayerNodePlatform.httpClient, Layer.succeed(HttpClient.HttpClient, makeMockClient(state))],
-      [KV.node, makeMockKV(cache)],
     ]),
   )
 
-const makeCache = (): MockCache => ({ values: new Map() })
+const writeCacheText = (text: string, mtimeMs?: number) =>
+  Effect.promise(async () => {
+    await mkdir(Global.Path.cache, { recursive: true })
+    await writeFile(cacheFile, text)
+    if (mtimeMs !== undefined) {
+      const t = mtimeMs / 1000
+      await utimes(cacheFile, t, t)
+    }
+  })
 
-const writeCacheText = (cache: MockCache, text: string, updatedAt = Date.now()) =>
-  cache.values.set(cacheKey, { updatedAt, body: text })
+const writeCache = (data: object, mtimeMs?: number) => writeCacheText(JSON.stringify(data), mtimeMs)
 
-const writeCache = (cache: MockCache, data: object, updatedAt?: number) =>
-  writeCacheText(cache, JSON.stringify(data), updatedAt)
+const provided = <A, E>(state: Ref.Ref<MockState>, eff: Effect.Effect<A, E, ModelsDev.Service>) =>
+  eff.pipe(Effect.provide(buildLayer(state)))
 
-const provided = <A, E>(state: Ref.Ref<MockState>, cache: MockCache, eff: Effect.Effect<A, E, ModelsDev.Service>) =>
-  eff.pipe(Effect.provide(buildLayer(state, cache)))
+beforeEach(async () => {
+  await rm(cacheFile, { force: true })
+})
+
+afterAll(async () => {
+  await rm(cacheFile, { force: true })
+})
 
 const initialState: MockState = {
   body: JSON.stringify(fixture),
@@ -203,14 +205,12 @@ const initialState: MockState = {
 }
 
 describe("ModelsDev Service", () => {
-  it.live("get() returns normalized snapshots from KV when a cache entry exists", () =>
+  it.live("get() returns normalized snapshots from disk when cache file exists", () =>
     Effect.gen(function* () {
-      const cache = makeCache()
-      writeCache(cache, fixture)
+      yield* writeCache(fixture)
       const state = yield* Ref.make(initialState)
       const result = yield* provided(
         state,
-        cache,
         ModelsDev.Service.use((s) => s.get()),
       )
       expect(result).toEqual(fixtureSnapshot)
@@ -219,13 +219,11 @@ describe("ModelsDev Service", () => {
     }),
   )
 
-  it.live("get() returns empty catalog when KV is empty, fetch disabled, and no bundled snapshot is injected", () =>
+  it.live("get() returns empty catalog when disk empty, fetch disabled, and no bundled snapshot is injected", () =>
     Effect.gen(function* () {
-      const cache = makeCache()
       const state = yield* Ref.make(initialState)
       const result = yield* provided(
         state,
-        cache,
         ModelsDev.Service.use((s) => s.get()),
       )
       expect(result).toEqual([])
@@ -234,15 +232,14 @@ describe("ModelsDev Service", () => {
     }),
   )
 
-  it.live("get() recovers from a corrupted KV entry by fetching a fresh catalog", () =>
+  it.live("get() recovers from a corrupted cache file by fetching a fresh catalog", () =>
     Effect.gen(function* () {
-      const cache = makeCache()
-      writeCacheText(cache, "{")
+      yield* writeCacheText("{")
       const state = yield* Ref.make({ ...initialState, body: JSON.stringify(fixture2) })
-      const context = yield* Layer.build(buildLayer(state, cache, { fetch: true }))
+      const context = yield* Layer.build(buildLayer(state, { fetch: true }))
       const result = yield* ModelsDev.Service.use((s) => s.get()).pipe(Effect.provide(context))
       expect(result).toEqual(fixture2Snapshot)
-      expect(cache.values.get(cacheKey)).toMatchObject({ body: JSON.stringify(fixture2) })
+      expect(yield* Effect.promise(() => readFile(cacheFile, "utf8"))).toBe(JSON.stringify(fixture2))
       const final = yield* Ref.get(state)
       expect(final.calls.length).toBe(1)
     }),
@@ -250,10 +247,9 @@ describe("ModelsDev Service", () => {
 
   it.live("uses the default models URL when the configured URL is empty", () =>
     Effect.gen(function* () {
-      const cache = makeCache()
       const state = yield* Ref.make(initialState)
       yield* ModelsDev.Service.use((service) => service.get()).pipe(
-        Effect.provide(buildLayer(state, cache, { url: "", fetch: true })),
+        Effect.provide(buildLayer(state, { url: "", fetch: true })),
       )
       expect((yield* Ref.get(state)).calls[0]?.url).toBe("https://models.opencode.ai/api.json")
     }),
@@ -261,31 +257,32 @@ describe("ModelsDev Service", () => {
 
   it.live("get() is single-flight under concurrent calls", () =>
     Effect.gen(function* () {
-      const cache = makeCache()
+      yield* writeCache(fixture)
       const state = yield* Ref.make(initialState)
-      const results = yield* Effect.gen(function* () {
-        const svc = yield* ModelsDev.Service
-        return yield* Effect.all([svc.get(), svc.get(), svc.get(), svc.get(), svc.get()], {
-          concurrency: "unbounded",
-        })
-      }).pipe(Effect.provide(buildLayer(state, cache, { fetch: true })))
+      const results = yield* provided(
+        state,
+        Effect.gen(function* () {
+          const svc = yield* ModelsDev.Service
+          return yield* Effect.all([svc.get(), svc.get(), svc.get(), svc.get(), svc.get()], {
+            concurrency: "unbounded",
+          })
+        }),
+      )
       for (const result of results) expect(result).toEqual(fixtureSnapshot)
-      expect((yield* Ref.get(state)).calls.length).toBe(1)
     }),
   )
 
-  it.live("get() caches across calls (later KV writes are ignored until invalidate)", () =>
+  it.live("get() caches across calls (later disk writes are ignored until invalidate)", () =>
     Effect.gen(function* () {
-      const cache = makeCache()
-      writeCache(cache, fixture)
+      yield* writeCache(fixture)
       const state = yield* Ref.make(initialState)
       const first = yield* provided(
         state,
-        cache,
         Effect.gen(function* () {
           const svc = yield* ModelsDev.Service
           const a = yield* svc.get()
-          writeCache(cache, fixture2)
+          // mutate disk between calls — cache should mask the change
+          yield* writeCache(fixture2)
           const b = yield* svc.get()
           return { a, b }
         }),
@@ -297,12 +294,10 @@ describe("ModelsDev Service", () => {
 
   it.live("refresh(true) fetches via HttpClient and updates the cache", () =>
     Effect.gen(function* () {
-      const cache = makeCache()
-      writeCache(cache, fixture)
+      yield* writeCache(fixture)
       const state = yield* Ref.make({ ...initialState, body: JSON.stringify(fixture2) })
       const result = yield* provided(
         state,
-        cache,
         Effect.gen(function* () {
           const svc = yield* ModelsDev.Service
           const before = yield* svc.get()
@@ -313,7 +308,6 @@ describe("ModelsDev Service", () => {
       )
       expect(result.before).toEqual(fixtureSnapshot)
       expect(result.after).toEqual(fixture2Snapshot)
-      expect(cache.values.get(cacheKey)).toMatchObject({ body: JSON.stringify(fixture2) })
       const final = yield* Ref.get(state)
       expect(final.calls.length).toBe(1)
       expect(final.calls[0].url).toContain("/api.json")
@@ -321,14 +315,13 @@ describe("ModelsDev Service", () => {
     }),
   )
 
-  it.live("refresh(false) skips fetch when the KV entry is fresh", () =>
+  it.live("refresh(false) skips fetch when on-disk file is fresh", () =>
     Effect.gen(function* () {
-      const cache = makeCache()
-      writeCache(cache, fixture, Date.now() - 1000)
+      // Fresh: mtime within the 5-minute TTL.
+      yield* writeCache(fixture, Date.now() - 1000)
       const state = yield* Ref.make({ ...initialState, body: JSON.stringify(fixture2) })
       yield* provided(
         state,
-        cache,
         ModelsDev.Service.use((s) => s.refresh(false)),
       )
       const final = yield* Ref.get(state)
@@ -336,14 +329,13 @@ describe("ModelsDev Service", () => {
     }),
   )
 
-  it.live("refresh(false) fetches when the KV entry is stale", () =>
+  it.live("refresh(false) fetches when on-disk file is stale", () =>
     Effect.gen(function* () {
-      const cache = makeCache()
-      writeCache(cache, fixture, Date.now() - 10 * 60 * 1000)
+      // Stale: mtime 10 minutes ago, beyond the 5-minute TTL.
+      yield* writeCache(fixture, Date.now() - 10 * 60 * 1000)
       const state = yield* Ref.make({ ...initialState, body: JSON.stringify(fixture2) })
       const after = yield* provided(
         state,
-        cache,
         Effect.gen(function* () {
           const svc = yield* ModelsDev.Service
           yield* svc.refresh(false)
@@ -358,12 +350,10 @@ describe("ModelsDev Service", () => {
 
   it.live("refresh swallows HTTP errors and leaves cache intact", () =>
     Effect.gen(function* () {
-      const cache = makeCache()
-      writeCache(cache, fixture)
+      yield* writeCache(fixture)
       const state = yield* Ref.make({ ...initialState, status: 500, body: "boom" })
       const result = yield* provided(
         state,
-        cache,
         Effect.gen(function* () {
           const svc = yield* ModelsDev.Service
           yield* svc.refresh(true)

packages/protocol/src/groups/session.ts

@@ -341,6 +341,8 @@ export const makeSessionGroup = <I extends HttpApiMiddleware.AnyId, S>(sessionLo
           id: SessionMessage.ID.pipe(Schema.optional),
           command: Schema.String,
           arguments: Schema.String.pipe(Schema.optional),
+          agent: Agent.ID.pipe(Schema.optional),
+          model: Model.Ref.pipe(Schema.optional),
           files: PromptInput.Prompt.fields.files,
           agents: PromptInput.Prompt.fields.agents,
           skills: PromptInput.Prompt.fields.skills,

packages/server/src/handlers/session.ts

@@ -355,6 +355,8 @@ export const SessionHandler = HttpApiBuilder.group(Api, "server.session", (handl
                 id: ctx.payload.id,
                 command: ctx.payload.command,
                 arguments: ctx.payload.arguments,
+                agent: ctx.payload.agent,
+                model: ctx.payload.model,
                 files: ctx.payload.files,
                 agents: ctx.payload.agents,
                 skills: ctx.payload.skills,

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

@@ -1149,23 +1149,15 @@ export function Prompt(props: PromptProps) {
     } else if (slashHead && isCommand) {
       move.startSubmit()
       const model = { providerID: selection.providerID, id: selection.modelID, variant }
-      if (session?.agent !== agent.id) await client.api.session.switchAgent({ sessionID, agent: agent.id })
       const cancelCommit = local.model.trackSessionCommit(sessionID, model)
-      if (
-        session?.model?.providerID !== model.providerID ||
-        session.model.id !== model.id ||
-        (session.model.variant ?? "default") !== (model.variant ?? "default")
-      )
-        await client.api.session.switchModel({ sessionID, model }).catch((error) => {
-          cancelCommit()
-          throw error
-        })
 
       void client.api.session
         .command({
           sessionID,
           command: slashHead.name,
           arguments: slashHead.arguments,
+          agent: agent.id,
+          model,
           files: store.prompt.files,
           agents: store.prompt.agents,
           skills: store.prompt.skills?.length ? store.prompt.skills : undefined,

packages/tui/src/mini/stream-v2.transport.ts

@@ -1653,6 +1653,8 @@ export async function createSessionTransport(input: StreamInput): Promise<Sessio
       )
     }
 
+    const selected = await resolveSelectedModel(input, client, next)
+    if (next.variant && !selected) throw new Error("Cannot select a variant before selecting a model")
     input.trace?.write("send.command", { sessionID: input.sessionID, messageID, command: command.name, delivery })
     return client.session.command(
       {
@@ -1660,6 +1662,8 @@ export async function createSessionTransport(input: StreamInput): Promise<Sessio
         id: messageID,
         command: command.name,
         arguments: command.arguments,
+        agent: next.agent,
+        model: selected,
         files: attachments.files.length ? attachments.files : undefined,
         agents: agents.length ? agents : undefined,
         skills: skills.length ? skills : undefined,
@@ -1702,10 +1706,12 @@ export async function createSessionTransport(input: StreamInput): Promise<Sessio
       const client = sdk
       if (next.agent)
         await client.session.switchAgent({ sessionID: input.sessionID, agent: next.agent }, { signal: next.signal })
-      const selected = await resolveSelectedModel(input, client, next)
-      if (next.variant && !selected) throw new Error("Cannot select a variant before selecting a model")
-      if (selected)
-        await client.session.switchModel({ sessionID: input.sessionID, model: selected }, { signal: next.signal })
+      if (!next.prompt.command) {
+        const selected = await resolveSelectedModel(input, client, next)
+        if (next.variant && !selected) throw new Error("Cannot select a variant before selecting a model")
+        if (selected)
+          await client.session.switchModel({ sessionID: input.sessionID, model: selected }, { signal: next.signal })
+      }
       mergePending(await admitPrompt(next, client, delivery))
       settlementClient = client
     },
@@ -1744,12 +1750,6 @@ export async function createSessionTransport(input: StreamInput): Promise<Sessio
         return
       }
       if (command) {
-        if (next.agent)
-          await client.session.switchAgent({ sessionID: input.sessionID, agent: next.agent }, { signal: next.signal })
-        const selected = await resolveSelectedModel(input, client, next)
-        if (next.variant && !selected) throw new Error("Cannot select a variant before selecting a model")
-        if (selected)
-          await client.session.switchModel({ sessionID: input.sessionID, model: selected }, { signal: next.signal })
         await runTurnWait(
           next,
           messageID,

packages/tui/test/mini/stream-v2.transport.test.ts

@@ -2855,6 +2855,8 @@ describe("V2 mini transport", () => {
       id: "msg_cmd",
       command: "deploy",
       arguments: "prod",
+      agent: "build",
+      model: { providerID: "test", id: "model" },
       files: [
         { uri: "file:///tmp/context.txt", name: "context.txt" },
         {
@@ -2866,11 +2868,9 @@ describe("V2 mini transport", () => {
       skills: [{ id: "api-design", mention: { start: 13, end: 24, text: "/api-design" } }],
       delivery: "steer",
     })
-    expect(client.session.switchAgent).toHaveBeenCalledWith({ sessionID: "ses_1", agent: "build" }, expect.anything())
-    expect(client.session.switchModel).toHaveBeenCalledWith(
-      { sessionID: "ses_1", model: { providerID: "test", id: "model" } },
-      expect.anything(),
-    )
+    // Selection rides the command payload; no separate client-side switch.
+    expect(client.session.switchAgent).not.toHaveBeenCalled()
+    expect(client.session.switchModel).not.toHaveBeenCalled()
     await transport.close()
   })
 

packages/www/content/docs/(Configure)/instructions.mdx

@@ -19,8 +19,9 @@ V2 loads:
 
 1. The global file at `$XDG_CONFIG_HOME/opencode/AGENTS.md`, normally
    `~/.config/opencode/AGENTS.md`.
-2. Every `AGENTS.md` from the current Location up to and including the project
-   root.
+2. Every `AGENTS.md` from the current Location up to and including the home
+   directory when the Location is inside it. For Locations outside home, the
+   scan stops at the project root.
 
 For example, when the Location is `packages/web`, OpenCode can load all three
 project files below:
@@ -35,9 +36,9 @@ my-project/
 ```
 
 The files are combined rather than selecting a single winner. They are rendered
-in this order: global, then project files from the Location toward the project
+in this order: global, then files from the Location toward home or the project
 root. OpenCode does not resolve conflicts between their contents, so keep broad
-guidance global and put scoped guidance in the relevant project directory.
+guidance global and put scoped guidance in the relevant directory.
 
 If the Location is outside the project root, only the global file is loaded.
 Setting `OPENCODE_DISABLE_PROJECT_CONFIG=1` also skips project `AGENTS.md`

packages/www/content/docs/migrate-v1.mdx

@@ -504,8 +504,8 @@ require a V2 rewrite. See [Skills](/skills).
 
 ### Instruction files
 
-Existing `AGENTS.md` files stay in place. V2 discovers the global `~/.config/opencode/AGENTS.md` and project `AGENTS.md`
-files from the current directory up to the project root.
+Existing `AGENTS.md` files stay in place. V2 discovers the global `~/.config/opencode/AGENTS.md` and ambient `AGENTS.md`
+files from the current directory up to home. For projects outside home, discovery stops at the project root.
 
 If a V1 setup relied on a `CLAUDE.md` fallback, move that guidance into the applicable `AGENTS.md`. V2 currently only
 discovers `AGENTS.md`; because non-API V1 behavior is intended to remain compatible, also run `/report` with the affected