feat(workspace): Multi-directory workspace engine support (#215)

packages/core/src/database/migration/20260820000001_add_session_directories.ts

@@ -0,0 +1,11 @@
+import { Effect } from "effect"
+import type { DatabaseMigration } from "../migration"
+
+export default {
+ id: "20260820000001_add_session_directories",
+ up(tx) {
+ return Effect.gen(function* () {
+ yield* tx.run(`ALTER TABLE session ADD COLUMN directories TEXT;`)
+ })
+ },
+} satisfies DatabaseMigration.Migration

packages/core/src/location-mutation.ts

@@ -117,15 +117,23 @@ const layer = Layer.effect(
  }
  })
 
+ const isLexicallyInternal = (abs: string) =>
+ FSUtil.contains(location.directory, abs) ||
+ (location.directories?.some((d) => FSUtil.contains(d, abs)) ?? false)
+
  const resolve = Effect.fn("LocationMutation.resolve")(function* (input: ResolveInput) {
  const relative = !path.isAbsolute(input.path)
  const absolute = path.resolve(location.directory, input.path)
- const lexicallyInternal = FSUtil.contains(location.directory, absolute)
+ const lexicallyInternal = isLexicallyInternal(absolute)
  if (relative && !lexicallyInternal) return yield* new PathError({ path: input.path, reason: "relative_escape" })
 
  const resolved = yield* resolvePath(absolute)
  if (lexicallyInternal && !FSUtil.contains(locationRoot, resolved.canonical)) {
- return yield* new PathError({ path: input.path, reason: "location_escape" })
+ // Multi-root: also allow canonical inside any workspace directory
+ const canonicalInternal =
+ FSUtil.contains(locationRoot, resolved.canonical) ||
+ (location.directories?.some((d) => FSUtil.contains(d, resolved.canonical)) ?? false)
+ if (!canonicalInternal) return yield* new PathError({ path: input.path, reason: "location_escape" })
  }
 
  const external = !lexicallyInternal

packages/core/src/location.ts

@@ -9,6 +9,7 @@ export * as Location from "./location"
 export { Info, Ref, response }
 
 export interface Interface extends Info {
+ readonly directories?: readonly string[]
  readonly vcs?: Project.Vcs
 }
 
@@ -24,6 +25,7 @@ const layer = (ref: Ref) =>
  const resolved = yield* project.resolve(ref.directory)
  return Service.of({
  directory: ref.directory,
+ directories: ref.directories,
  workspaceID: ref.workspaceID,
  project: { id: resolved.id, directory: resolved.directory },
  vcs: resolved.vcs,

packages/core/src/session/sql.ts

@@ -31,6 +31,7 @@ export const SessionTable = sqliteTable(
  parent_id: text().$type<SessionSchema.ID>(),
  slug: text().notNull(),
  directory: DatabasePath.directoryColumn().notNull(),
+ directories: text({ mode: "json" }).$type<string[]>(),
  path: DatabasePath.pathColumn(),
  title: text().notNull(),
  version: text().notNull(),

packages/core/src/system-context/builtins.ts

@@ -13,9 +13,17 @@ const builtIns = Layer.effectDiscard(
  Effect.gen(function* () {
  const location = yield* Location.Service
  const registry = yield* SystemContextRegistry.Service
+ const workspaceFolders = [
+ location.directory,
+ ...(location.directories ?? []).filter((d) => d !== location.directory),
+ ]
+ const workspaceEnv =
+ workspaceFolders.length > 1
+ ? ` Working directory: ${location.directory}\n Workspace folders:\n${workspaceFolders.map((d) => ` - ${d}${d === location.directory ? " (primary)" : ""}`).join("\n")}`
+ : ` Working directory: ${location.directory}`
  const environment = [
  "<env>",
-` Working directory: ${location.directory}`,
+workspaceEnv,
  ` Workspace root folder: ${location.project.directory}`,
  ` Is directory a git repo: ${location.vcs?.type === "git" ? "yes" : "no"}`,
  ` Platform: ${process.platform}`,

packages/core/test/fixture/location.ts

@@ -7,6 +7,7 @@ import { tmpdir } from "./tmpdir"
 export function location(ref: Location.Ref, input: { projectDirectory?: AbsolutePath; vcs?: Project.Vcs } = {}) {
  return {
  directory: ref.directory,
+ directories: ref.directories,
  workspaceID: ref.workspaceID,
  project: { id: Project.ID.global, directory: input.projectDirectory ?? ref.directory },
  vcs: input.vcs,

packages/core/test/location-mutation.test.ts

@@ -21,6 +21,25 @@ function provide(directory: string) {
  )
 }
 
+function provideMultiRoot(directory: string, directories: string[]) {
+ return Effect.provide(
+ LayerNode.compile(LocationMutation.node, [
+ [
+ Location.node,
+ Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location({
+ directory: AbsolutePath.make(directory),
+ directories: directories.map((d) => AbsolutePath.make(d)),
+ }),
+ ),
+ ),
+ ],
+ ]),
+ )
+}
+
 function withTmp<A, E, R>(f: (directory: string) => Effect.Effect<A, E, R>) {
  return Effect.acquireRelease(
  Effect.promise(() => tmpdir()),
@@ -175,4 +194,33 @@ describe("LocationMutation", () => {
  path: "README.md",
  })
  })
+
+ it.live("accepts an absolute path inside a secondary workspace directory without external authorization", () =>
+ withTmp((primary) =>
+ withTmp((secondary) =>
+ Effect.gen(function* () {
+ const targetPath = path.join(secondary, "lib.ts")
+ yield* Effect.promise(() => fs.writeFile(targetPath, "export const x = 1"))
+ const target = yield* (yield* LocationMutation.Service).resolve({ path: targetPath })
+ expect(target.externalDirectory).toBeUndefined()
+ }).pipe(provideMultiRoot(primary, [primary, secondary])),
+ ),
+ ),
+ )
+
+ it.live("rejects an absolute path outside all workspace directories", () =>
+ withTmp((primary) =>
+ withTmp((secondary) =>
+ withTmp((outside) =>
+ Effect.gen(function* () {
+ const targetPath = path.join(outside, "rogue.txt")
+ yield* Effect.promise(() => fs.writeFile(targetPath, "rogue"))
+ const target = yield* (yield* LocationMutation.Service).resolve({ path: targetPath })
+ // Should require external authorization — externalDirectory is set
+ expect(target.externalDirectory).toBeDefined()
+ }).pipe(provideMultiRoot(primary, [primary, secondary])),
+ ),
+ ),
+ ),
+ )
 })

packages/core/test/system-context/builtins.test.ts

@@ -15,6 +15,7 @@ import { testEffect } from "../lib/effect"
 
 const directory = AbsolutePath.make(FSUtil.resolve("/repo/packages/core"))
 const projectDirectory = AbsolutePath.make(FSUtil.resolve("/repo"))
+const secondaryDirectory = AbsolutePath.make(FSUtil.resolve("/repo/packages/schema"))
 const instructionFile = FSUtil.resolve("/repo/AGENTS.md")
 const timestamp = Date.parse("2026-06-03T12:00:00.000Z")
 const localDate = (time: number) => new Date(time).toDateString()
@@ -27,13 +28,44 @@ const locationLayer = Layer.succeed(
  ),
  ),
 )
+const multiRootLocationLayer = Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location(
+ { directory, directories: [directory, secondaryDirectory] },
+ { projectDirectory, vcs: { type: "git", store: AbsolutePath.make(FSUtil.resolve("/repo/.git")) } },
+ ),
+ ),
+)
+// directories array with primary NOT at index 0
+const multiRootReversedLocationLayer = Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location(
+ { directory, directories: [secondaryDirectory, directory] },
+ { projectDirectory, vcs: { type: "git", store: AbsolutePath.make(FSUtil.resolve("/repo/.git")) } },
+ ),
+ ),
+)
 const builtInsNode = LayerNode.group([SystemContextBuiltIns.node, SystemContextRegistry.node])
 const it = testEffect(
  AppNodeBuilder.build(builtInsNode, [
  [Location.node, locationLayer],
  [Global.node, Global.layerWith({ config: "/global" })],
  ]),
 )
+const itMultiRoot = testEffect(
+ AppNodeBuilder.build(builtInsNode, [
+ [Location.node, multiRootLocationLayer],
+ [Global.node, Global.layerWith({ config: "/global" })],
+ ]),
+)
+const itMultiRootReversed = testEffect(
+ AppNodeBuilder.build(builtInsNode, [
+ [Location.node, multiRootReversedLocationLayer],
+ [Global.node, Global.layerWith({ config: "/global" })],
+ ]),
+)
 const instructionFS = Layer.effect(
  FSUtil.Service,
  FSUtil.Service.pipe(
@@ -126,4 +158,54 @@ describe("SystemContextBuiltIns", () => {
  )
  }),
  )
+
+ itMultiRoot.effect("lists workspace folders when multiple directories are configured", () =>
+ Effect.gen(function* () {
+ yield* TestClock.setTime(timestamp)
+ const context = yield* SystemContextRegistry.Service
+ const initialized = yield* SystemContext.initialize(yield* context.load())
+
+ expect(initialized.baseline).toBe(
+ [
+ "Here is some useful information about the environment you are running in:",
+ "<env>",
+ ` Working directory: ${directory}`,
+ ` Workspace folders:`,
+ ` - ${directory} (primary)`,
+ ` - ${secondaryDirectory}`,
+ ` Workspace root folder: ${projectDirectory}`,
+ " Is directory a git repo: yes",
+ ` Platform: ${process.platform}`,
+ "</env>",
+ "",
+ `Today's date: ${localDate(timestamp)}`,
+ ].join("\n"),
+ )
+ }),
+ )
+
+ itMultiRootReversed.effect("marks the correct folder as primary even when directories[0] is not the primary", () =>
+ Effect.gen(function* () {
+ yield* TestClock.setTime(timestamp)
+ const context = yield* SystemContextRegistry.Service
+ const initialized = yield* SystemContext.initialize(yield* context.load())
+
+ expect(initialized.baseline).toBe(
+ [
+ "Here is some useful information about the environment you are running in:",
+ "<env>",
+ ` Working directory: ${directory}`,
+ ` Workspace folders:`,
+ ` - ${directory} (primary)`,
+ ` - ${secondaryDirectory}`,
+ ` Workspace root folder: ${projectDirectory}`,
+ " Is directory a git repo: yes",
+ ` Platform: ${process.platform}`,
+ "</env>",
+ "",
+ `Today's date: ${localDate(timestamp)}`,
+ ].join("\n"),
+ )
+ }),
+ )
 })

packages/opencode/src/project/instance-context.ts

@@ -4,6 +4,7 @@ import type * as Project from "./project"
 
 export interface InstanceContext {
  directory: string
+ directories?: string[]
  worktree: string
  project: Project.Info
 }
@@ -17,6 +18,7 @@ export const context = LocalContext.create<InstanceContext>("instance")
  */
 export function containsPath(filepath: string, ctx: InstanceContext): boolean {
  if (FSUtil.contains(ctx.directory, filepath)) return true
+ if (ctx.directories?.some((d) => FSUtil.contains(d, filepath))) return true
  // Non-git projects set worktree to "/" which would match ANY absolute path.
  // Skip worktree check in this case to preserve external_directory permissions.
  if (ctx.worktree === "/") return false

packages/opencode/src/project/instance-store.ts

@@ -13,6 +13,7 @@ import * as Project from "./project"
 
 export interface LoadInput {
  directory: string
+ directories?: string[]
  worktree?: string
  project?: Project.Info
 }
@@ -48,12 +49,14 @@ const layer: Layer.Layer<Service, never, Project.Service | InstanceBootstrap.Ser
  input.project && input.worktree
  ? {
  directory: input.directory,
+ directories: input.directories,
  worktree: input.worktree,
  project: input.project,
  }
  : yield* project.fromDirectory(input.directory).pipe(
  Effect.map((result) => ({
  directory: input.directory,
+ directories: input.directories,
  worktree: result.sandbox,
  project: result.project,
  })),

packages/opencode/src/session/instruction.ts

@@ -119,16 +119,29 @@ const layer: Layer.Layer<
  }
  }
 
- // The first project-level match wins so we don't stack AGENTS.md/CLAUDE.md from every ancestor.
+ // Multi-root: run findUp from each workspace directory, dedup by resolved path.
+ // Primary first, then remaining in workspace order; each walks to its own boundary.
  if (!Flag.OPENCODE_DISABLE_PROJECT_CONFIG) {
+ const allDirs: string[] = ctx.directories?.length
+ ? ctx.directories
+ : [ctx.directory]
+ // Preserve order but ensure primary is first
+ const ordered = allDirs[0] === ctx.directory ? allDirs : [ctx.directory, ...allDirs.filter((d) => d !== ctx.directory)]
  for (const file of instructionFiles) {
- const matches = yield* fs
- .findUp(file, ctx.directory, ctx.worktree)
- .pipe(Effect.catch(() => Effect.succeed([])))
- if (matches.length > 0) {
- matches.forEach((item) => paths.add(path.resolve(item)))
- break
+ let foundAny = false
+ for (const dir of ordered) {
+ // Primary uses worktree as boundary; secondary directories use themselves
+ // as boundary (don't walk past the workspace root into unrelated parents).
+ const stop = dir === ctx.directory ? ctx.worktree : dir
+ const matches = yield* fs
+ .findUp(file, dir, stop)
+ .pipe(Effect.catch(() => Effect.succeed([])))
+ if (matches.length > 0) {
+ matches.forEach((item) => paths.add(path.resolve(item)))
+ foundAny = true
+ }
  }
+ if (foundAny) break
  }
  }
 

packages/opencode/test/fixture/fixture.ts

@@ -166,9 +166,9 @@ export function tmpdirScoped<E = never, R = never>(options?: {
 }
 
 export const provideInstance =
- (directory: string) =>
+ (directory: string, directories?: string[]) =>
  <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R | InstanceStore.Service> =>
- InstanceStore.Service.use((store) => store.provide({ directory }, self))
+ InstanceStore.Service.use((store) => store.provide({ directory, directories }, self))
 
 export const provideInstanceEffect =
  (directory: string) =>

packages/opencode/test/session/instruction.test.ts

@@ -262,3 +262,45 @@ describe("Instruction.systemPaths global config", () => {
  }),
  )
 })
+
+describe("Instruction.systemPaths multi-root", () => {
+ it.live("discovers AGENTS.md in a secondary workspace directory", () =>
+ Effect.gen(function* () {
+ const primary = yield* tmpWithFiles({})
+ const secondary = yield* tmpWithFiles({ "AGENTS.md": "# Secondary Instructions" })
+
+ yield* Effect.gen(function* () {
+ const svc = yield* Instruction.Service
+ const paths = yield* svc.systemPaths()
+ expect(paths.has(path.join(secondary, "AGENTS.md"))).toBe(true)
+ }).pipe(
+ provideInstance(primary, [primary, secondary]),
+ provideInstruction({ home: primary, config: primary }),
+ )
+ }),
+ )
+
+ it.live("does not walk past a secondary directory into unrelated parent directories", () =>
+ Effect.gen(function* () {
+ // Create two independent git-initialized project directories.
+ // Place an AGENTS.md above the secondary's git root — it should NOT be discovered
+ // because the secondary's findUp stops at the secondary root itself.
+ const primary = yield* tmpdirScoped({ git: true })
+ const secondary = yield* tmpdirScoped({ git: true })
+ const fs = yield* FileSystem.FileSystem
+ // Put AGENTS.md above the secondary's git root
+ const aboveSecondary = path.dirname(secondary)
+ yield* fs.writeFileString(path.join(aboveSecondary, "AGENTS.md"), "# Should NOT be found")
+
+ yield* Effect.gen(function* () {
+ const svc = yield* Instruction.Service
+ const paths = yield* svc.systemPaths()
+ // The AGENTS.md above the secondary's git root should NOT be found
+ expect(paths.has(path.join(aboveSecondary, "AGENTS.md"))).toBe(false)
+ }).pipe(
+ provideInstance(primary, [primary, secondary]),
+ provideInstruction({ home: "/nonexistent-global", config: "/nonexistent-global" }),
+ )
+ }),
+ )
+})

packages/core/src/database/migration/20260820000001_add_session_directories.ts

@@ -0,0 +1,11 @@
+import { Effect } from "effect"
+import type { DatabaseMigration } from "../migration"
+
+export default {
+ id: "20260820000001_add_session_directories",
+ up(tx) {
+ return Effect.gen(function* () {
+ yield* tx.run(`ALTER TABLE session ADD COLUMN directories TEXT;`)
+ })
+ },
+} satisfies DatabaseMigration.Migration

packages/core/src/location-mutation.ts

@@ -117,15 +117,23 @@ const layer = Layer.effect(
  }
  })
 
+ const isLexicallyInternal = (abs: string) =>
+ FSUtil.contains(location.directory, abs) ||
+ (location.directories?.some((d) => FSUtil.contains(d, abs)) ?? false)
+
  const resolve = Effect.fn("LocationMutation.resolve")(function* (input: ResolveInput) {
  const relative = !path.isAbsolute(input.path)
  const absolute = path.resolve(location.directory, input.path)
- const lexicallyInternal = FSUtil.contains(location.directory, absolute)
+ const lexicallyInternal = isLexicallyInternal(absolute)
  if (relative && !lexicallyInternal) return yield* new PathError({ path: input.path, reason: "relative_escape" })
 
  const resolved = yield* resolvePath(absolute)
  if (lexicallyInternal && !FSUtil.contains(locationRoot, resolved.canonical)) {
- return yield* new PathError({ path: input.path, reason: "location_escape" })
+ // Multi-root: also allow canonical inside any workspace directory
+ const canonicalInternal =
+ FSUtil.contains(locationRoot, resolved.canonical) ||
+ (location.directories?.some((d) => FSUtil.contains(d, resolved.canonical)) ?? false)
+ if (!canonicalInternal) return yield* new PathError({ path: input.path, reason: "location_escape" })
  }
 
  const external = !lexicallyInternal

packages/core/src/location.ts

@@ -9,6 +9,7 @@ export * as Location from "./location"
 export { Info, Ref, response }
 
 export interface Interface extends Info {
+ readonly directories?: readonly string[]
  readonly vcs?: Project.Vcs
 }
 
@@ -24,6 +25,7 @@ const layer = (ref: Ref) =>
  const resolved = yield* project.resolve(ref.directory)
  return Service.of({
  directory: ref.directory,
+ directories: ref.directories,
  workspaceID: ref.workspaceID,
  project: { id: resolved.id, directory: resolved.directory },
  vcs: resolved.vcs,

packages/core/src/session/sql.ts

@@ -31,6 +31,7 @@ export const SessionTable = sqliteTable(
  parent_id: text().$type<SessionSchema.ID>(),
  slug: text().notNull(),
  directory: DatabasePath.directoryColumn().notNull(),
+ directories: text({ mode: "json" }).$type<string[]>(),
  path: DatabasePath.pathColumn(),
  title: text().notNull(),
  version: text().notNull(),

packages/core/src/system-context/builtins.ts

@@ -13,9 +13,17 @@ const builtIns = Layer.effectDiscard(
  Effect.gen(function* () {
  const location = yield* Location.Service
  const registry = yield* SystemContextRegistry.Service
+ const workspaceFolders = [
+ location.directory,
+ ...(location.directories ?? []).filter((d) => d !== location.directory),
+ ]
+ const workspaceEnv =
+ workspaceFolders.length > 1
+ ? ` Working directory: ${location.directory}\n Workspace folders:\n${workspaceFolders.map((d) => ` - ${d}${d === location.directory ? " (primary)" : ""}`).join("\n")}`
+ : ` Working directory: ${location.directory}`
  const environment = [
  "<env>",
-` Working directory: ${location.directory}`,
+workspaceEnv,
  ` Workspace root folder: ${location.project.directory}`,
  ` Is directory a git repo: ${location.vcs?.type === "git" ? "yes" : "no"}`,
  ` Platform: ${process.platform}`,

packages/core/test/fixture/location.ts

@@ -7,6 +7,7 @@ import { tmpdir } from "./tmpdir"
 export function location(ref: Location.Ref, input: { projectDirectory?: AbsolutePath; vcs?: Project.Vcs } = {}) {
  return {
  directory: ref.directory,
+ directories: ref.directories,
  workspaceID: ref.workspaceID,
  project: { id: Project.ID.global, directory: input.projectDirectory ?? ref.directory },
  vcs: input.vcs,

packages/core/test/location-mutation.test.ts

@@ -21,6 +21,25 @@ function provide(directory: string) {
  )
 }
 
+function provideMultiRoot(directory: string, directories: string[]) {
+ return Effect.provide(
+ LayerNode.compile(LocationMutation.node, [
+ [
+ Location.node,
+ Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location({
+ directory: AbsolutePath.make(directory),
+ directories: directories.map((d) => AbsolutePath.make(d)),
+ }),
+ ),
+ ),
+ ],
+ ]),
+ )
+}
+
 function withTmp<A, E, R>(f: (directory: string) => Effect.Effect<A, E, R>) {
  return Effect.acquireRelease(
  Effect.promise(() => tmpdir()),
@@ -175,4 +194,33 @@ describe("LocationMutation", () => {
  path: "README.md",
  })
  })
+
+ it.live("accepts an absolute path inside a secondary workspace directory without external authorization", () =>
+ withTmp((primary) =>
+ withTmp((secondary) =>
+ Effect.gen(function* () {
+ const targetPath = path.join(secondary, "lib.ts")
+ yield* Effect.promise(() => fs.writeFile(targetPath, "export const x = 1"))
+ const target = yield* (yield* LocationMutation.Service).resolve({ path: targetPath })
+ expect(target.externalDirectory).toBeUndefined()
+ }).pipe(provideMultiRoot(primary, [primary, secondary])),
+ ),
+ ),
+ )
+
+ it.live("rejects an absolute path outside all workspace directories", () =>
+ withTmp((primary) =>
+ withTmp((secondary) =>
+ withTmp((outside) =>
+ Effect.gen(function* () {
+ const targetPath = path.join(outside, "rogue.txt")
+ yield* Effect.promise(() => fs.writeFile(targetPath, "rogue"))
+ const target = yield* (yield* LocationMutation.Service).resolve({ path: targetPath })
+ // Should require external authorization — externalDirectory is set
+ expect(target.externalDirectory).toBeDefined()
+ }).pipe(provideMultiRoot(primary, [primary, secondary])),
+ ),
+ ),
+ ),
+ )
 })

packages/core/test/system-context/builtins.test.ts

@@ -15,6 +15,7 @@ import { testEffect } from "../lib/effect"
 
 const directory = AbsolutePath.make(FSUtil.resolve("/repo/packages/core"))
 const projectDirectory = AbsolutePath.make(FSUtil.resolve("/repo"))
+const secondaryDirectory = AbsolutePath.make(FSUtil.resolve("/repo/packages/schema"))
 const instructionFile = FSUtil.resolve("/repo/AGENTS.md")
 const timestamp = Date.parse("2026-06-03T12:00:00.000Z")
 const localDate = (time: number) => new Date(time).toDateString()
@@ -27,13 +28,44 @@ const locationLayer = Layer.succeed(
  ),
  ),
 )
+const multiRootLocationLayer = Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location(
+ { directory, directories: [directory, secondaryDirectory] },
+ { projectDirectory, vcs: { type: "git", store: AbsolutePath.make(FSUtil.resolve("/repo/.git")) } },
+ ),
+ ),
+)
+// directories array with primary NOT at index 0
+const multiRootReversedLocationLayer = Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location(
+ { directory, directories: [secondaryDirectory, directory] },
+ { projectDirectory, vcs: { type: "git", store: AbsolutePath.make(FSUtil.resolve("/repo/.git")) } },
+ ),
+ ),
+)
 const builtInsNode = LayerNode.group([SystemContextBuiltIns.node, SystemContextRegistry.node])
 const it = testEffect(
  AppNodeBuilder.build(builtInsNode, [
  [Location.node, locationLayer],
  [Global.node, Global.layerWith({ config: "/global" })],
  ]),
 )
+const itMultiRoot = testEffect(
+ AppNodeBuilder.build(builtInsNode, [
+ [Location.node, multiRootLocationLayer],
+ [Global.node, Global.layerWith({ config: "/global" })],
+ ]),
+)
+const itMultiRootReversed = testEffect(
+ AppNodeBuilder.build(builtInsNode, [
+ [Location.node, multiRootReversedLocationLayer],
+ [Global.node, Global.layerWith({ config: "/global" })],
+ ]),
+)
 const instructionFS = Layer.effect(
  FSUtil.Service,
  FSUtil.Service.pipe(
@@ -126,4 +158,54 @@ describe("SystemContextBuiltIns", () => {
  )
  }),
  )
+
+ itMultiRoot.effect("lists workspace folders when multiple directories are configured", () =>
+ Effect.gen(function* () {
+ yield* TestClock.setTime(timestamp)
+ const context = yield* SystemContextRegistry.Service
+ const initialized = yield* SystemContext.initialize(yield* context.load())
+
+ expect(initialized.baseline).toBe(
+ [
+ "Here is some useful information about the environment you are running in:",
+ "<env>",
+ ` Working directory: ${directory}`,
+ ` Workspace folders:`,
+ ` - ${directory} (primary)`,
+ ` - ${secondaryDirectory}`,
+ ` Workspace root folder: ${projectDirectory}`,
+ " Is directory a git repo: yes",
+ ` Platform: ${process.platform}`,
+ "</env>",
+ "",
+ `Today's date: ${localDate(timestamp)}`,
+ ].join("\n"),
+ )
+ }),
+ )
+
+ itMultiRootReversed.effect("marks the correct folder as primary even when directories[0] is not the primary", () =>
+ Effect.gen(function* () {
+ yield* TestClock.setTime(timestamp)
+ const context = yield* SystemContextRegistry.Service
+ const initialized = yield* SystemContext.initialize(yield* context.load())
+
+ expect(initialized.baseline).toBe(
+ [
+ "Here is some useful information about the environment you are running in:",
+ "<env>",
+ ` Working directory: ${directory}`,
+ ` Workspace folders:`,
+ ` - ${directory} (primary)`,
+ ` - ${secondaryDirectory}`,
+ ` Workspace root folder: ${projectDirectory}`,
+ " Is directory a git repo: yes",
+ ` Platform: ${process.platform}`,
+ "</env>",
+ "",
+ `Today's date: ${localDate(timestamp)}`,
+ ].join("\n"),
+ )
+ }),
+ )
 })

packages/opencode/src/project/instance-context.ts

@@ -4,6 +4,7 @@ import type * as Project from "./project"
 
 export interface InstanceContext {
  directory: string
+ directories?: string[]
  worktree: string
  project: Project.Info
 }
@@ -17,6 +18,7 @@ export const context = LocalContext.create<InstanceContext>("instance")
  */
 export function containsPath(filepath: string, ctx: InstanceContext): boolean {
  if (FSUtil.contains(ctx.directory, filepath)) return true
+ if (ctx.directories?.some((d) => FSUtil.contains(d, filepath))) return true
  // Non-git projects set worktree to "/" which would match ANY absolute path.
  // Skip worktree check in this case to preserve external_directory permissions.
  if (ctx.worktree === "/") return false

packages/opencode/src/project/instance-store.ts

@@ -13,6 +13,7 @@ import * as Project from "./project"
 
 export interface LoadInput {
  directory: string
+ directories?: string[]
  worktree?: string
  project?: Project.Info
 }
@@ -48,12 +49,14 @@ const layer: Layer.Layer<Service, never, Project.Service | InstanceBootstrap.Ser
  input.project && input.worktree
  ? {
  directory: input.directory,
+ directories: input.directories,
  worktree: input.worktree,
  project: input.project,
  }
  : yield* project.fromDirectory(input.directory).pipe(
  Effect.map((result) => ({
  directory: input.directory,
+ directories: input.directories,
  worktree: result.sandbox,
  project: result.project,
  })),

packages/opencode/src/session/instruction.ts

@@ -119,16 +119,29 @@ const layer: Layer.Layer<
  }
  }
 
- // The first project-level match wins so we don't stack AGENTS.md/CLAUDE.md from every ancestor.
+ // Multi-root: run findUp from each workspace directory, dedup by resolved path.
+ // Primary first, then remaining in workspace order; each walks to its own boundary.
  if (!Flag.OPENCODE_DISABLE_PROJECT_CONFIG) {
+ const allDirs: string[] = ctx.directories?.length
+ ? ctx.directories
+ : [ctx.directory]
+ // Preserve order but ensure primary is first
+ const ordered = allDirs[0] === ctx.directory ? allDirs : [ctx.directory, ...allDirs.filter((d) => d !== ctx.directory)]
  for (const file of instructionFiles) {
- const matches = yield* fs
- .findUp(file, ctx.directory, ctx.worktree)
- .pipe(Effect.catch(() => Effect.succeed([])))
- if (matches.length > 0) {
- matches.forEach((item) => paths.add(path.resolve(item)))
- break
+ let foundAny = false
+ for (const dir of ordered) {
+ // Primary uses worktree as boundary; secondary directories use themselves
+ // as boundary (don't walk past the workspace root into unrelated parents).
+ const stop = dir === ctx.directory ? ctx.worktree : dir
+ const matches = yield* fs
+ .findUp(file, dir, stop)
+ .pipe(Effect.catch(() => Effect.succeed([])))
+ if (matches.length > 0) {
+ matches.forEach((item) => paths.add(path.resolve(item)))
+ foundAny = true
+ }
  }
+ if (foundAny) break
  }
  }
 

packages/opencode/test/fixture/fixture.ts

@@ -166,9 +166,9 @@ export function tmpdirScoped<E = never, R = never>(options?: {
 }
 
 export const provideInstance =
- (directory: string) =>
+ (directory: string, directories?: string[]) =>
  <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R | InstanceStore.Service> =>
- InstanceStore.Service.use((store) => store.provide({ directory }, self))
+ InstanceStore.Service.use((store) => store.provide({ directory, directories }, self))
 
 export const provideInstanceEffect =
  (directory: string) =>

packages/opencode/test/session/instruction.test.ts

@@ -262,3 +262,45 @@ describe("Instruction.systemPaths global config", () => {
  }),
  )
 })
+
+describe("Instruction.systemPaths multi-root", () => {
+ it.live("discovers AGENTS.md in a secondary workspace directory", () =>
+ Effect.gen(function* () {
+ const primary = yield* tmpWithFiles({})
+ const secondary = yield* tmpWithFiles({ "AGENTS.md": "# Secondary Instructions" })
+
+ yield* Effect.gen(function* () {
+ const svc = yield* Instruction.Service
+ const paths = yield* svc.systemPaths()
+ expect(paths.has(path.join(secondary, "AGENTS.md"))).toBe(true)
+ }).pipe(
+ provideInstance(primary, [primary, secondary]),
+ provideInstruction({ home: primary, config: primary }),
+ )
+ }),
+ )
+
+ it.live("does not walk past a secondary directory into unrelated parent directories", () =>
+ Effect.gen(function* () {
+ // Create two independent git-initialized project directories.
+ // Place an AGENTS.md above the secondary's git root — it should NOT be discovered
+ // because the secondary's findUp stops at the secondary root itself.
+ const primary = yield* tmpdirScoped({ git: true })
+ const secondary = yield* tmpdirScoped({ git: true })
+ const fs = yield* FileSystem.FileSystem
+ // Put AGENTS.md above the secondary's git root
+ const aboveSecondary = path.dirname(secondary)
+ yield* fs.writeFileString(path.join(aboveSecondary, "AGENTS.md"), "# Should NOT be found")
+
+ yield* Effect.gen(function* () {
+ const svc = yield* Instruction.Service
+ const paths = yield* svc.systemPaths()
+ // The AGENTS.md above the secondary's git root should NOT be found
+ expect(paths.has(path.join(aboveSecondary, "AGENTS.md"))).toBe(false)
+ }).pipe(
+ provideInstance(primary, [primary, secondary]),
+ provideInstruction({ home: "/nonexistent-global", config: "/nonexistent-global" }),
+ )
+ }),
+ )
+})

packages/core/src/database/migration/20260820000001_add_session_directories.ts

@@ -0,0 +1,11 @@
+import { Effect } from "effect"
+import type { DatabaseMigration } from "../migration"
+
+export default {
+ id: "20260820000001_add_session_directories",
+ up(tx) {
+ return Effect.gen(function* () {
+ yield* tx.run(`ALTER TABLE session ADD COLUMN directories TEXT;`)
+ })
+ },
+} satisfies DatabaseMigration.Migration

packages/core/src/location-mutation.ts

@@ -117,15 +117,23 @@ const layer = Layer.effect(
  }
  })
 
+ const isLexicallyInternal = (abs: string) =>
+ FSUtil.contains(location.directory, abs) ||
+ (location.directories?.some((d) => FSUtil.contains(d, abs)) ?? false)
+
  const resolve = Effect.fn("LocationMutation.resolve")(function* (input: ResolveInput) {
  const relative = !path.isAbsolute(input.path)
  const absolute = path.resolve(location.directory, input.path)
- const lexicallyInternal = FSUtil.contains(location.directory, absolute)
+ const lexicallyInternal = isLexicallyInternal(absolute)
  if (relative && !lexicallyInternal) return yield* new PathError({ path: input.path, reason: "relative_escape" })
 
  const resolved = yield* resolvePath(absolute)
  if (lexicallyInternal && !FSUtil.contains(locationRoot, resolved.canonical)) {
- return yield* new PathError({ path: input.path, reason: "location_escape" })
+ // Multi-root: also allow canonical inside any workspace directory
+ const canonicalInternal =
+ FSUtil.contains(locationRoot, resolved.canonical) ||
+ (location.directories?.some((d) => FSUtil.contains(d, resolved.canonical)) ?? false)
+ if (!canonicalInternal) return yield* new PathError({ path: input.path, reason: "location_escape" })
  }
 
  const external = !lexicallyInternal

packages/core/src/location.ts

@@ -9,6 +9,7 @@ export * as Location from "./location"
 export { Info, Ref, response }
 
 export interface Interface extends Info {
+ readonly directories?: readonly string[]
  readonly vcs?: Project.Vcs
 }
 
@@ -24,6 +25,7 @@ const layer = (ref: Ref) =>
  const resolved = yield* project.resolve(ref.directory)
  return Service.of({
  directory: ref.directory,
+ directories: ref.directories,
  workspaceID: ref.workspaceID,
  project: { id: resolved.id, directory: resolved.directory },
  vcs: resolved.vcs,

packages/core/src/session/sql.ts

@@ -31,6 +31,7 @@ export const SessionTable = sqliteTable(
  parent_id: text().$type<SessionSchema.ID>(),
  slug: text().notNull(),
  directory: DatabasePath.directoryColumn().notNull(),
+ directories: text({ mode: "json" }).$type<string[]>(),
  path: DatabasePath.pathColumn(),
  title: text().notNull(),
  version: text().notNull(),

packages/core/src/system-context/builtins.ts

@@ -13,9 +13,17 @@ const builtIns = Layer.effectDiscard(
  Effect.gen(function* () {
  const location = yield* Location.Service
  const registry = yield* SystemContextRegistry.Service
+ const workspaceFolders = [
+ location.directory,
+ ...(location.directories ?? []).filter((d) => d !== location.directory),
+ ]
+ const workspaceEnv =
+ workspaceFolders.length > 1
+ ? ` Working directory: ${location.directory}\n Workspace folders:\n${workspaceFolders.map((d) => ` - ${d}${d === location.directory ? " (primary)" : ""}`).join("\n")}`
+ : ` Working directory: ${location.directory}`
  const environment = [
  "<env>",
-` Working directory: ${location.directory}`,
+workspaceEnv,
  ` Workspace root folder: ${location.project.directory}`,
  ` Is directory a git repo: ${location.vcs?.type === "git" ? "yes" : "no"}`,
  ` Platform: ${process.platform}`,

packages/core/test/fixture/location.ts

@@ -7,6 +7,7 @@ import { tmpdir } from "./tmpdir"
 export function location(ref: Location.Ref, input: { projectDirectory?: AbsolutePath; vcs?: Project.Vcs } = {}) {
  return {
  directory: ref.directory,
+ directories: ref.directories,
  workspaceID: ref.workspaceID,
  project: { id: Project.ID.global, directory: input.projectDirectory ?? ref.directory },
  vcs: input.vcs,

packages/core/test/location-mutation.test.ts

@@ -21,6 +21,25 @@ function provide(directory: string) {
  )
 }
 
+function provideMultiRoot(directory: string, directories: string[]) {
+ return Effect.provide(
+ LayerNode.compile(LocationMutation.node, [
+ [
+ Location.node,
+ Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location({
+ directory: AbsolutePath.make(directory),
+ directories: directories.map((d) => AbsolutePath.make(d)),
+ }),
+ ),
+ ),
+ ],
+ ]),
+ )
+}
+
 function withTmp<A, E, R>(f: (directory: string) => Effect.Effect<A, E, R>) {
  return Effect.acquireRelease(
  Effect.promise(() => tmpdir()),
@@ -175,4 +194,33 @@ describe("LocationMutation", () => {
  path: "README.md",
  })
  })
+
+ it.live("accepts an absolute path inside a secondary workspace directory without external authorization", () =>
+ withTmp((primary) =>
+ withTmp((secondary) =>
+ Effect.gen(function* () {
+ const targetPath = path.join(secondary, "lib.ts")
+ yield* Effect.promise(() => fs.writeFile(targetPath, "export const x = 1"))
+ const target = yield* (yield* LocationMutation.Service).resolve({ path: targetPath })
+ expect(target.externalDirectory).toBeUndefined()
+ }).pipe(provideMultiRoot(primary, [primary, secondary])),
+ ),
+ ),
+ )
+
+ it.live("rejects an absolute path outside all workspace directories", () =>
+ withTmp((primary) =>
+ withTmp((secondary) =>
+ withTmp((outside) =>
+ Effect.gen(function* () {
+ const targetPath = path.join(outside, "rogue.txt")
+ yield* Effect.promise(() => fs.writeFile(targetPath, "rogue"))
+ const target = yield* (yield* LocationMutation.Service).resolve({ path: targetPath })
+ // Should require external authorization — externalDirectory is set
+ expect(target.externalDirectory).toBeDefined()
+ }).pipe(provideMultiRoot(primary, [primary, secondary])),
+ ),
+ ),
+ ),
+ )
 })

packages/core/test/system-context/builtins.test.ts

@@ -15,6 +15,7 @@ import { testEffect } from "../lib/effect"
 
 const directory = AbsolutePath.make(FSUtil.resolve("/repo/packages/core"))
 const projectDirectory = AbsolutePath.make(FSUtil.resolve("/repo"))
+const secondaryDirectory = AbsolutePath.make(FSUtil.resolve("/repo/packages/schema"))
 const instructionFile = FSUtil.resolve("/repo/AGENTS.md")
 const timestamp = Date.parse("2026-06-03T12:00:00.000Z")
 const localDate = (time: number) => new Date(time).toDateString()
@@ -27,13 +28,44 @@ const locationLayer = Layer.succeed(
  ),
  ),
 )
+const multiRootLocationLayer = Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location(
+ { directory, directories: [directory, secondaryDirectory] },
+ { projectDirectory, vcs: { type: "git", store: AbsolutePath.make(FSUtil.resolve("/repo/.git")) } },
+ ),
+ ),
+)
+// directories array with primary NOT at index 0
+const multiRootReversedLocationLayer = Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location(
+ { directory, directories: [secondaryDirectory, directory] },
+ { projectDirectory, vcs: { type: "git", store: AbsolutePath.make(FSUtil.resolve("/repo/.git")) } },
+ ),
+ ),
+)
 const builtInsNode = LayerNode.group([SystemContextBuiltIns.node, SystemContextRegistry.node])
 const it = testEffect(
  AppNodeBuilder.build(builtInsNode, [
  [Location.node, locationLayer],
  [Global.node, Global.layerWith({ config: "/global" })],
  ]),
 )
+const itMultiRoot = testEffect(
+ AppNodeBuilder.build(builtInsNode, [
+ [Location.node, multiRootLocationLayer],
+ [Global.node, Global.layerWith({ config: "/global" })],
+ ]),
+)
+const itMultiRootReversed = testEffect(
+ AppNodeBuilder.build(builtInsNode, [
+ [Location.node, multiRootReversedLocationLayer],
+ [Global.node, Global.layerWith({ config: "/global" })],
+ ]),
+)
 const instructionFS = Layer.effect(
  FSUtil.Service,
  FSUtil.Service.pipe(
@@ -126,4 +158,54 @@ describe("SystemContextBuiltIns", () => {
  )
  }),
  )
+
+ itMultiRoot.effect("lists workspace folders when multiple directories are configured", () =>
+ Effect.gen(function* () {
+ yield* TestClock.setTime(timestamp)
+ const context = yield* SystemContextRegistry.Service
+ const initialized = yield* SystemContext.initialize(yield* context.load())
+
+ expect(initialized.baseline).toBe(
+ [
+ "Here is some useful information about the environment you are running in:",
+ "<env>",
+ ` Working directory: ${directory}`,
+ ` Workspace folders:`,
+ ` - ${directory} (primary)`,
+ ` - ${secondaryDirectory}`,
+ ` Workspace root folder: ${projectDirectory}`,
+ " Is directory a git repo: yes",
+ ` Platform: ${process.platform}`,
+ "</env>",
+ "",
+ `Today's date: ${localDate(timestamp)}`,
+ ].join("\n"),
+ )
+ }),
+ )
+
+ itMultiRootReversed.effect("marks the correct folder as primary even when directories[0] is not the primary", () =>
+ Effect.gen(function* () {
+ yield* TestClock.setTime(timestamp)
+ const context = yield* SystemContextRegistry.Service
+ const initialized = yield* SystemContext.initialize(yield* context.load())
+
+ expect(initialized.baseline).toBe(
+ [
+ "Here is some useful information about the environment you are running in:",
+ "<env>",
+ ` Working directory: ${directory}`,
+ ` Workspace folders:`,
+ ` - ${directory} (primary)`,
+ ` - ${secondaryDirectory}`,
+ ` Workspace root folder: ${projectDirectory}`,
+ " Is directory a git repo: yes",
+ ` Platform: ${process.platform}`,
+ "</env>",
+ "",
+ `Today's date: ${localDate(timestamp)}`,
+ ].join("\n"),
+ )
+ }),
+ )
 })

packages/opencode/src/project/instance-context.ts

@@ -4,6 +4,7 @@ import type * as Project from "./project"
 
 export interface InstanceContext {
  directory: string
+ directories?: string[]
  worktree: string
  project: Project.Info
 }
@@ -17,6 +18,7 @@ export const context = LocalContext.create<InstanceContext>("instance")
  */
 export function containsPath(filepath: string, ctx: InstanceContext): boolean {
  if (FSUtil.contains(ctx.directory, filepath)) return true
+ if (ctx.directories?.some((d) => FSUtil.contains(d, filepath))) return true
  // Non-git projects set worktree to "/" which would match ANY absolute path.
  // Skip worktree check in this case to preserve external_directory permissions.
  if (ctx.worktree === "/") return false

packages/opencode/src/project/instance-store.ts

@@ -13,6 +13,7 @@ import * as Project from "./project"
 
 export interface LoadInput {
  directory: string
+ directories?: string[]
  worktree?: string
  project?: Project.Info
 }
@@ -48,12 +49,14 @@ const layer: Layer.Layer<Service, never, Project.Service | InstanceBootstrap.Ser
  input.project && input.worktree
  ? {
  directory: input.directory,
+ directories: input.directories,
  worktree: input.worktree,
  project: input.project,
  }
  : yield* project.fromDirectory(input.directory).pipe(
  Effect.map((result) => ({
  directory: input.directory,
+ directories: input.directories,
  worktree: result.sandbox,
  project: result.project,
  })),

packages/opencode/src/session/instruction.ts

@@ -119,16 +119,29 @@ const layer: Layer.Layer<
  }
  }
 
- // The first project-level match wins so we don't stack AGENTS.md/CLAUDE.md from every ancestor.
+ // Multi-root: run findUp from each workspace directory, dedup by resolved path.
+ // Primary first, then remaining in workspace order; each walks to its own boundary.
  if (!Flag.OPENCODE_DISABLE_PROJECT_CONFIG) {
+ const allDirs: string[] = ctx.directories?.length
+ ? ctx.directories
+ : [ctx.directory]
+ // Preserve order but ensure primary is first
+ const ordered = allDirs[0] === ctx.directory ? allDirs : [ctx.directory, ...allDirs.filter((d) => d !== ctx.directory)]
  for (const file of instructionFiles) {
- const matches = yield* fs
- .findUp(file, ctx.directory, ctx.worktree)
- .pipe(Effect.catch(() => Effect.succeed([])))
- if (matches.length > 0) {
- matches.forEach((item) => paths.add(path.resolve(item)))
- break
+ let foundAny = false
+ for (const dir of ordered) {
+ // Primary uses worktree as boundary; secondary directories use themselves
+ // as boundary (don't walk past the workspace root into unrelated parents).
+ const stop = dir === ctx.directory ? ctx.worktree : dir
+ const matches = yield* fs
+ .findUp(file, dir, stop)
+ .pipe(Effect.catch(() => Effect.succeed([])))
+ if (matches.length > 0) {
+ matches.forEach((item) => paths.add(path.resolve(item)))
+ foundAny = true
+ }
  }
+ if (foundAny) break
  }
  }
 

packages/opencode/test/fixture/fixture.ts

@@ -166,9 +166,9 @@ export function tmpdirScoped<E = never, R = never>(options?: {
 }
 
 export const provideInstance =
- (directory: string) =>
+ (directory: string, directories?: string[]) =>
  <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R | InstanceStore.Service> =>
- InstanceStore.Service.use((store) => store.provide({ directory }, self))
+ InstanceStore.Service.use((store) => store.provide({ directory, directories }, self))
 
 export const provideInstanceEffect =
  (directory: string) =>

packages/opencode/test/session/instruction.test.ts

@@ -262,3 +262,45 @@ describe("Instruction.systemPaths global config", () => {
  }),
  )
 })
+
+describe("Instruction.systemPaths multi-root", () => {
+ it.live("discovers AGENTS.md in a secondary workspace directory", () =>
+ Effect.gen(function* () {
+ const primary = yield* tmpWithFiles({})
+ const secondary = yield* tmpWithFiles({ "AGENTS.md": "# Secondary Instructions" })
+
+ yield* Effect.gen(function* () {
+ const svc = yield* Instruction.Service
+ const paths = yield* svc.systemPaths()
+ expect(paths.has(path.join(secondary, "AGENTS.md"))).toBe(true)
+ }).pipe(
+ provideInstance(primary, [primary, secondary]),
+ provideInstruction({ home: primary, config: primary }),
+ )
+ }),
+ )
+
+ it.live("does not walk past a secondary directory into unrelated parent directories", () =>
+ Effect.gen(function* () {
+ // Create two independent git-initialized project directories.
+ // Place an AGENTS.md above the secondary's git root — it should NOT be discovered
+ // because the secondary's findUp stops at the secondary root itself.
+ const primary = yield* tmpdirScoped({ git: true })
+ const secondary = yield* tmpdirScoped({ git: true })
+ const fs = yield* FileSystem.FileSystem
+ // Put AGENTS.md above the secondary's git root
+ const aboveSecondary = path.dirname(secondary)
+ yield* fs.writeFileString(path.join(aboveSecondary, "AGENTS.md"), "# Should NOT be found")
+
+ yield* Effect.gen(function* () {
+ const svc = yield* Instruction.Service
+ const paths = yield* svc.systemPaths()
+ // The AGENTS.md above the secondary's git root should NOT be found
+ expect(paths.has(path.join(aboveSecondary, "AGENTS.md"))).toBe(false)
+ }).pipe(
+ provideInstance(primary, [primary, secondary]),
+ provideInstruction({ home: "/nonexistent-global", config: "/nonexistent-global" }),
+ )
+ }),
+ )
+})

packages/core/src/database/migration/20260820000001_add_session_directories.ts

@@ -0,0 +1,11 @@
+import { Effect } from "effect"
+import type { DatabaseMigration } from "../migration"
+
+export default {
+ id: "20260820000001_add_session_directories",
+ up(tx) {
+ return Effect.gen(function* () {
+ yield* tx.run(`ALTER TABLE session ADD COLUMN directories TEXT;`)
+ })
+ },
+} satisfies DatabaseMigration.Migration

packages/core/src/location-mutation.ts

@@ -117,15 +117,23 @@ const layer = Layer.effect(
  }
  })
 
+ const isLexicallyInternal = (abs: string) =>
+ FSUtil.contains(location.directory, abs) ||
+ (location.directories?.some((d) => FSUtil.contains(d, abs)) ?? false)
+
  const resolve = Effect.fn("LocationMutation.resolve")(function* (input: ResolveInput) {
  const relative = !path.isAbsolute(input.path)
  const absolute = path.resolve(location.directory, input.path)
- const lexicallyInternal = FSUtil.contains(location.directory, absolute)
+ const lexicallyInternal = isLexicallyInternal(absolute)
  if (relative && !lexicallyInternal) return yield* new PathError({ path: input.path, reason: "relative_escape" })
 
  const resolved = yield* resolvePath(absolute)
  if (lexicallyInternal && !FSUtil.contains(locationRoot, resolved.canonical)) {
- return yield* new PathError({ path: input.path, reason: "location_escape" })
+ // Multi-root: also allow canonical inside any workspace directory
+ const canonicalInternal =
+ FSUtil.contains(locationRoot, resolved.canonical) ||
+ (location.directories?.some((d) => FSUtil.contains(d, resolved.canonical)) ?? false)
+ if (!canonicalInternal) return yield* new PathError({ path: input.path, reason: "location_escape" })
  }
 
  const external = !lexicallyInternal

packages/core/src/location.ts

@@ -9,6 +9,7 @@ export * as Location from "./location"
 export { Info, Ref, response }
 
 export interface Interface extends Info {
+ readonly directories?: readonly string[]
  readonly vcs?: Project.Vcs
 }
 
@@ -24,6 +25,7 @@ const layer = (ref: Ref) =>
  const resolved = yield* project.resolve(ref.directory)
  return Service.of({
  directory: ref.directory,
+ directories: ref.directories,
  workspaceID: ref.workspaceID,
  project: { id: resolved.id, directory: resolved.directory },
  vcs: resolved.vcs,

packages/core/src/session/sql.ts

@@ -31,6 +31,7 @@ export const SessionTable = sqliteTable(
  parent_id: text().$type<SessionSchema.ID>(),
  slug: text().notNull(),
  directory: DatabasePath.directoryColumn().notNull(),
+ directories: text({ mode: "json" }).$type<string[]>(),
  path: DatabasePath.pathColumn(),
  title: text().notNull(),
  version: text().notNull(),

packages/core/src/system-context/builtins.ts

@@ -13,9 +13,17 @@ const builtIns = Layer.effectDiscard(
  Effect.gen(function* () {
  const location = yield* Location.Service
  const registry = yield* SystemContextRegistry.Service
+ const workspaceFolders = [
+ location.directory,
+ ...(location.directories ?? []).filter((d) => d !== location.directory),
+ ]
+ const workspaceEnv =
+ workspaceFolders.length > 1
+ ? ` Working directory: ${location.directory}\n Workspace folders:\n${workspaceFolders.map((d) => ` - ${d}${d === location.directory ? " (primary)" : ""}`).join("\n")}`
+ : ` Working directory: ${location.directory}`
  const environment = [
  "<env>",
-` Working directory: ${location.directory}`,
+workspaceEnv,
  ` Workspace root folder: ${location.project.directory}`,
  ` Is directory a git repo: ${location.vcs?.type === "git" ? "yes" : "no"}`,
  ` Platform: ${process.platform}`,

packages/core/test/fixture/location.ts

@@ -7,6 +7,7 @@ import { tmpdir } from "./tmpdir"
 export function location(ref: Location.Ref, input: { projectDirectory?: AbsolutePath; vcs?: Project.Vcs } = {}) {
  return {
  directory: ref.directory,
+ directories: ref.directories,
  workspaceID: ref.workspaceID,
  project: { id: Project.ID.global, directory: input.projectDirectory ?? ref.directory },
  vcs: input.vcs,

packages/core/test/location-mutation.test.ts

@@ -21,6 +21,25 @@ function provide(directory: string) {
  )
 }
 
+function provideMultiRoot(directory: string, directories: string[]) {
+ return Effect.provide(
+ LayerNode.compile(LocationMutation.node, [
+ [
+ Location.node,
+ Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location({
+ directory: AbsolutePath.make(directory),
+ directories: directories.map((d) => AbsolutePath.make(d)),
+ }),
+ ),
+ ),
+ ],
+ ]),
+ )
+}
+
 function withTmp<A, E, R>(f: (directory: string) => Effect.Effect<A, E, R>) {
  return Effect.acquireRelease(
  Effect.promise(() => tmpdir()),
@@ -175,4 +194,33 @@ describe("LocationMutation", () => {
  path: "README.md",
  })
  })
+
+ it.live("accepts an absolute path inside a secondary workspace directory without external authorization", () =>
+ withTmp((primary) =>
+ withTmp((secondary) =>
+ Effect.gen(function* () {
+ const targetPath = path.join(secondary, "lib.ts")
+ yield* Effect.promise(() => fs.writeFile(targetPath, "export const x = 1"))
+ const target = yield* (yield* LocationMutation.Service).resolve({ path: targetPath })
+ expect(target.externalDirectory).toBeUndefined()
+ }).pipe(provideMultiRoot(primary, [primary, secondary])),
+ ),
+ ),
+ )
+
+ it.live("rejects an absolute path outside all workspace directories", () =>
+ withTmp((primary) =>
+ withTmp((secondary) =>
+ withTmp((outside) =>
+ Effect.gen(function* () {
+ const targetPath = path.join(outside, "rogue.txt")
+ yield* Effect.promise(() => fs.writeFile(targetPath, "rogue"))
+ const target = yield* (yield* LocationMutation.Service).resolve({ path: targetPath })
+ // Should require external authorization — externalDirectory is set
+ expect(target.externalDirectory).toBeDefined()
+ }).pipe(provideMultiRoot(primary, [primary, secondary])),
+ ),
+ ),
+ ),
+ )
 })

packages/core/test/system-context/builtins.test.ts

@@ -15,6 +15,7 @@ import { testEffect } from "../lib/effect"
 
 const directory = AbsolutePath.make(FSUtil.resolve("/repo/packages/core"))
 const projectDirectory = AbsolutePath.make(FSUtil.resolve("/repo"))
+const secondaryDirectory = AbsolutePath.make(FSUtil.resolve("/repo/packages/schema"))
 const instructionFile = FSUtil.resolve("/repo/AGENTS.md")
 const timestamp = Date.parse("2026-06-03T12:00:00.000Z")
 const localDate = (time: number) => new Date(time).toDateString()
@@ -27,13 +28,44 @@ const locationLayer = Layer.succeed(
  ),
  ),
 )
+const multiRootLocationLayer = Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location(
+ { directory, directories: [directory, secondaryDirectory] },
+ { projectDirectory, vcs: { type: "git", store: AbsolutePath.make(FSUtil.resolve("/repo/.git")) } },
+ ),
+ ),
+)
+// directories array with primary NOT at index 0
+const multiRootReversedLocationLayer = Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location(
+ { directory, directories: [secondaryDirectory, directory] },
+ { projectDirectory, vcs: { type: "git", store: AbsolutePath.make(FSUtil.resolve("/repo/.git")) } },
+ ),
+ ),
+)
 const builtInsNode = LayerNode.group([SystemContextBuiltIns.node, SystemContextRegistry.node])
 const it = testEffect(
  AppNodeBuilder.build(builtInsNode, [
  [Location.node, locationLayer],
  [Global.node, Global.layerWith({ config: "/global" })],
  ]),
 )
+const itMultiRoot = testEffect(
+ AppNodeBuilder.build(builtInsNode, [
+ [Location.node, multiRootLocationLayer],
+ [Global.node, Global.layerWith({ config: "/global" })],
+ ]),
+)
+const itMultiRootReversed = testEffect(
+ AppNodeBuilder.build(builtInsNode, [
+ [Location.node, multiRootReversedLocationLayer],
+ [Global.node, Global.layerWith({ config: "/global" })],
+ ]),
+)
 const instructionFS = Layer.effect(
  FSUtil.Service,
  FSUtil.Service.pipe(
@@ -126,4 +158,54 @@ describe("SystemContextBuiltIns", () => {
  )
  }),
  )
+
+ itMultiRoot.effect("lists workspace folders when multiple directories are configured", () =>
+ Effect.gen(function* () {
+ yield* TestClock.setTime(timestamp)
+ const context = yield* SystemContextRegistry.Service
+ const initialized = yield* SystemContext.initialize(yield* context.load())
+
+ expect(initialized.baseline).toBe(
+ [
+ "Here is some useful information about the environment you are running in:",
+ "<env>",
+ ` Working directory: ${directory}`,
+ ` Workspace folders:`,
+ ` - ${directory} (primary)`,
+ ` - ${secondaryDirectory}`,
+ ` Workspace root folder: ${projectDirectory}`,
+ " Is directory a git repo: yes",
+ ` Platform: ${process.platform}`,
+ "</env>",
+ "",
+ `Today's date: ${localDate(timestamp)}`,
+ ].join("\n"),
+ )
+ }),
+ )
+
+ itMultiRootReversed.effect("marks the correct folder as primary even when directories[0] is not the primary", () =>
+ Effect.gen(function* () {
+ yield* TestClock.setTime(timestamp)
+ const context = yield* SystemContextRegistry.Service
+ const initialized = yield* SystemContext.initialize(yield* context.load())
+
+ expect(initialized.baseline).toBe(
+ [
+ "Here is some useful information about the environment you are running in:",
+ "<env>",
+ ` Working directory: ${directory}`,
+ ` Workspace folders:`,
+ ` - ${directory} (primary)`,
+ ` - ${secondaryDirectory}`,
+ ` Workspace root folder: ${projectDirectory}`,
+ " Is directory a git repo: yes",
+ ` Platform: ${process.platform}`,
+ "</env>",
+ "",
+ `Today's date: ${localDate(timestamp)}`,
+ ].join("\n"),
+ )
+ }),
+ )
 })

packages/opencode/src/project/instance-context.ts

@@ -4,6 +4,7 @@ import type * as Project from "./project"
 
 export interface InstanceContext {
  directory: string
+ directories?: string[]
  worktree: string
  project: Project.Info
 }
@@ -17,6 +18,7 @@ export const context = LocalContext.create<InstanceContext>("instance")
  */
 export function containsPath(filepath: string, ctx: InstanceContext): boolean {
  if (FSUtil.contains(ctx.directory, filepath)) return true
+ if (ctx.directories?.some((d) => FSUtil.contains(d, filepath))) return true
  // Non-git projects set worktree to "/" which would match ANY absolute path.
  // Skip worktree check in this case to preserve external_directory permissions.
  if (ctx.worktree === "/") return false

packages/opencode/src/project/instance-store.ts

@@ -13,6 +13,7 @@ import * as Project from "./project"
 
 export interface LoadInput {
  directory: string
+ directories?: string[]
  worktree?: string
  project?: Project.Info
 }
@@ -48,12 +49,14 @@ const layer: Layer.Layer<Service, never, Project.Service | InstanceBootstrap.Ser
  input.project && input.worktree
  ? {
  directory: input.directory,
+ directories: input.directories,
  worktree: input.worktree,
  project: input.project,
  }
  : yield* project.fromDirectory(input.directory).pipe(
  Effect.map((result) => ({
  directory: input.directory,
+ directories: input.directories,
  worktree: result.sandbox,
  project: result.project,
  })),

packages/opencode/src/session/instruction.ts

@@ -119,16 +119,29 @@ const layer: Layer.Layer<
  }
  }
 
- // The first project-level match wins so we don't stack AGENTS.md/CLAUDE.md from every ancestor.
+ // Multi-root: run findUp from each workspace directory, dedup by resolved path.
+ // Primary first, then remaining in workspace order; each walks to its own boundary.
  if (!Flag.OPENCODE_DISABLE_PROJECT_CONFIG) {
+ const allDirs: string[] = ctx.directories?.length
+ ? ctx.directories
+ : [ctx.directory]
+ // Preserve order but ensure primary is first
+ const ordered = allDirs[0] === ctx.directory ? allDirs : [ctx.directory, ...allDirs.filter((d) => d !== ctx.directory)]
  for (const file of instructionFiles) {
- const matches = yield* fs
- .findUp(file, ctx.directory, ctx.worktree)
- .pipe(Effect.catch(() => Effect.succeed([])))
- if (matches.length > 0) {
- matches.forEach((item) => paths.add(path.resolve(item)))
- break
+ let foundAny = false
+ for (const dir of ordered) {
+ // Primary uses worktree as boundary; secondary directories use themselves
+ // as boundary (don't walk past the workspace root into unrelated parents).
+ const stop = dir === ctx.directory ? ctx.worktree : dir
+ const matches = yield* fs
+ .findUp(file, dir, stop)
+ .pipe(Effect.catch(() => Effect.succeed([])))
+ if (matches.length > 0) {
+ matches.forEach((item) => paths.add(path.resolve(item)))
+ foundAny = true
+ }
  }
+ if (foundAny) break
  }
  }
 

packages/opencode/test/fixture/fixture.ts

@@ -166,9 +166,9 @@ export function tmpdirScoped<E = never, R = never>(options?: {
 }
 
 export const provideInstance =
- (directory: string) =>
+ (directory: string, directories?: string[]) =>
  <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R | InstanceStore.Service> =>
- InstanceStore.Service.use((store) => store.provide({ directory }, self))
+ InstanceStore.Service.use((store) => store.provide({ directory, directories }, self))
 
 export const provideInstanceEffect =
  (directory: string) =>

packages/opencode/test/session/instruction.test.ts

@@ -262,3 +262,45 @@ describe("Instruction.systemPaths global config", () => {
  }),
  )
 })
+
+describe("Instruction.systemPaths multi-root", () => {
+ it.live("discovers AGENTS.md in a secondary workspace directory", () =>
+ Effect.gen(function* () {
+ const primary = yield* tmpWithFiles({})
+ const secondary = yield* tmpWithFiles({ "AGENTS.md": "# Secondary Instructions" })
+
+ yield* Effect.gen(function* () {
+ const svc = yield* Instruction.Service
+ const paths = yield* svc.systemPaths()
+ expect(paths.has(path.join(secondary, "AGENTS.md"))).toBe(true)
+ }).pipe(
+ provideInstance(primary, [primary, secondary]),
+ provideInstruction({ home: primary, config: primary }),
+ )
+ }),
+ )
+
+ it.live("does not walk past a secondary directory into unrelated parent directories", () =>
+ Effect.gen(function* () {
+ // Create two independent git-initialized project directories.
+ // Place an AGENTS.md above the secondary's git root — it should NOT be discovered
+ // because the secondary's findUp stops at the secondary root itself.
+ const primary = yield* tmpdirScoped({ git: true })
+ const secondary = yield* tmpdirScoped({ git: true })
+ const fs = yield* FileSystem.FileSystem
+ // Put AGENTS.md above the secondary's git root
+ const aboveSecondary = path.dirname(secondary)
+ yield* fs.writeFileString(path.join(aboveSecondary, "AGENTS.md"), "# Should NOT be found")
+
+ yield* Effect.gen(function* () {
+ const svc = yield* Instruction.Service
+ const paths = yield* svc.systemPaths()
+ // The AGENTS.md above the secondary's git root should NOT be found
+ expect(paths.has(path.join(aboveSecondary, "AGENTS.md"))).toBe(false)
+ }).pipe(
+ provideInstance(primary, [primary, secondary]),
+ provideInstruction({ home: "/nonexistent-global", config: "/nonexistent-global" }),
+ )
+ }),
+ )
+})

packages/core/src/database/migration/20260820000001_add_session_directories.ts

@@ -0,0 +1,11 @@
+import { Effect } from "effect"
+import type { DatabaseMigration } from "../migration"
+
+export default {
+ id: "20260820000001_add_session_directories",
+ up(tx) {
+ return Effect.gen(function* () {
+ yield* tx.run(`ALTER TABLE session ADD COLUMN directories TEXT;`)
+ })
+ },
+} satisfies DatabaseMigration.Migration

packages/core/src/location-mutation.ts

@@ -117,15 +117,23 @@ const layer = Layer.effect(
  }
  })
 
+ const isLexicallyInternal = (abs: string) =>
+ FSUtil.contains(location.directory, abs) ||
+ (location.directories?.some((d) => FSUtil.contains(d, abs)) ?? false)
+
  const resolve = Effect.fn("LocationMutation.resolve")(function* (input: ResolveInput) {
  const relative = !path.isAbsolute(input.path)
  const absolute = path.resolve(location.directory, input.path)
- const lexicallyInternal = FSUtil.contains(location.directory, absolute)
+ const lexicallyInternal = isLexicallyInternal(absolute)
  if (relative && !lexicallyInternal) return yield* new PathError({ path: input.path, reason: "relative_escape" })
 
  const resolved = yield* resolvePath(absolute)
  if (lexicallyInternal && !FSUtil.contains(locationRoot, resolved.canonical)) {
- return yield* new PathError({ path: input.path, reason: "location_escape" })
+ // Multi-root: also allow canonical inside any workspace directory
+ const canonicalInternal =
+ FSUtil.contains(locationRoot, resolved.canonical) ||
+ (location.directories?.some((d) => FSUtil.contains(d, resolved.canonical)) ?? false)
+ if (!canonicalInternal) return yield* new PathError({ path: input.path, reason: "location_escape" })
  }
 
  const external = !lexicallyInternal

packages/core/src/location.ts

@@ -9,6 +9,7 @@ export * as Location from "./location"
 export { Info, Ref, response }
 
 export interface Interface extends Info {
+ readonly directories?: readonly string[]
  readonly vcs?: Project.Vcs
 }
 
@@ -24,6 +25,7 @@ const layer = (ref: Ref) =>
  const resolved = yield* project.resolve(ref.directory)
  return Service.of({
  directory: ref.directory,
+ directories: ref.directories,
  workspaceID: ref.workspaceID,
  project: { id: resolved.id, directory: resolved.directory },
  vcs: resolved.vcs,

packages/core/src/session/sql.ts

@@ -31,6 +31,7 @@ export const SessionTable = sqliteTable(
  parent_id: text().$type<SessionSchema.ID>(),
  slug: text().notNull(),
  directory: DatabasePath.directoryColumn().notNull(),
+ directories: text({ mode: "json" }).$type<string[]>(),
  path: DatabasePath.pathColumn(),
  title: text().notNull(),
  version: text().notNull(),

packages/core/src/system-context/builtins.ts

@@ -13,9 +13,17 @@ const builtIns = Layer.effectDiscard(
  Effect.gen(function* () {
  const location = yield* Location.Service
  const registry = yield* SystemContextRegistry.Service
+ const workspaceFolders = [
+ location.directory,
+ ...(location.directories ?? []).filter((d) => d !== location.directory),
+ ]
+ const workspaceEnv =
+ workspaceFolders.length > 1
+ ? ` Working directory: ${location.directory}\n Workspace folders:\n${workspaceFolders.map((d) => ` - ${d}${d === location.directory ? " (primary)" : ""}`).join("\n")}`
+ : ` Working directory: ${location.directory}`
  const environment = [
  "<env>",
-` Working directory: ${location.directory}`,
+workspaceEnv,
  ` Workspace root folder: ${location.project.directory}`,
  ` Is directory a git repo: ${location.vcs?.type === "git" ? "yes" : "no"}`,
  ` Platform: ${process.platform}`,

packages/core/test/fixture/location.ts

@@ -7,6 +7,7 @@ import { tmpdir } from "./tmpdir"
 export function location(ref: Location.Ref, input: { projectDirectory?: AbsolutePath; vcs?: Project.Vcs } = {}) {
  return {
  directory: ref.directory,
+ directories: ref.directories,
  workspaceID: ref.workspaceID,
  project: { id: Project.ID.global, directory: input.projectDirectory ?? ref.directory },
  vcs: input.vcs,

packages/core/test/location-mutation.test.ts

@@ -21,6 +21,25 @@ function provide(directory: string) {
  )
 }
 
+function provideMultiRoot(directory: string, directories: string[]) {
+ return Effect.provide(
+ LayerNode.compile(LocationMutation.node, [
+ [
+ Location.node,
+ Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location({
+ directory: AbsolutePath.make(directory),
+ directories: directories.map((d) => AbsolutePath.make(d)),
+ }),
+ ),
+ ),
+ ],
+ ]),
+ )
+}
+
 function withTmp<A, E, R>(f: (directory: string) => Effect.Effect<A, E, R>) {
  return Effect.acquireRelease(
  Effect.promise(() => tmpdir()),
@@ -175,4 +194,33 @@ describe("LocationMutation", () => {
  path: "README.md",
  })
  })
+
+ it.live("accepts an absolute path inside a secondary workspace directory without external authorization", () =>
+ withTmp((primary) =>
+ withTmp((secondary) =>
+ Effect.gen(function* () {
+ const targetPath = path.join(secondary, "lib.ts")
+ yield* Effect.promise(() => fs.writeFile(targetPath, "export const x = 1"))
+ const target = yield* (yield* LocationMutation.Service).resolve({ path: targetPath })
+ expect(target.externalDirectory).toBeUndefined()
+ }).pipe(provideMultiRoot(primary, [primary, secondary])),
+ ),
+ ),
+ )
+
+ it.live("rejects an absolute path outside all workspace directories", () =>
+ withTmp((primary) =>
+ withTmp((secondary) =>
+ withTmp((outside) =>
+ Effect.gen(function* () {
+ const targetPath = path.join(outside, "rogue.txt")
+ yield* Effect.promise(() => fs.writeFile(targetPath, "rogue"))
+ const target = yield* (yield* LocationMutation.Service).resolve({ path: targetPath })
+ // Should require external authorization — externalDirectory is set
+ expect(target.externalDirectory).toBeDefined()
+ }).pipe(provideMultiRoot(primary, [primary, secondary])),
+ ),
+ ),
+ ),
+ )
 })

packages/core/test/system-context/builtins.test.ts

@@ -15,6 +15,7 @@ import { testEffect } from "../lib/effect"
 
 const directory = AbsolutePath.make(FSUtil.resolve("/repo/packages/core"))
 const projectDirectory = AbsolutePath.make(FSUtil.resolve("/repo"))
+const secondaryDirectory = AbsolutePath.make(FSUtil.resolve("/repo/packages/schema"))
 const instructionFile = FSUtil.resolve("/repo/AGENTS.md")
 const timestamp = Date.parse("2026-06-03T12:00:00.000Z")
 const localDate = (time: number) => new Date(time).toDateString()
@@ -27,13 +28,44 @@ const locationLayer = Layer.succeed(
  ),
  ),
 )
+const multiRootLocationLayer = Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location(
+ { directory, directories: [directory, secondaryDirectory] },
+ { projectDirectory, vcs: { type: "git", store: AbsolutePath.make(FSUtil.resolve("/repo/.git")) } },
+ ),
+ ),
+)
+// directories array with primary NOT at index 0
+const multiRootReversedLocationLayer = Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location(
+ { directory, directories: [secondaryDirectory, directory] },
+ { projectDirectory, vcs: { type: "git", store: AbsolutePath.make(FSUtil.resolve("/repo/.git")) } },
+ ),
+ ),
+)
 const builtInsNode = LayerNode.group([SystemContextBuiltIns.node, SystemContextRegistry.node])
 const it = testEffect(
  AppNodeBuilder.build(builtInsNode, [
  [Location.node, locationLayer],
  [Global.node, Global.layerWith({ config: "/global" })],
  ]),
 )
+const itMultiRoot = testEffect(
+ AppNodeBuilder.build(builtInsNode, [
+ [Location.node, multiRootLocationLayer],
+ [Global.node, Global.layerWith({ config: "/global" })],
+ ]),
+)
+const itMultiRootReversed = testEffect(
+ AppNodeBuilder.build(builtInsNode, [
+ [Location.node, multiRootReversedLocationLayer],
+ [Global.node, Global.layerWith({ config: "/global" })],
+ ]),
+)
 const instructionFS = Layer.effect(
  FSUtil.Service,
  FSUtil.Service.pipe(
@@ -126,4 +158,54 @@ describe("SystemContextBuiltIns", () => {
  )
  }),
  )
+
+ itMultiRoot.effect("lists workspace folders when multiple directories are configured", () =>
+ Effect.gen(function* () {
+ yield* TestClock.setTime(timestamp)
+ const context = yield* SystemContextRegistry.Service
+ const initialized = yield* SystemContext.initialize(yield* context.load())
+
+ expect(initialized.baseline).toBe(
+ [
+ "Here is some useful information about the environment you are running in:",
+ "<env>",
+ ` Working directory: ${directory}`,
+ ` Workspace folders:`,
+ ` - ${directory} (primary)`,
+ ` - ${secondaryDirectory}`,
+ ` Workspace root folder: ${projectDirectory}`,
+ " Is directory a git repo: yes",
+ ` Platform: ${process.platform}`,
+ "</env>",
+ "",
+ `Today's date: ${localDate(timestamp)}`,
+ ].join("\n"),
+ )
+ }),
+ )
+
+ itMultiRootReversed.effect("marks the correct folder as primary even when directories[0] is not the primary", () =>
+ Effect.gen(function* () {
+ yield* TestClock.setTime(timestamp)
+ const context = yield* SystemContextRegistry.Service
+ const initialized = yield* SystemContext.initialize(yield* context.load())
+
+ expect(initialized.baseline).toBe(
+ [
+ "Here is some useful information about the environment you are running in:",
+ "<env>",
+ ` Working directory: ${directory}`,
+ ` Workspace folders:`,
+ ` - ${directory} (primary)`,
+ ` - ${secondaryDirectory}`,
+ ` Workspace root folder: ${projectDirectory}`,
+ " Is directory a git repo: yes",
+ ` Platform: ${process.platform}`,
+ "</env>",
+ "",
+ `Today's date: ${localDate(timestamp)}`,
+ ].join("\n"),
+ )
+ }),
+ )
 })

packages/opencode/src/project/instance-context.ts

@@ -4,6 +4,7 @@ import type * as Project from "./project"
 
 export interface InstanceContext {
  directory: string
+ directories?: string[]
  worktree: string
  project: Project.Info
 }
@@ -17,6 +18,7 @@ export const context = LocalContext.create<InstanceContext>("instance")
  */
 export function containsPath(filepath: string, ctx: InstanceContext): boolean {
  if (FSUtil.contains(ctx.directory, filepath)) return true
+ if (ctx.directories?.some((d) => FSUtil.contains(d, filepath))) return true
  // Non-git projects set worktree to "/" which would match ANY absolute path.
  // Skip worktree check in this case to preserve external_directory permissions.
  if (ctx.worktree === "/") return false

packages/opencode/src/project/instance-store.ts

@@ -13,6 +13,7 @@ import * as Project from "./project"
 
 export interface LoadInput {
  directory: string
+ directories?: string[]
  worktree?: string
  project?: Project.Info
 }
@@ -48,12 +49,14 @@ const layer: Layer.Layer<Service, never, Project.Service | InstanceBootstrap.Ser
  input.project && input.worktree
  ? {
  directory: input.directory,
+ directories: input.directories,
  worktree: input.worktree,
  project: input.project,
  }
  : yield* project.fromDirectory(input.directory).pipe(
  Effect.map((result) => ({
  directory: input.directory,
+ directories: input.directories,
  worktree: result.sandbox,
  project: result.project,
  })),

packages/opencode/src/session/instruction.ts

@@ -119,16 +119,29 @@ const layer: Layer.Layer<
  }
  }
 
- // The first project-level match wins so we don't stack AGENTS.md/CLAUDE.md from every ancestor.
+ // Multi-root: run findUp from each workspace directory, dedup by resolved path.
+ // Primary first, then remaining in workspace order; each walks to its own boundary.
  if (!Flag.OPENCODE_DISABLE_PROJECT_CONFIG) {
+ const allDirs: string[] = ctx.directories?.length
+ ? ctx.directories
+ : [ctx.directory]
+ // Preserve order but ensure primary is first
+ const ordered = allDirs[0] === ctx.directory ? allDirs : [ctx.directory, ...allDirs.filter((d) => d !== ctx.directory)]
  for (const file of instructionFiles) {
- const matches = yield* fs
- .findUp(file, ctx.directory, ctx.worktree)
- .pipe(Effect.catch(() => Effect.succeed([])))
- if (matches.length > 0) {
- matches.forEach((item) => paths.add(path.resolve(item)))
- break
+ let foundAny = false
+ for (const dir of ordered) {
+ // Primary uses worktree as boundary; secondary directories use themselves
+ // as boundary (don't walk past the workspace root into unrelated parents).
+ const stop = dir === ctx.directory ? ctx.worktree : dir
+ const matches = yield* fs
+ .findUp(file, dir, stop)
+ .pipe(Effect.catch(() => Effect.succeed([])))
+ if (matches.length > 0) {
+ matches.forEach((item) => paths.add(path.resolve(item)))
+ foundAny = true
+ }
  }
+ if (foundAny) break
  }
  }
 

packages/opencode/test/fixture/fixture.ts

@@ -166,9 +166,9 @@ export function tmpdirScoped<E = never, R = never>(options?: {
 }
 
 export const provideInstance =
- (directory: string) =>
+ (directory: string, directories?: string[]) =>
  <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R | InstanceStore.Service> =>
- InstanceStore.Service.use((store) => store.provide({ directory }, self))
+ InstanceStore.Service.use((store) => store.provide({ directory, directories }, self))
 
 export const provideInstanceEffect =
  (directory: string) =>

packages/opencode/test/session/instruction.test.ts

@@ -262,3 +262,45 @@ describe("Instruction.systemPaths global config", () => {
  }),
  )
 })
+
+describe("Instruction.systemPaths multi-root", () => {
+ it.live("discovers AGENTS.md in a secondary workspace directory", () =>
+ Effect.gen(function* () {
+ const primary = yield* tmpWithFiles({})
+ const secondary = yield* tmpWithFiles({ "AGENTS.md": "# Secondary Instructions" })
+
+ yield* Effect.gen(function* () {
+ const svc = yield* Instruction.Service
+ const paths = yield* svc.systemPaths()
+ expect(paths.has(path.join(secondary, "AGENTS.md"))).toBe(true)
+ }).pipe(
+ provideInstance(primary, [primary, secondary]),
+ provideInstruction({ home: primary, config: primary }),
+ )
+ }),
+ )
+
+ it.live("does not walk past a secondary directory into unrelated parent directories", () =>
+ Effect.gen(function* () {
+ // Create two independent git-initialized project directories.
+ // Place an AGENTS.md above the secondary's git root — it should NOT be discovered
+ // because the secondary's findUp stops at the secondary root itself.
+ const primary = yield* tmpdirScoped({ git: true })
+ const secondary = yield* tmpdirScoped({ git: true })
+ const fs = yield* FileSystem.FileSystem
+ // Put AGENTS.md above the secondary's git root
+ const aboveSecondary = path.dirname(secondary)
+ yield* fs.writeFileString(path.join(aboveSecondary, "AGENTS.md"), "# Should NOT be found")
+
+ yield* Effect.gen(function* () {
+ const svc = yield* Instruction.Service
+ const paths = yield* svc.systemPaths()
+ // The AGENTS.md above the secondary's git root should NOT be found
+ expect(paths.has(path.join(aboveSecondary, "AGENTS.md"))).toBe(false)
+ }).pipe(
+ provideInstance(primary, [primary, secondary]),
+ provideInstruction({ home: "/nonexistent-global", config: "/nonexistent-global" }),
+ )
+ }),
+ )
+})

packages/core/src/database/migration/20260820000001_add_session_directories.ts

@@ -0,0 +1,11 @@
+import { Effect } from "effect"
+import type { DatabaseMigration } from "../migration"
+
+export default {
+ id: "20260820000001_add_session_directories",
+ up(tx) {
+ return Effect.gen(function* () {
+ yield* tx.run(`ALTER TABLE session ADD COLUMN directories TEXT;`)
+ })
+ },
+} satisfies DatabaseMigration.Migration

packages/core/src/location-mutation.ts

@@ -117,15 +117,23 @@ const layer = Layer.effect(
  }
  })
 
+ const isLexicallyInternal = (abs: string) =>
+ FSUtil.contains(location.directory, abs) ||
+ (location.directories?.some((d) => FSUtil.contains(d, abs)) ?? false)
+
  const resolve = Effect.fn("LocationMutation.resolve")(function* (input: ResolveInput) {
  const relative = !path.isAbsolute(input.path)
  const absolute = path.resolve(location.directory, input.path)
- const lexicallyInternal = FSUtil.contains(location.directory, absolute)
+ const lexicallyInternal = isLexicallyInternal(absolute)
  if (relative && !lexicallyInternal) return yield* new PathError({ path: input.path, reason: "relative_escape" })
 
  const resolved = yield* resolvePath(absolute)
  if (lexicallyInternal && !FSUtil.contains(locationRoot, resolved.canonical)) {
- return yield* new PathError({ path: input.path, reason: "location_escape" })
+ // Multi-root: also allow canonical inside any workspace directory
+ const canonicalInternal =
+ FSUtil.contains(locationRoot, resolved.canonical) ||
+ (location.directories?.some((d) => FSUtil.contains(d, resolved.canonical)) ?? false)
+ if (!canonicalInternal) return yield* new PathError({ path: input.path, reason: "location_escape" })
  }
 
  const external = !lexicallyInternal

packages/core/src/location.ts

@@ -9,6 +9,7 @@ export * as Location from "./location"
 export { Info, Ref, response }
 
 export interface Interface extends Info {
+ readonly directories?: readonly string[]
  readonly vcs?: Project.Vcs
 }
 
@@ -24,6 +25,7 @@ const layer = (ref: Ref) =>
  const resolved = yield* project.resolve(ref.directory)
  return Service.of({
  directory: ref.directory,
+ directories: ref.directories,
  workspaceID: ref.workspaceID,
  project: { id: resolved.id, directory: resolved.directory },
  vcs: resolved.vcs,

packages/core/src/session/sql.ts

@@ -31,6 +31,7 @@ export const SessionTable = sqliteTable(
  parent_id: text().$type<SessionSchema.ID>(),
  slug: text().notNull(),
  directory: DatabasePath.directoryColumn().notNull(),
+ directories: text({ mode: "json" }).$type<string[]>(),
  path: DatabasePath.pathColumn(),
  title: text().notNull(),
  version: text().notNull(),

packages/core/src/system-context/builtins.ts

@@ -13,9 +13,17 @@ const builtIns = Layer.effectDiscard(
  Effect.gen(function* () {
  const location = yield* Location.Service
  const registry = yield* SystemContextRegistry.Service
+ const workspaceFolders = [
+ location.directory,
+ ...(location.directories ?? []).filter((d) => d !== location.directory),
+ ]
+ const workspaceEnv =
+ workspaceFolders.length > 1
+ ? ` Working directory: ${location.directory}\n Workspace folders:\n${workspaceFolders.map((d) => ` - ${d}${d === location.directory ? " (primary)" : ""}`).join("\n")}`
+ : ` Working directory: ${location.directory}`
  const environment = [
  "<env>",
-` Working directory: ${location.directory}`,
+workspaceEnv,
  ` Workspace root folder: ${location.project.directory}`,
  ` Is directory a git repo: ${location.vcs?.type === "git" ? "yes" : "no"}`,
  ` Platform: ${process.platform}`,

packages/core/test/fixture/location.ts

@@ -7,6 +7,7 @@ import { tmpdir } from "./tmpdir"
 export function location(ref: Location.Ref, input: { projectDirectory?: AbsolutePath; vcs?: Project.Vcs } = {}) {
  return {
  directory: ref.directory,
+ directories: ref.directories,
  workspaceID: ref.workspaceID,
  project: { id: Project.ID.global, directory: input.projectDirectory ?? ref.directory },
  vcs: input.vcs,

packages/core/test/location-mutation.test.ts

@@ -21,6 +21,25 @@ function provide(directory: string) {
  )
 }
 
+function provideMultiRoot(directory: string, directories: string[]) {
+ return Effect.provide(
+ LayerNode.compile(LocationMutation.node, [
+ [
+ Location.node,
+ Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location({
+ directory: AbsolutePath.make(directory),
+ directories: directories.map((d) => AbsolutePath.make(d)),
+ }),
+ ),
+ ),
+ ],
+ ]),
+ )
+}
+
 function withTmp<A, E, R>(f: (directory: string) => Effect.Effect<A, E, R>) {
  return Effect.acquireRelease(
  Effect.promise(() => tmpdir()),
@@ -175,4 +194,33 @@ describe("LocationMutation", () => {
  path: "README.md",
  })
  })
+
+ it.live("accepts an absolute path inside a secondary workspace directory without external authorization", () =>
+ withTmp((primary) =>
+ withTmp((secondary) =>
+ Effect.gen(function* () {
+ const targetPath = path.join(secondary, "lib.ts")
+ yield* Effect.promise(() => fs.writeFile(targetPath, "export const x = 1"))
+ const target = yield* (yield* LocationMutation.Service).resolve({ path: targetPath })
+ expect(target.externalDirectory).toBeUndefined()
+ }).pipe(provideMultiRoot(primary, [primary, secondary])),
+ ),
+ ),
+ )
+
+ it.live("rejects an absolute path outside all workspace directories", () =>
+ withTmp((primary) =>
+ withTmp((secondary) =>
+ withTmp((outside) =>
+ Effect.gen(function* () {
+ const targetPath = path.join(outside, "rogue.txt")
+ yield* Effect.promise(() => fs.writeFile(targetPath, "rogue"))
+ const target = yield* (yield* LocationMutation.Service).resolve({ path: targetPath })
+ // Should require external authorization — externalDirectory is set
+ expect(target.externalDirectory).toBeDefined()
+ }).pipe(provideMultiRoot(primary, [primary, secondary])),
+ ),
+ ),
+ ),
+ )
 })

packages/core/test/system-context/builtins.test.ts

@@ -15,6 +15,7 @@ import { testEffect } from "../lib/effect"
 
 const directory = AbsolutePath.make(FSUtil.resolve("/repo/packages/core"))
 const projectDirectory = AbsolutePath.make(FSUtil.resolve("/repo"))
+const secondaryDirectory = AbsolutePath.make(FSUtil.resolve("/repo/packages/schema"))
 const instructionFile = FSUtil.resolve("/repo/AGENTS.md")
 const timestamp = Date.parse("2026-06-03T12:00:00.000Z")
 const localDate = (time: number) => new Date(time).toDateString()
@@ -27,13 +28,44 @@ const locationLayer = Layer.succeed(
  ),
  ),
 )
+const multiRootLocationLayer = Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location(
+ { directory, directories: [directory, secondaryDirectory] },
+ { projectDirectory, vcs: { type: "git", store: AbsolutePath.make(FSUtil.resolve("/repo/.git")) } },
+ ),
+ ),
+)
+// directories array with primary NOT at index 0
+const multiRootReversedLocationLayer = Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location(
+ { directory, directories: [secondaryDirectory, directory] },
+ { projectDirectory, vcs: { type: "git", store: AbsolutePath.make(FSUtil.resolve("/repo/.git")) } },
+ ),
+ ),
+)
 const builtInsNode = LayerNode.group([SystemContextBuiltIns.node, SystemContextRegistry.node])
 const it = testEffect(
  AppNodeBuilder.build(builtInsNode, [
  [Location.node, locationLayer],
  [Global.node, Global.layerWith({ config: "/global" })],
  ]),
 )
+const itMultiRoot = testEffect(
+ AppNodeBuilder.build(builtInsNode, [
+ [Location.node, multiRootLocationLayer],
+ [Global.node, Global.layerWith({ config: "/global" })],
+ ]),
+)
+const itMultiRootReversed = testEffect(
+ AppNodeBuilder.build(builtInsNode, [
+ [Location.node, multiRootReversedLocationLayer],
+ [Global.node, Global.layerWith({ config: "/global" })],
+ ]),
+)
 const instructionFS = Layer.effect(
  FSUtil.Service,
  FSUtil.Service.pipe(
@@ -126,4 +158,54 @@ describe("SystemContextBuiltIns", () => {
  )
  }),
  )
+
+ itMultiRoot.effect("lists workspace folders when multiple directories are configured", () =>
+ Effect.gen(function* () {
+ yield* TestClock.setTime(timestamp)
+ const context = yield* SystemContextRegistry.Service
+ const initialized = yield* SystemContext.initialize(yield* context.load())
+
+ expect(initialized.baseline).toBe(
+ [
+ "Here is some useful information about the environment you are running in:",
+ "<env>",
+ ` Working directory: ${directory}`,
+ ` Workspace folders:`,
+ ` - ${directory} (primary)`,
+ ` - ${secondaryDirectory}`,
+ ` Workspace root folder: ${projectDirectory}`,
+ " Is directory a git repo: yes",
+ ` Platform: ${process.platform}`,
+ "</env>",
+ "",
+ `Today's date: ${localDate(timestamp)}`,
+ ].join("\n"),
+ )
+ }),
+ )
+
+ itMultiRootReversed.effect("marks the correct folder as primary even when directories[0] is not the primary", () =>
+ Effect.gen(function* () {
+ yield* TestClock.setTime(timestamp)
+ const context = yield* SystemContextRegistry.Service
+ const initialized = yield* SystemContext.initialize(yield* context.load())
+
+ expect(initialized.baseline).toBe(
+ [
+ "Here is some useful information about the environment you are running in:",
+ "<env>",
+ ` Working directory: ${directory}`,
+ ` Workspace folders:`,
+ ` - ${directory} (primary)`,
+ ` - ${secondaryDirectory}`,
+ ` Workspace root folder: ${projectDirectory}`,
+ " Is directory a git repo: yes",
+ ` Platform: ${process.platform}`,
+ "</env>",
+ "",
+ `Today's date: ${localDate(timestamp)}`,
+ ].join("\n"),
+ )
+ }),
+ )
 })

packages/opencode/src/project/instance-context.ts

@@ -4,6 +4,7 @@ import type * as Project from "./project"
 
 export interface InstanceContext {
  directory: string
+ directories?: string[]
  worktree: string
  project: Project.Info
 }
@@ -17,6 +18,7 @@ export const context = LocalContext.create<InstanceContext>("instance")
  */
 export function containsPath(filepath: string, ctx: InstanceContext): boolean {
  if (FSUtil.contains(ctx.directory, filepath)) return true
+ if (ctx.directories?.some((d) => FSUtil.contains(d, filepath))) return true
  // Non-git projects set worktree to "/" which would match ANY absolute path.
  // Skip worktree check in this case to preserve external_directory permissions.
  if (ctx.worktree === "/") return false

packages/opencode/src/project/instance-store.ts

@@ -13,6 +13,7 @@ import * as Project from "./project"
 
 export interface LoadInput {
  directory: string
+ directories?: string[]
  worktree?: string
  project?: Project.Info
 }
@@ -48,12 +49,14 @@ const layer: Layer.Layer<Service, never, Project.Service | InstanceBootstrap.Ser
  input.project && input.worktree
  ? {
  directory: input.directory,
+ directories: input.directories,
  worktree: input.worktree,
  project: input.project,
  }
  : yield* project.fromDirectory(input.directory).pipe(
  Effect.map((result) => ({
  directory: input.directory,
+ directories: input.directories,
  worktree: result.sandbox,
  project: result.project,
  })),

packages/opencode/src/session/instruction.ts

@@ -119,16 +119,29 @@ const layer: Layer.Layer<
  }
  }
 
- // The first project-level match wins so we don't stack AGENTS.md/CLAUDE.md from every ancestor.
+ // Multi-root: run findUp from each workspace directory, dedup by resolved path.
+ // Primary first, then remaining in workspace order; each walks to its own boundary.
  if (!Flag.OPENCODE_DISABLE_PROJECT_CONFIG) {
+ const allDirs: string[] = ctx.directories?.length
+ ? ctx.directories
+ : [ctx.directory]
+ // Preserve order but ensure primary is first
+ const ordered = allDirs[0] === ctx.directory ? allDirs : [ctx.directory, ...allDirs.filter((d) => d !== ctx.directory)]
  for (const file of instructionFiles) {
- const matches = yield* fs
- .findUp(file, ctx.directory, ctx.worktree)
- .pipe(Effect.catch(() => Effect.succeed([])))
- if (matches.length > 0) {
- matches.forEach((item) => paths.add(path.resolve(item)))
- break
+ let foundAny = false
+ for (const dir of ordered) {
+ // Primary uses worktree as boundary; secondary directories use themselves
+ // as boundary (don't walk past the workspace root into unrelated parents).
+ const stop = dir === ctx.directory ? ctx.worktree : dir
+ const matches = yield* fs
+ .findUp(file, dir, stop)
+ .pipe(Effect.catch(() => Effect.succeed([])))
+ if (matches.length > 0) {
+ matches.forEach((item) => paths.add(path.resolve(item)))
+ foundAny = true
+ }
  }
+ if (foundAny) break
  }
  }
 

packages/opencode/test/fixture/fixture.ts

@@ -166,9 +166,9 @@ export function tmpdirScoped<E = never, R = never>(options?: {
 }
 
 export const provideInstance =
- (directory: string) =>
+ (directory: string, directories?: string[]) =>
  <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R | InstanceStore.Service> =>
- InstanceStore.Service.use((store) => store.provide({ directory }, self))
+ InstanceStore.Service.use((store) => store.provide({ directory, directories }, self))
 
 export const provideInstanceEffect =
  (directory: string) =>

packages/opencode/test/session/instruction.test.ts

@@ -262,3 +262,45 @@ describe("Instruction.systemPaths global config", () => {
  }),
  )
 })
+
+describe("Instruction.systemPaths multi-root", () => {
+ it.live("discovers AGENTS.md in a secondary workspace directory", () =>
+ Effect.gen(function* () {
+ const primary = yield* tmpWithFiles({})
+ const secondary = yield* tmpWithFiles({ "AGENTS.md": "# Secondary Instructions" })
+
+ yield* Effect.gen(function* () {
+ const svc = yield* Instruction.Service
+ const paths = yield* svc.systemPaths()
+ expect(paths.has(path.join(secondary, "AGENTS.md"))).toBe(true)
+ }).pipe(
+ provideInstance(primary, [primary, secondary]),
+ provideInstruction({ home: primary, config: primary }),
+ )
+ }),
+ )
+
+ it.live("does not walk past a secondary directory into unrelated parent directories", () =>
+ Effect.gen(function* () {
+ // Create two independent git-initialized project directories.
+ // Place an AGENTS.md above the secondary's git root — it should NOT be discovered
+ // because the secondary's findUp stops at the secondary root itself.
+ const primary = yield* tmpdirScoped({ git: true })
+ const secondary = yield* tmpdirScoped({ git: true })
+ const fs = yield* FileSystem.FileSystem
+ // Put AGENTS.md above the secondary's git root
+ const aboveSecondary = path.dirname(secondary)
+ yield* fs.writeFileString(path.join(aboveSecondary, "AGENTS.md"), "# Should NOT be found")
+
+ yield* Effect.gen(function* () {
+ const svc = yield* Instruction.Service
+ const paths = yield* svc.systemPaths()
+ // The AGENTS.md above the secondary's git root should NOT be found
+ expect(paths.has(path.join(aboveSecondary, "AGENTS.md"))).toBe(false)
+ }).pipe(
+ provideInstance(primary, [primary, secondary]),
+ provideInstruction({ home: "/nonexistent-global", config: "/nonexistent-global" }),
+ )
+ }),
+ )
+})

packages/core/src/database/migration/20260820000001_add_session_directories.ts

@@ -0,0 +1,11 @@
+import { Effect } from "effect"
+import type { DatabaseMigration } from "../migration"
+
+export default {
+ id: "20260820000001_add_session_directories",
+ up(tx) {
+ return Effect.gen(function* () {
+ yield* tx.run(`ALTER TABLE session ADD COLUMN directories TEXT;`)
+ })
+ },
+} satisfies DatabaseMigration.Migration

packages/core/src/location-mutation.ts

@@ -117,15 +117,23 @@ const layer = Layer.effect(
  }
  })
 
+ const isLexicallyInternal = (abs: string) =>
+ FSUtil.contains(location.directory, abs) ||
+ (location.directories?.some((d) => FSUtil.contains(d, abs)) ?? false)
+
  const resolve = Effect.fn("LocationMutation.resolve")(function* (input: ResolveInput) {
  const relative = !path.isAbsolute(input.path)
  const absolute = path.resolve(location.directory, input.path)
- const lexicallyInternal = FSUtil.contains(location.directory, absolute)
+ const lexicallyInternal = isLexicallyInternal(absolute)
  if (relative && !lexicallyInternal) return yield* new PathError({ path: input.path, reason: "relative_escape" })
 
  const resolved = yield* resolvePath(absolute)
  if (lexicallyInternal && !FSUtil.contains(locationRoot, resolved.canonical)) {
- return yield* new PathError({ path: input.path, reason: "location_escape" })
+ // Multi-root: also allow canonical inside any workspace directory
+ const canonicalInternal =
+ FSUtil.contains(locationRoot, resolved.canonical) ||
+ (location.directories?.some((d) => FSUtil.contains(d, resolved.canonical)) ?? false)
+ if (!canonicalInternal) return yield* new PathError({ path: input.path, reason: "location_escape" })
  }
 
  const external = !lexicallyInternal

packages/core/src/location.ts

@@ -9,6 +9,7 @@ export * as Location from "./location"
 export { Info, Ref, response }
 
 export interface Interface extends Info {
+ readonly directories?: readonly string[]
  readonly vcs?: Project.Vcs
 }
 
@@ -24,6 +25,7 @@ const layer = (ref: Ref) =>
  const resolved = yield* project.resolve(ref.directory)
  return Service.of({
  directory: ref.directory,
+ directories: ref.directories,
  workspaceID: ref.workspaceID,
  project: { id: resolved.id, directory: resolved.directory },
  vcs: resolved.vcs,

packages/core/src/session/sql.ts

@@ -31,6 +31,7 @@ export const SessionTable = sqliteTable(
  parent_id: text().$type<SessionSchema.ID>(),
  slug: text().notNull(),
  directory: DatabasePath.directoryColumn().notNull(),
+ directories: text({ mode: "json" }).$type<string[]>(),
  path: DatabasePath.pathColumn(),
  title: text().notNull(),
  version: text().notNull(),

packages/core/src/system-context/builtins.ts

@@ -13,9 +13,17 @@ const builtIns = Layer.effectDiscard(
  Effect.gen(function* () {
  const location = yield* Location.Service
  const registry = yield* SystemContextRegistry.Service
+ const workspaceFolders = [
+ location.directory,
+ ...(location.directories ?? []).filter((d) => d !== location.directory),
+ ]
+ const workspaceEnv =
+ workspaceFolders.length > 1
+ ? ` Working directory: ${location.directory}\n Workspace folders:\n${workspaceFolders.map((d) => ` - ${d}${d === location.directory ? " (primary)" : ""}`).join("\n")}`
+ : ` Working directory: ${location.directory}`
  const environment = [
  "<env>",
-` Working directory: ${location.directory}`,
+workspaceEnv,
  ` Workspace root folder: ${location.project.directory}`,
  ` Is directory a git repo: ${location.vcs?.type === "git" ? "yes" : "no"}`,
  ` Platform: ${process.platform}`,

packages/core/test/fixture/location.ts

@@ -7,6 +7,7 @@ import { tmpdir } from "./tmpdir"
 export function location(ref: Location.Ref, input: { projectDirectory?: AbsolutePath; vcs?: Project.Vcs } = {}) {
  return {
  directory: ref.directory,
+ directories: ref.directories,
  workspaceID: ref.workspaceID,
  project: { id: Project.ID.global, directory: input.projectDirectory ?? ref.directory },
  vcs: input.vcs,

packages/core/test/location-mutation.test.ts

@@ -21,6 +21,25 @@ function provide(directory: string) {
  )
 }
 
+function provideMultiRoot(directory: string, directories: string[]) {
+ return Effect.provide(
+ LayerNode.compile(LocationMutation.node, [
+ [
+ Location.node,
+ Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location({
+ directory: AbsolutePath.make(directory),
+ directories: directories.map((d) => AbsolutePath.make(d)),
+ }),
+ ),
+ ),
+ ],
+ ]),
+ )
+}
+
 function withTmp<A, E, R>(f: (directory: string) => Effect.Effect<A, E, R>) {
  return Effect.acquireRelease(
  Effect.promise(() => tmpdir()),
@@ -175,4 +194,33 @@ describe("LocationMutation", () => {
  path: "README.md",
  })
  })
+
+ it.live("accepts an absolute path inside a secondary workspace directory without external authorization", () =>
+ withTmp((primary) =>
+ withTmp((secondary) =>
+ Effect.gen(function* () {
+ const targetPath = path.join(secondary, "lib.ts")
+ yield* Effect.promise(() => fs.writeFile(targetPath, "export const x = 1"))
+ const target = yield* (yield* LocationMutation.Service).resolve({ path: targetPath })
+ expect(target.externalDirectory).toBeUndefined()
+ }).pipe(provideMultiRoot(primary, [primary, secondary])),
+ ),
+ ),
+ )
+
+ it.live("rejects an absolute path outside all workspace directories", () =>
+ withTmp((primary) =>
+ withTmp((secondary) =>
+ withTmp((outside) =>
+ Effect.gen(function* () {
+ const targetPath = path.join(outside, "rogue.txt")
+ yield* Effect.promise(() => fs.writeFile(targetPath, "rogue"))
+ const target = yield* (yield* LocationMutation.Service).resolve({ path: targetPath })
+ // Should require external authorization — externalDirectory is set
+ expect(target.externalDirectory).toBeDefined()
+ }).pipe(provideMultiRoot(primary, [primary, secondary])),
+ ),
+ ),
+ ),
+ )
 })

packages/core/test/system-context/builtins.test.ts

@@ -15,6 +15,7 @@ import { testEffect } from "../lib/effect"
 
 const directory = AbsolutePath.make(FSUtil.resolve("/repo/packages/core"))
 const projectDirectory = AbsolutePath.make(FSUtil.resolve("/repo"))
+const secondaryDirectory = AbsolutePath.make(FSUtil.resolve("/repo/packages/schema"))
 const instructionFile = FSUtil.resolve("/repo/AGENTS.md")
 const timestamp = Date.parse("2026-06-03T12:00:00.000Z")
 const localDate = (time: number) => new Date(time).toDateString()
@@ -27,13 +28,44 @@ const locationLayer = Layer.succeed(
  ),
  ),
 )
+const multiRootLocationLayer = Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location(
+ { directory, directories: [directory, secondaryDirectory] },
+ { projectDirectory, vcs: { type: "git", store: AbsolutePath.make(FSUtil.resolve("/repo/.git")) } },
+ ),
+ ),
+)
+// directories array with primary NOT at index 0
+const multiRootReversedLocationLayer = Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location(
+ { directory, directories: [secondaryDirectory, directory] },
+ { projectDirectory, vcs: { type: "git", store: AbsolutePath.make(FSUtil.resolve("/repo/.git")) } },
+ ),
+ ),
+)
 const builtInsNode = LayerNode.group([SystemContextBuiltIns.node, SystemContextRegistry.node])
 const it = testEffect(
  AppNodeBuilder.build(builtInsNode, [
  [Location.node, locationLayer],
  [Global.node, Global.layerWith({ config: "/global" })],
  ]),
 )
+const itMultiRoot = testEffect(
+ AppNodeBuilder.build(builtInsNode, [
+ [Location.node, multiRootLocationLayer],
+ [Global.node, Global.layerWith({ config: "/global" })],
+ ]),
+)
+const itMultiRootReversed = testEffect(
+ AppNodeBuilder.build(builtInsNode, [
+ [Location.node, multiRootReversedLocationLayer],
+ [Global.node, Global.layerWith({ config: "/global" })],
+ ]),
+)
 const instructionFS = Layer.effect(
  FSUtil.Service,
  FSUtil.Service.pipe(
@@ -126,4 +158,54 @@ describe("SystemContextBuiltIns", () => {
  )
  }),
  )
+
+ itMultiRoot.effect("lists workspace folders when multiple directories are configured", () =>
+ Effect.gen(function* () {
+ yield* TestClock.setTime(timestamp)
+ const context = yield* SystemContextRegistry.Service
+ const initialized = yield* SystemContext.initialize(yield* context.load())
+
+ expect(initialized.baseline).toBe(
+ [
+ "Here is some useful information about the environment you are running in:",
+ "<env>",
+ ` Working directory: ${directory}`,
+ ` Workspace folders:`,
+ ` - ${directory} (primary)`,
+ ` - ${secondaryDirectory}`,
+ ` Workspace root folder: ${projectDirectory}`,
+ " Is directory a git repo: yes",
+ ` Platform: ${process.platform}`,
+ "</env>",
+ "",
+ `Today's date: ${localDate(timestamp)}`,
+ ].join("\n"),
+ )
+ }),
+ )
+
+ itMultiRootReversed.effect("marks the correct folder as primary even when directories[0] is not the primary", () =>
+ Effect.gen(function* () {
+ yield* TestClock.setTime(timestamp)
+ const context = yield* SystemContextRegistry.Service
+ const initialized = yield* SystemContext.initialize(yield* context.load())
+
+ expect(initialized.baseline).toBe(
+ [
+ "Here is some useful information about the environment you are running in:",
+ "<env>",
+ ` Working directory: ${directory}`,
+ ` Workspace folders:`,
+ ` - ${directory} (primary)`,
+ ` - ${secondaryDirectory}`,
+ ` Workspace root folder: ${projectDirectory}`,
+ " Is directory a git repo: yes",
+ ` Platform: ${process.platform}`,
+ "</env>",
+ "",
+ `Today's date: ${localDate(timestamp)}`,
+ ].join("\n"),
+ )
+ }),
+ )
 })

packages/opencode/src/project/instance-context.ts

@@ -4,6 +4,7 @@ import type * as Project from "./project"
 
 export interface InstanceContext {
  directory: string
+ directories?: string[]
  worktree: string
  project: Project.Info
 }
@@ -17,6 +18,7 @@ export const context = LocalContext.create<InstanceContext>("instance")
  */
 export function containsPath(filepath: string, ctx: InstanceContext): boolean {
  if (FSUtil.contains(ctx.directory, filepath)) return true
+ if (ctx.directories?.some((d) => FSUtil.contains(d, filepath))) return true
  // Non-git projects set worktree to "/" which would match ANY absolute path.
  // Skip worktree check in this case to preserve external_directory permissions.
  if (ctx.worktree === "/") return false

packages/opencode/src/project/instance-store.ts

@@ -13,6 +13,7 @@ import * as Project from "./project"
 
 export interface LoadInput {
  directory: string
+ directories?: string[]
  worktree?: string
  project?: Project.Info
 }
@@ -48,12 +49,14 @@ const layer: Layer.Layer<Service, never, Project.Service | InstanceBootstrap.Ser
  input.project && input.worktree
  ? {
  directory: input.directory,
+ directories: input.directories,
  worktree: input.worktree,
  project: input.project,
  }
  : yield* project.fromDirectory(input.directory).pipe(
  Effect.map((result) => ({
  directory: input.directory,
+ directories: input.directories,
  worktree: result.sandbox,
  project: result.project,
  })),

packages/opencode/src/session/instruction.ts

@@ -119,16 +119,29 @@ const layer: Layer.Layer<
  }
  }
 
- // The first project-level match wins so we don't stack AGENTS.md/CLAUDE.md from every ancestor.
+ // Multi-root: run findUp from each workspace directory, dedup by resolved path.
+ // Primary first, then remaining in workspace order; each walks to its own boundary.
  if (!Flag.OPENCODE_DISABLE_PROJECT_CONFIG) {
+ const allDirs: string[] = ctx.directories?.length
+ ? ctx.directories
+ : [ctx.directory]
+ // Preserve order but ensure primary is first
+ const ordered = allDirs[0] === ctx.directory ? allDirs : [ctx.directory, ...allDirs.filter((d) => d !== ctx.directory)]
  for (const file of instructionFiles) {
- const matches = yield* fs
- .findUp(file, ctx.directory, ctx.worktree)
- .pipe(Effect.catch(() => Effect.succeed([])))
- if (matches.length > 0) {
- matches.forEach((item) => paths.add(path.resolve(item)))
- break
+ let foundAny = false
+ for (const dir of ordered) {
+ // Primary uses worktree as boundary; secondary directories use themselves
+ // as boundary (don't walk past the workspace root into unrelated parents).
+ const stop = dir === ctx.directory ? ctx.worktree : dir
+ const matches = yield* fs
+ .findUp(file, dir, stop)
+ .pipe(Effect.catch(() => Effect.succeed([])))
+ if (matches.length > 0) {
+ matches.forEach((item) => paths.add(path.resolve(item)))
+ foundAny = true
+ }
  }
+ if (foundAny) break
  }
  }
 

packages/opencode/test/fixture/fixture.ts

@@ -166,9 +166,9 @@ export function tmpdirScoped<E = never, R = never>(options?: {
 }
 
 export const provideInstance =
- (directory: string) =>
+ (directory: string, directories?: string[]) =>
  <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R | InstanceStore.Service> =>
- InstanceStore.Service.use((store) => store.provide({ directory }, self))
+ InstanceStore.Service.use((store) => store.provide({ directory, directories }, self))
 
 export const provideInstanceEffect =
  (directory: string) =>

packages/opencode/test/session/instruction.test.ts

@@ -262,3 +262,45 @@ describe("Instruction.systemPaths global config", () => {
  }),
  )
 })
+
+describe("Instruction.systemPaths multi-root", () => {
+ it.live("discovers AGENTS.md in a secondary workspace directory", () =>
+ Effect.gen(function* () {
+ const primary = yield* tmpWithFiles({})
+ const secondary = yield* tmpWithFiles({ "AGENTS.md": "# Secondary Instructions" })
+
+ yield* Effect.gen(function* () {
+ const svc = yield* Instruction.Service
+ const paths = yield* svc.systemPaths()
+ expect(paths.has(path.join(secondary, "AGENTS.md"))).toBe(true)
+ }).pipe(
+ provideInstance(primary, [primary, secondary]),
+ provideInstruction({ home: primary, config: primary }),
+ )
+ }),
+ )
+
+ it.live("does not walk past a secondary directory into unrelated parent directories", () =>
+ Effect.gen(function* () {
+ // Create two independent git-initialized project directories.
+ // Place an AGENTS.md above the secondary's git root — it should NOT be discovered
+ // because the secondary's findUp stops at the secondary root itself.
+ const primary = yield* tmpdirScoped({ git: true })
+ const secondary = yield* tmpdirScoped({ git: true })
+ const fs = yield* FileSystem.FileSystem
+ // Put AGENTS.md above the secondary's git root
+ const aboveSecondary = path.dirname(secondary)
+ yield* fs.writeFileString(path.join(aboveSecondary, "AGENTS.md"), "# Should NOT be found")
+
+ yield* Effect.gen(function* () {
+ const svc = yield* Instruction.Service
+ const paths = yield* svc.systemPaths()
+ // The AGENTS.md above the secondary's git root should NOT be found
+ expect(paths.has(path.join(aboveSecondary, "AGENTS.md"))).toBe(false)
+ }).pipe(
+ provideInstance(primary, [primary, secondary]),
+ provideInstruction({ home: "/nonexistent-global", config: "/nonexistent-global" }),
+ )
+ }),
+ )
+})

packages/core/src/database/migration/20260820000001_add_session_directories.ts

@@ -0,0 +1,11 @@
+import { Effect } from "effect"
+import type { DatabaseMigration } from "../migration"
+
+export default {
+ id: "20260820000001_add_session_directories",
+ up(tx) {
+ return Effect.gen(function* () {
+ yield* tx.run(`ALTER TABLE session ADD COLUMN directories TEXT;`)
+ })
+ },
+} satisfies DatabaseMigration.Migration

packages/core/src/location-mutation.ts

@@ -117,15 +117,23 @@ const layer = Layer.effect(
  }
  })
 
+ const isLexicallyInternal = (abs: string) =>
+ FSUtil.contains(location.directory, abs) ||
+ (location.directories?.some((d) => FSUtil.contains(d, abs)) ?? false)
+
  const resolve = Effect.fn("LocationMutation.resolve")(function* (input: ResolveInput) {
  const relative = !path.isAbsolute(input.path)
  const absolute = path.resolve(location.directory, input.path)
- const lexicallyInternal = FSUtil.contains(location.directory, absolute)
+ const lexicallyInternal = isLexicallyInternal(absolute)
  if (relative && !lexicallyInternal) return yield* new PathError({ path: input.path, reason: "relative_escape" })
 
  const resolved = yield* resolvePath(absolute)
  if (lexicallyInternal && !FSUtil.contains(locationRoot, resolved.canonical)) {
- return yield* new PathError({ path: input.path, reason: "location_escape" })
+ // Multi-root: also allow canonical inside any workspace directory
+ const canonicalInternal =
+ FSUtil.contains(locationRoot, resolved.canonical) ||
+ (location.directories?.some((d) => FSUtil.contains(d, resolved.canonical)) ?? false)
+ if (!canonicalInternal) return yield* new PathError({ path: input.path, reason: "location_escape" })
  }
 
  const external = !lexicallyInternal

packages/core/src/location.ts

@@ -9,6 +9,7 @@ export * as Location from "./location"
 export { Info, Ref, response }
 
 export interface Interface extends Info {
+ readonly directories?: readonly string[]
  readonly vcs?: Project.Vcs
 }
 
@@ -24,6 +25,7 @@ const layer = (ref: Ref) =>
  const resolved = yield* project.resolve(ref.directory)
  return Service.of({
  directory: ref.directory,
+ directories: ref.directories,
  workspaceID: ref.workspaceID,
  project: { id: resolved.id, directory: resolved.directory },
  vcs: resolved.vcs,

packages/core/src/session/sql.ts

@@ -31,6 +31,7 @@ export const SessionTable = sqliteTable(
  parent_id: text().$type<SessionSchema.ID>(),
  slug: text().notNull(),
  directory: DatabasePath.directoryColumn().notNull(),
+ directories: text({ mode: "json" }).$type<string[]>(),
  path: DatabasePath.pathColumn(),
  title: text().notNull(),
  version: text().notNull(),

packages/core/src/system-context/builtins.ts

@@ -13,9 +13,17 @@ const builtIns = Layer.effectDiscard(
  Effect.gen(function* () {
  const location = yield* Location.Service
  const registry = yield* SystemContextRegistry.Service
+ const workspaceFolders = [
+ location.directory,
+ ...(location.directories ?? []).filter((d) => d !== location.directory),
+ ]
+ const workspaceEnv =
+ workspaceFolders.length > 1
+ ? ` Working directory: ${location.directory}\n Workspace folders:\n${workspaceFolders.map((d) => ` - ${d}${d === location.directory ? " (primary)" : ""}`).join("\n")}`
+ : ` Working directory: ${location.directory}`
  const environment = [
  "<env>",
-` Working directory: ${location.directory}`,
+workspaceEnv,
  ` Workspace root folder: ${location.project.directory}`,
  ` Is directory a git repo: ${location.vcs?.type === "git" ? "yes" : "no"}`,
  ` Platform: ${process.platform}`,

packages/core/test/fixture/location.ts

@@ -7,6 +7,7 @@ import { tmpdir } from "./tmpdir"
 export function location(ref: Location.Ref, input: { projectDirectory?: AbsolutePath; vcs?: Project.Vcs } = {}) {
  return {
  directory: ref.directory,
+ directories: ref.directories,
  workspaceID: ref.workspaceID,
  project: { id: Project.ID.global, directory: input.projectDirectory ?? ref.directory },
  vcs: input.vcs,

packages/core/test/location-mutation.test.ts

@@ -21,6 +21,25 @@ function provide(directory: string) {
  )
 }
 
+function provideMultiRoot(directory: string, directories: string[]) {
+ return Effect.provide(
+ LayerNode.compile(LocationMutation.node, [
+ [
+ Location.node,
+ Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location({
+ directory: AbsolutePath.make(directory),
+ directories: directories.map((d) => AbsolutePath.make(d)),
+ }),
+ ),
+ ),
+ ],
+ ]),
+ )
+}
+
 function withTmp<A, E, R>(f: (directory: string) => Effect.Effect<A, E, R>) {
  return Effect.acquireRelease(
  Effect.promise(() => tmpdir()),
@@ -175,4 +194,33 @@ describe("LocationMutation", () => {
  path: "README.md",
  })
  })
+
+ it.live("accepts an absolute path inside a secondary workspace directory without external authorization", () =>
+ withTmp((primary) =>
+ withTmp((secondary) =>
+ Effect.gen(function* () {
+ const targetPath = path.join(secondary, "lib.ts")
+ yield* Effect.promise(() => fs.writeFile(targetPath, "export const x = 1"))
+ const target = yield* (yield* LocationMutation.Service).resolve({ path: targetPath })
+ expect(target.externalDirectory).toBeUndefined()
+ }).pipe(provideMultiRoot(primary, [primary, secondary])),
+ ),
+ ),
+ )
+
+ it.live("rejects an absolute path outside all workspace directories", () =>
+ withTmp((primary) =>
+ withTmp((secondary) =>
+ withTmp((outside) =>
+ Effect.gen(function* () {
+ const targetPath = path.join(outside, "rogue.txt")
+ yield* Effect.promise(() => fs.writeFile(targetPath, "rogue"))
+ const target = yield* (yield* LocationMutation.Service).resolve({ path: targetPath })
+ // Should require external authorization — externalDirectory is set
+ expect(target.externalDirectory).toBeDefined()
+ }).pipe(provideMultiRoot(primary, [primary, secondary])),
+ ),
+ ),
+ ),
+ )
 })

packages/core/test/system-context/builtins.test.ts

@@ -15,6 +15,7 @@ import { testEffect } from "../lib/effect"
 
 const directory = AbsolutePath.make(FSUtil.resolve("/repo/packages/core"))
 const projectDirectory = AbsolutePath.make(FSUtil.resolve("/repo"))
+const secondaryDirectory = AbsolutePath.make(FSUtil.resolve("/repo/packages/schema"))
 const instructionFile = FSUtil.resolve("/repo/AGENTS.md")
 const timestamp = Date.parse("2026-06-03T12:00:00.000Z")
 const localDate = (time: number) => new Date(time).toDateString()
@@ -27,13 +28,44 @@ const locationLayer = Layer.succeed(
  ),
  ),
 )
+const multiRootLocationLayer = Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location(
+ { directory, directories: [directory, secondaryDirectory] },
+ { projectDirectory, vcs: { type: "git", store: AbsolutePath.make(FSUtil.resolve("/repo/.git")) } },
+ ),
+ ),
+)
+// directories array with primary NOT at index 0
+const multiRootReversedLocationLayer = Layer.succeed(
+ Location.Service,
+ Location.Service.of(
+ location(
+ { directory, directories: [secondaryDirectory, directory] },
+ { projectDirectory, vcs: { type: "git", store: AbsolutePath.make(FSUtil.resolve("/repo/.git")) } },
+ ),
+ ),
+)
 const builtInsNode = LayerNode.group([SystemContextBuiltIns.node, SystemContextRegistry.node])
 const it = testEffect(
  AppNodeBuilder.build(builtInsNode, [
  [Location.node, locationLayer],
  [Global.node, Global.layerWith({ config: "/global" })],
  ]),
 )
+const itMultiRoot = testEffect(
+ AppNodeBuilder.build(builtInsNode, [
+ [Location.node, multiRootLocationLayer],
+ [Global.node, Global.layerWith({ config: "/global" })],
+ ]),
+)
+const itMultiRootReversed = testEffect(
+ AppNodeBuilder.build(builtInsNode, [
+ [Location.node, multiRootReversedLocationLayer],
+ [Global.node, Global.layerWith({ config: "/global" })],
+ ]),
+)
 const instructionFS = Layer.effect(
  FSUtil.Service,
  FSUtil.Service.pipe(
@@ -126,4 +158,54 @@ describe("SystemContextBuiltIns", () => {
  )
  }),
  )
+
+ itMultiRoot.effect("lists workspace folders when multiple directories are configured", () =>
+ Effect.gen(function* () {
+ yield* TestClock.setTime(timestamp)
+ const context = yield* SystemContextRegistry.Service
+ const initialized = yield* SystemContext.initialize(yield* context.load())
+
+ expect(initialized.baseline).toBe(
+ [
+ "Here is some useful information about the environment you are running in:",
+ "<env>",
+ ` Working directory: ${directory}`,
+ ` Workspace folders:`,
+ ` - ${directory} (primary)`,
+ ` - ${secondaryDirectory}`,
+ ` Workspace root folder: ${projectDirectory}`,
+ " Is directory a git repo: yes",
+ ` Platform: ${process.platform}`,
+ "</env>",
+ "",
+ `Today's date: ${localDate(timestamp)}`,
+ ].join("\n"),
+ )
+ }),
+ )
+
+ itMultiRootReversed.effect("marks the correct folder as primary even when directories[0] is not the primary", () =>
+ Effect.gen(function* () {
+ yield* TestClock.setTime(timestamp)
+ const context = yield* SystemContextRegistry.Service
+ const initialized = yield* SystemContext.initialize(yield* context.load())
+
+ expect(initialized.baseline).toBe(
+ [
+ "Here is some useful information about the environment you are running in:",
+ "<env>",
+ ` Working directory: ${directory}`,
+ ` Workspace folders:`,
+ ` - ${directory} (primary)`,
+ ` - ${secondaryDirectory}`,
+ ` Workspace root folder: ${projectDirectory}`,
+ " Is directory a git repo: yes",
+ ` Platform: ${process.platform}`,
+ "</env>",
+ "",
+ `Today's date: ${localDate(timestamp)}`,
+ ].join("\n"),
+ )
+ }),
+ )
 })

packages/opencode/src/project/instance-context.ts

@@ -4,6 +4,7 @@ import type * as Project from "./project"
 
 export interface InstanceContext {
  directory: string
+ directories?: string[]
  worktree: string
  project: Project.Info
 }
@@ -17,6 +18,7 @@ export const context = LocalContext.create<InstanceContext>("instance")
  */
 export function containsPath(filepath: string, ctx: InstanceContext): boolean {
  if (FSUtil.contains(ctx.directory, filepath)) return true
+ if (ctx.directories?.some((d) => FSUtil.contains(d, filepath))) return true
  // Non-git projects set worktree to "/" which would match ANY absolute path.
  // Skip worktree check in this case to preserve external_directory permissions.
  if (ctx.worktree === "/") return false

packages/opencode/src/project/instance-store.ts

@@ -13,6 +13,7 @@ import * as Project from "./project"
 
 export interface LoadInput {
  directory: string
+ directories?: string[]
  worktree?: string
  project?: Project.Info
 }
@@ -48,12 +49,14 @@ const layer: Layer.Layer<Service, never, Project.Service | InstanceBootstrap.Ser
  input.project && input.worktree
  ? {
  directory: input.directory,
+ directories: input.directories,
  worktree: input.worktree,
  project: input.project,
  }
  : yield* project.fromDirectory(input.directory).pipe(
  Effect.map((result) => ({
  directory: input.directory,
+ directories: input.directories,
  worktree: result.sandbox,
  project: result.project,
  })),

packages/opencode/src/session/instruction.ts

@@ -119,16 +119,29 @@ const layer: Layer.Layer<
  }
  }
 
- // The first project-level match wins so we don't stack AGENTS.md/CLAUDE.md from every ancestor.
+ // Multi-root: run findUp from each workspace directory, dedup by resolved path.
+ // Primary first, then remaining in workspace order; each walks to its own boundary.
  if (!Flag.OPENCODE_DISABLE_PROJECT_CONFIG) {
+ const allDirs: string[] = ctx.directories?.length
+ ? ctx.directories
+ : [ctx.directory]
+ // Preserve order but ensure primary is first
+ const ordered = allDirs[0] === ctx.directory ? allDirs : [ctx.directory, ...allDirs.filter((d) => d !== ctx.directory)]
  for (const file of instructionFiles) {
- const matches = yield* fs
- .findUp(file, ctx.directory, ctx.worktree)
- .pipe(Effect.catch(() => Effect.succeed([])))
- if (matches.length > 0) {
- matches.forEach((item) => paths.add(path.resolve(item)))
- break
+ let foundAny = false
+ for (const dir of ordered) {
+ // Primary uses worktree as boundary; secondary directories use themselves
+ // as boundary (don't walk past the workspace root into unrelated parents).
+ const stop = dir === ctx.directory ? ctx.worktree : dir
+ const matches = yield* fs
+ .findUp(file, dir, stop)
+ .pipe(Effect.catch(() => Effect.succeed([])))
+ if (matches.length > 0) {
+ matches.forEach((item) => paths.add(path.resolve(item)))
+ foundAny = true
+ }
  }
+ if (foundAny) break
  }
  }
 

packages/opencode/test/fixture/fixture.ts

@@ -166,9 +166,9 @@ export function tmpdirScoped<E = never, R = never>(options?: {
 }
 
 export const provideInstance =
- (directory: string) =>
+ (directory: string, directories?: string[]) =>
  <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R | InstanceStore.Service> =>
- InstanceStore.Service.use((store) => store.provide({ directory }, self))
+ InstanceStore.Service.use((store) => store.provide({ directory, directories }, self))
 
 export const provideInstanceEffect =
  (directory: string) =>

packages/opencode/test/session/instruction.test.ts

@@ -262,3 +262,45 @@ describe("Instruction.systemPaths global config", () => {
  }),
  )
 })
+
+describe("Instruction.systemPaths multi-root", () => {
+ it.live("discovers AGENTS.md in a secondary workspace directory", () =>
+ Effect.gen(function* () {
+ const primary = yield* tmpWithFiles({})
+ const secondary = yield* tmpWithFiles({ "AGENTS.md": "# Secondary Instructions" })
+
+ yield* Effect.gen(function* () {
+ const svc = yield* Instruction.Service
+ const paths = yield* svc.systemPaths()
+ expect(paths.has(path.join(secondary, "AGENTS.md"))).toBe(true)
+ }).pipe(
+ provideInstance(primary, [primary, secondary]),
+ provideInstruction({ home: primary, config: primary }),
+ )
+ }),
+ )
+
+ it.live("does not walk past a secondary directory into unrelated parent directories", () =>
+ Effect.gen(function* () {
+ // Create two independent git-initialized project directories.
+ // Place an AGENTS.md above the secondary's git root — it should NOT be discovered
+ // because the secondary's findUp stops at the secondary root itself.
+ const primary = yield* tmpdirScoped({ git: true })
+ const secondary = yield* tmpdirScoped({ git: true })
+ const fs = yield* FileSystem.FileSystem
+ // Put AGENTS.md above the secondary's git root
+ const aboveSecondary = path.dirname(secondary)
+ yield* fs.writeFileString(path.join(aboveSecondary, "AGENTS.md"), "# Should NOT be found")
+
+ yield* Effect.gen(function* () {
+ const svc = yield* Instruction.Service
+ const paths = yield* svc.systemPaths()
+ // The AGENTS.md above the secondary's git root should NOT be found
+ expect(paths.has(path.join(aboveSecondary, "AGENTS.md"))).toBe(false)
+ }).pipe(
+ provideInstance(primary, [primary, secondary]),
+ provideInstruction({ home: "/nonexistent-global", config: "/nonexistent-global" }),
+ )
+ }),
+ )
+})