refactor(core): centralize external directory defaults

Co-authored-by: Aiden Cline <rekram1-node@users.noreply.github.com>

packages/ai/AGENTS.md

@@ -10,7 +10,7 @@
 
 ## Conventions
 
-Per-type constructors live on the type, not as top-level re-exports. Use `Message.system(...)`, `Message.user(...)`, `Message.assistant(...)`, `Message.tool(...)`, `LanguageModel.make(...)`, `ToolDefinition.make(...)`, `ToolCallPart.make(...)`, `ToolResultPart.make(...)`, `ToolChoice.make(...)`, `ToolChoice.named(...)`, `SystemPart.make(...)`, and `GenerationOptions.make(...)` directly. The top-level `LLM` namespace is reserved for request-shaped call APIs: `LLM.request`, `LLM.generate`, `LLM.stream`, `LLM.updateRequest`, and `LLM.generateObject`. Two ways to construct the same thing is one too many.
+Per-type constructors live on the type, not as top-level re-exports. Use `Message.system(...)`, `Message.user(...)`, `Message.assistant(...)`, `Message.tool(...)`, `LanguageModel.make(...)`, `ToolDefinition.make(...)`, `ToolCallPart.make(...)`, `ToolResultPart.make(...)`, `ToolChoice.make(...)`, `ToolChoice.named(...)`, `SystemPart.make(...)`, and `GenerationOptions.make(...)` directly. The top-level `LLM` namespace is reserved for request-shaped call APIs: `LLM.request`, `LLM.generate`, `LLM.stream`, and `LLM.generateObject`. Use `LLMRequest.update(...)` when deriving canonical request data; do not add a duplicate `LLM.updateRequest(...)` path. Two ways to construct the same thing is one too many.
 
 - Keep provider-defined string enums forward-compatible. Expose known values for autocomplete while accepting future values with `Known | (string & {})`; use `Schema.String` at runtime unless rejecting unknown values is required for correctness.
 

packages/ai/README.md

@@ -3,8 +3,9 @@
 Schema-first AI primitives for opencode. Provider quirks live in adapters, not in calling code.
 
 ```ts
-import { Effect } from "effect"
+import { Effect, Layer } from "effect"
 import { LLM, LLMClient } from "@opencode-ai/ai"
+import { RequestExecutor } from "@opencode-ai/ai/route"
 import { OpenAI } from "@opencode-ai/ai/providers"
 
 const model = OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY }).responses("gpt-4o-mini")
@@ -20,6 +21,10 @@ const program = Effect.gen(function* () {
   const response = yield* LLMClient.generate(request)
   console.log(response.text)
 })
+
+const llmLayer = LLMClient.layer.pipe(Layer.provide(RequestExecutor.fetchLayer))
+
+await Effect.runPromise(program.pipe(Effect.provide(llmLayer)))
 ```
 
 Run `LLMClient.stream(request)` instead of `generate` when you want incremental `LLMEvent`s. The event stream is provider-neutral — same shape across OpenAI Chat, OpenAI Responses, Anthropic Messages, Gemini, Bedrock Converse, and any OpenAI-compatible deployment.
@@ -200,6 +205,32 @@ The hosted result is represented as a provider-executed tool call and tool resul
 - **`Image.generate({...})`** — generate images through a provider-neutral image request and response model.
 - **`ImageClient`** — Effect service and layer for image execution, parallel to `LLMClient`.
 
+## Testing
+
+Use the deterministic test client from `@opencode-ai/ai/testing` to script provider-neutral responses and inspect
+the requests sent by code under test:
+
+```ts
+import { Effect } from "effect"
+import { TestLLM } from "@opencode-ai/ai/testing"
+
+const testLLM = TestLLM.layer({
+  fallback: TestLLM.text("Hello from the test model", "text-1"),
+})
+
+// TestLLM.clientLayer provides LLMClient.Service and consumes TestLLM.Service.
+const programWithTestClient = Effect.gen(function* () {
+  const result = yield* program
+  const test = yield* TestLLM.Service
+  console.log(test.requests)
+  return result
+}).pipe(Effect.provide(TestLLM.clientLayer), Effect.provide(testLLM))
+```
+
+`TestLLM.push(...)` scripts one-shot responses, `TestLLM.always(...)` changes the fallback, and
+`TestLLM.wait(...)` lets concurrent tests wait until a request has arrived. Every received canonical request is
+available on the yielded `TestLLM.Service`.
+
 ## Caching
 
 Prompt caching is **on by default**. Every `LLMRequest` resolves to `cache: "auto"` unless the caller opts out with `cache: "none"`. Each protocol translates `CacheHint`s to its wire format (`cache_control` on Anthropic, `cachePoint` on Bedrock; OpenAI and Gemini do implicit caching server-side and don't need inline markers — auto is a no-op there).

packages/ai/src/image-client.ts

@@ -15,11 +15,11 @@ export class Service extends Context.Service<Service, Interface>()("@opencode/Im
 
 export const generate = <Options extends ImageOptions>(
   request: ImageRequestFor<Options>,
-): Effect.Effect<ImageResponse, AIError> =>
+): Effect.Effect<ImageResponse, AIError, Service> =>
   Effect.gen(function* () {
     const client = yield* Service
     return yield* client.generate(request)
-  }) as Effect.Effect<ImageResponse, AIError>
+  })
 
 export const layer: Layer.Layer<Service, never, RequestExecutor.Service> = Layer.effect(
   Service,

packages/ai/src/llm.ts

@@ -1,5 +1,5 @@
 import { Effect, JsonSchema, Schema } from "effect"
-import { LLMClient } from "./route/client"
+import { LLMClient, Service } from "./route/client"
 import {
   GenerationOptions,
   HttpOptions,
@@ -151,10 +151,10 @@ const runGenerateObject = Effect.fn("LLM.generateObject")(function* (
  */
 export function generateObject<const SelectedLanguageModel extends LanguageModel, S extends ToolSchema<any>>(
   options: GenerateObjectOptions<S, SelectedLanguageModel>,
-): Effect.Effect<GenerateObjectResponse<Schema.Schema.Type<S>>, AIError>
+): Effect.Effect<GenerateObjectResponse<Schema.Schema.Type<S>>, AIError, Service>
 export function generateObject<const SelectedLanguageModel extends LanguageModel>(
   options: GenerateObjectDynamicOptions<SelectedLanguageModel>,
-): Effect.Effect<GenerateObjectResponse<unknown>, AIError>
+): Effect.Effect<GenerateObjectResponse<unknown>, AIError, Service>
 export function generateObject(options: GenerateObjectOptions<ToolSchema<any>> | GenerateObjectDynamicOptions) {
   if ("schema" in options) {
     const { schema, ...rest } = options

packages/ai/src/route/client.ts

@@ -422,18 +422,18 @@ const generateWith = (stream: Interface["stream"]) =>
     )
   })
 
-export function stream(request: LLMRequest, options?: StreamOptions): Stream.Stream<LLMEvent, AIError> {
+export function stream(request: LLMRequest, options?: StreamOptions): Stream.Stream<LLMEvent, AIError, Service> {
   return Stream.unwrap(
     Effect.gen(function* () {
       return (yield* Service).stream(request, options)
     }),
-  ) as Stream.Stream<LLMEvent, AIError>
+  )
 }
 
-export function generate(request: LLMRequest, options?: StreamOptions): Effect.Effect<LLMResponse, AIError> {
+export function generate(request: LLMRequest, options?: StreamOptions): Effect.Effect<LLMResponse, AIError, Service> {
   return Effect.gen(function* () {
     return yield* (yield* Service).generate(request, options)
-  }) as Effect.Effect<LLMResponse, AIError>
+  })
 }
 
 export const streamRequest = (request: LLMRequest, options?: StreamOptions) =>

packages/ai/test/image.types.ts

@@ -1,5 +1,7 @@
+import { Effect } from "effect"
 import {
   Image,
+  ImageClient,
   ImageInput,
   ImageModel,
   type ImageModelOptions,
@@ -7,8 +9,13 @@ import {
   type ImageRequestFor,
   type ImageRoute,
 } from "../src"
+import type { Service } from "../src/image-client"
 import { Google, OpenAI, XAI, ZAI } from "../src/providers"
 
+type Requirements<T> = T extends Effect.Effect<infer _A, infer _E, infer R> ? R : never
+type Equal<A, B> = [A, B] extends [B, A] ? true : false
+type Assert<T extends true> = T
+
 type GoogleLikeOptions = {
   readonly aspectRatio?: "1:1" | "16:9"
   readonly imageSize?: "1K" | "2K"
@@ -146,6 +153,9 @@ const request = Image.request({
 })
 const typedRequest: ImageRequestFor<GoogleLikeOptions> = request
 void typedRequest
+const generated = ImageClient.generate(request)
+type GenerateRequirements = Assert<Equal<Requirements<typeof generated>, Service>>
+void (true satisfies GenerateRequirements)
 
 // @ts-expect-error Image requests no longer expose a common count option.
 Image.generate({ model: openai, prompt: "A lighthouse", count: 2 })

packages/ai/test/llm-option-types.types.ts

@@ -1,5 +1,11 @@
-import { Schema } from "effect"
-import { LLM, type LanguageModel, type LanguageModelProviderOptions, type ProviderOptions } from "../src"
+import { Effect, Schema, Stream } from "effect"
+import {
+  LLM,
+  type LLMClientService,
+  type LanguageModel,
+  type LanguageModelProviderOptions,
+  type ProviderOptions,
+} from "../src"
 import { OpenAIChat } from "../src/protocols"
 
 interface ExampleOptions {
@@ -15,9 +21,19 @@ const model = OpenAIChat.route
   .with({ endpoint: { baseURL: "https://example.com/v1" } })
   .model<ExampleProviderOptions>({ id: "example" })
 
+type Requirements<T> = T extends Effect.Effect<infer _A, infer _E, infer R> ? R : never
+type StreamRequirements<T> = T extends Stream.Stream<infer _A, infer _E, infer R> ? R : never
+type Equal<A, B> = [A, B] extends [B, A] ? true : false
+type Assert<T extends true> = T
+
 LLM.request({ model, prompt: "Hello", providerOptions: { example: { mode: "fast" } } })
 LLM.request({ model, prompt: "Hello", providerOptions: { future: { option: true } } })
 
+const generated = LLM.generate(LLM.request({ model, prompt: "Hello" }))
+type GenerateRequirements = Assert<Equal<Requirements<typeof generated>, LLMClientService>>
+const streamed = LLM.stream(LLM.request({ model, prompt: "Hello" }))
+type StreamClientRequirements = Assert<Equal<StreamRequirements<typeof streamed>, LLMClientService>>
+
 LLM.request({
   model,
   prompt: "Hello",
@@ -25,12 +41,20 @@ LLM.request({
   providerOptions: { example: { mode: "slow" } },
 })
 
-LLM.generateObject({
+const generatedObject = LLM.generateObject({
   model,
   prompt: "Hello",
   schema: Schema.Struct({ answer: Schema.String }),
   providerOptions: { example: { mode: "thorough" } },
 })
+type GenerateObjectRequirements = Assert<Equal<Requirements<typeof generatedObject>, LLMClientService>>
+
+const generatedDynamicObject = LLM.generateObject({
+  model,
+  prompt: "Hello",
+  jsonSchema: { type: "object" },
+})
+type GenerateDynamicObjectRequirements = Assert<Equal<Requirements<typeof generatedDynamicObject>, LLMClientService>>
 
 LLM.generateObject({
   model,
@@ -44,4 +68,8 @@ declare const generic: LanguageModel
 LLM.request({ model: generic, prompt: "Hello", providerOptions: { arbitrary: { option: true } } })
 
 const options: LanguageModelProviderOptions<typeof model> = { example: { mode: "fast" } }
-void options
+void (options satisfies LanguageModelProviderOptions<typeof model>)
+void (true satisfies GenerateRequirements)
+void (true satisfies StreamClientRequirements)
+void (true satisfies GenerateObjectRequirements)
+void (true satisfies GenerateDynamicObjectRequirements)

packages/core/src/agent.ts

@@ -26,6 +26,7 @@ export interface Selection {
 
 type Data = {
   agents: Map<ID, Types.DeepMutable<Info>>
+  permissions: Types.DeepMutable<Info["permissions"]>
   default?: ID
 }
 
@@ -33,6 +34,7 @@ export type Draft = {
   list: () => readonly Info[]
   get: (id: ID) => Info | undefined
   default: (id: ID | undefined) => void
+  permissions: (permissions: Info["permissions"]) => void
   update: (id: ID, fn: (agent: Types.DeepMutable<Info>) => void) => void
   remove: (id: ID) => void
 }
@@ -53,15 +55,25 @@ const layer = Layer.effect(
     const bus = yield* Bus.Service
     const state = State.create<Data, Draft>({
       name: "agent",
-      initial: () => ({ agents: new Map() }),
+      initial: () => ({ agents: new Map(), permissions: [] }),
       draft: (draft) => ({
         list: () => Array.fromIterable(draft.agents.values()) as Info[],
         get: (id) => draft.agents.get(id),
         default: (id) => {
           draft.default = id
         },
+        permissions: (permissions) => {
+          draft.permissions.push(...permissions)
+          for (const agent of draft.agents.values()) agent.permissions.push(...permissions)
+        },
         update: (id, fn) => {
-          const current = draft.agents.get(id) ?? (Info.empty(id) as Types.DeepMutable<Info>)
+          const defaults = Info.default(id)
+          const current =
+            draft.agents.get(id) ??
+            ({
+              ...defaults,
+              permissions: [...defaults.permissions, ...draft.permissions],
+            } as Types.DeepMutable<Info>)
           if (!draft.agents.has(id)) draft.agents.set(id, current)
           fn(current)
           current.id = id

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

@@ -58,7 +58,7 @@ export const Plugin = define({
           const files = yield* discover(fs, entry.path)
           return yield* Effect.forEach(files, (file) =>
             fs.readFileStringSafe(file.filepath).pipe(
-              Effect.map((content) => content && decode(file, content)),
+              Effect.map((content) => (content ? decode(file, content) : undefined)),
               Effect.catch(() => Effect.succeed(undefined)),
             ),
           ).pipe(

packages/core/src/plugin/agent.ts

@@ -2,15 +2,12 @@ export * as AgentPlugin from "./agent"
 
 import path from "path"
 import { define } from "@opencode-ai/plugin/effect/plugin"
-import { Effect } from "effect"
+import { Effect, Stream } from "effect"
 import { Agent } from "../agent"
 import { Global } from "@opencode-ai/util/global"
-import { Location } from "../location"
 import { Permission } from "../permission"
-
-// Combined output files written by the Shell service, e.g. `<data>/shell/<projectID>/<shellID>.out`.
-// Whitelisted so agents can read a command's full captured output without an external-directory prompt.
-const SHELL_OUTPUT_GLOB = path.join(Global.Path.data, "shell", "*", "*")
+import { Reference } from "../reference"
+import { Skill } from "../skill"
 
 const PROMPT_EXPLORE = `You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
 
@@ -100,38 +97,39 @@ Rules:
 export const Plugin = define({
   id: "opencode.agent",
   effect: Effect.fn(function* (ctx) {
-    const location = yield* Location.Service
-    const worktree = location.directory
-    const whitelistedDirs = [SHELL_OUTPUT_GLOB, path.join(Global.Path.tmp, "*")]
-    const readonlyExternalDirectory: Permission.Ruleset = [
-      { action: "external_directory", resource: "*", effect: "ask" },
-      ...whitelistedDirs.map(
+    const global = yield* Global.Service
+    const references = yield* Reference.Service
+    const skills = yield* Skill.Service
+    const externalDirectories: { current: Permission.Ruleset } = { current: [] }
+    const refreshExternalDirectories = Effect.fn("AgentPlugin.refreshExternalDirectories")(function* () {
+      const [referenceList, skillSources, skillList] = yield* Effect.all([
+        references.list(),
+        skills.sources(),
+        skills.list(),
+      ])
+      externalDirectories.current = Array.from(
+        new Set([
+          path.join(global.data, "shell", "*", "*"),
+          path.join(global.data, "tool-output", "*"),
+          path.join(global.tmp, "*"),
+          path.join(global.config, "*"),
+          ...referenceList.map((reference) => path.join(reference.path, "*")),
+          ...skillSources.flatMap((source) => (source.type === "directory" ? [path.join(source.path, "*")] : [])),
+          ...skillList.map((skill) => path.join(path.dirname(skill.location), "*")),
+        ]),
         (resource): Permission.Rule => ({ action: "external_directory", resource, effect: "allow" }),
-      ),
-    ]
-    const defaults: Permission.Ruleset = [
-      { action: "*", resource: "*", effect: "allow" },
-      ...readonlyExternalDirectory,
-      { action: "question", resource: "*", effect: "deny" },
-      { action: "plan_enter", resource: "*", effect: "deny" },
-      { action: "plan_exit", resource: "*", effect: "deny" },
-      { action: "read", resource: "*", effect: "allow" },
-      { action: "read", resource: "*.env", effect: "ask" },
-      { action: "read", resource: "*.env.*", effect: "ask" },
-      { action: "read", resource: "*.env.example", effect: "allow" },
-    ]
+      )
+    })
+
+    yield* refreshExternalDirectories()
 
     yield* ctx.agent.transform((draft) => {
+      draft.permissions(externalDirectories.current)
       draft.update(Agent.defaultID, (item) => {
         item.name = Agent.Name.make("Build")
         item.description = "The default agent. Executes tools based on configured permissions."
         item.mode = "primary"
-        item.permissions.push(
-          ...Permission.merge(defaults, [
-            { action: "question", resource: "*", effect: "allow" },
-            { action: "plan_enter", resource: "*", effect: "allow" },
-          ]),
-        )
+        item.permissions.push({ action: "question", resource: "*", effect: "allow" })
       })
 
       draft.update(Agent.ID.make("plan"), (item) => {
@@ -139,18 +137,8 @@ export const Plugin = define({
         item.description = "Plan mode. Disallows all edit tools."
         item.mode = "primary"
         item.permissions.push(
-          ...Permission.merge(defaults, [
-            { action: "question", resource: "*", effect: "allow" },
-            { action: "plan_exit", resource: "*", effect: "allow" },
-            { action: "external_directory", resource: path.join(Global.Path.data, "plans", "*"), effect: "allow" },
-            { action: "edit", resource: "*", effect: "deny" },
-            { action: "edit", resource: path.join(".opencode", "plans", "*.md"), effect: "allow" },
-            {
-              action: "edit",
-              resource: path.relative(worktree, path.join(Global.Path.data, "plans", "*.md")),
-              effect: "allow",
-            },
-          ]),
+          { action: "question", resource: "*", effect: "allow" },
+          { action: "edit", resource: "*", effect: "deny" },
         )
       })
 
@@ -159,7 +147,10 @@ export const Plugin = define({
         item.description =
           "General-purpose agent for researching complex questions and executing multi-step tasks. Use this agent to execute multiple units of work in parallel."
         item.mode = "subagent"
-        item.permissions.push(...Permission.merge(defaults, [{ action: "subagent", resource: "*", effect: "deny" }]))
+        item.permissions.push(
+          { action: "question", resource: "*", effect: "deny" },
+          { action: "subagent", resource: "*", effect: "deny" },
+        )
       })
 
       draft.update(Agent.ID.make("explore"), (item) => {
@@ -170,7 +161,6 @@ export const Plugin = define({
         item.mode = "subagent"
         item.permissions.push(
           ...Permission.merge(
-            defaults,
             [
               { action: "*", resource: "*", effect: "deny" },
               { action: "grep", resource: "*", effect: "allow" },
@@ -180,7 +170,7 @@ export const Plugin = define({
               { action: "read", resource: "*", effect: "allow" },
               { action: "subagent", resource: "*", effect: "deny" },
             ],
-            readonlyExternalDirectory,
+            [{ action: "external_directory", resource: "*", effect: "ask" }, ...externalDirectories.current],
           ),
         )
       })
@@ -190,7 +180,7 @@ export const Plugin = define({
         item.mode = "primary"
         item.hidden = true
         item.system = PROMPT_COMPACTION
-        item.permissions.push(...Permission.merge(defaults, [{ action: "*", resource: "*", effect: "deny" }]))
+        item.permissions.push({ action: "*", resource: "*", effect: "deny" })
       })
 
       draft.update(Agent.ID.make("title"), (item) => {
@@ -198,7 +188,7 @@ export const Plugin = define({
         item.mode = "primary"
         item.hidden = true
         item.system = PROMPT_TITLE
-        item.permissions.push(...Permission.merge(defaults, [{ action: "*", resource: "*", effect: "deny" }]))
+        item.permissions.push({ action: "*", resource: "*", effect: "deny" })
       })
 
       draft.update(Agent.ID.make("summary"), (item) => {
@@ -206,8 +196,13 @@ export const Plugin = define({
         item.mode = "primary"
         item.hidden = true
         item.system = PROMPT_SUMMARY
-        item.permissions.push(...Permission.merge(defaults, [{ action: "*", resource: "*", effect: "deny" }]))
+        item.permissions.push({ action: "*", resource: "*", effect: "deny" })
       })
     })
+    yield* ctx.event.subscribe().pipe(
+      Stream.filter((event) => event.type === "reference.updated" || event.type === "skill.updated"),
+      Stream.runForEach(() => refreshExternalDirectories().pipe(Effect.andThen(ctx.agent.reload()))),
+      Effect.forkScoped({ startImmediately: true }),
+    )
   }),
 })

packages/core/src/plugin/host.ts

@@ -96,6 +96,7 @@ export const make = Effect.fn("PluginHost.make")(function* (plugin: import("../p
             list: () => mutable(draft.list()),
             get: (id) => mutable(draft.get(Agent.ID.make(id))),
             default: (id) => draft.default(id === undefined ? undefined : Agent.ID.make(id)),
+            permissions: draft.permissions,
             update: (id, update) => draft.update(Agent.ID.make(id), update),
             remove: (id) => draft.remove(Agent.ID.make(id)),
           })

packages/core/src/plugin/internal.ts

@@ -159,9 +159,9 @@ const pre = [
 
 const post = [
   ConfigReferencePlugin.Plugin,
+  ConfigSkillPlugin.Plugin,
   ConfigAgentPlugin.Plugin,
   ConfigCommandPlugin.Plugin,
-  ConfigSkillPlugin.Plugin,
   ConfigProviderPlugin.Plugin,
   ConfigWebSearchPlugin.Plugin,
   VariantPlugin.Plugin,

packages/core/src/tool/plugin/shell.ts

@@ -6,6 +6,7 @@ import type { Content } from "@opencode-ai/schema/tool"
 import type { Context as PluginContext } from "@opencode-ai/plugin/effect/plugin"
 import { Deferred, Effect, Schema, Scope } from "effect"
 import { FSUtil } from "@opencode-ai/util/fs-util"
+import { Global } from "@opencode-ai/util/global"
 import { LocationMutation } from "../../location-mutation"
 import { Permission } from "../../permission"
 import { PluginRuntime } from "../../plugin/runtime"
@@ -35,6 +36,7 @@ const description = (shell?: string) =>
     ...(shell ? [`Commands run on ${OS} using ${shell}.`] : []),
     "Quote file paths containing spaces or special characters.",
     "Prefer dedicated tools over shell commands when possible.",
+    `Use \`${Global.Path.tmp}\` for temporary work outside the workspace. It already exists and is pre-approved for external-directory access.`,
     "When output is large, the full result is saved to a file and a truncated preview is returned.",
     "Rely on automatic truncation unless filtering the output is more useful.",
     "Commands accept an optional timeout, background commands have no timeout by default.",

packages/core/test/agent.test.ts

@@ -8,13 +8,36 @@ import { LayerNode } from "@opencode-ai/util/effect/layer-node"
 import { Location } from "@opencode-ai/core/location"
 import { Permission } from "@opencode-ai/core/permission"
 import { AgentPlugin } from "@opencode-ai/core/plugin/agent"
+import { Reference } from "@opencode-ai/core/reference"
 import { AbsolutePath } from "@opencode-ai/core/schema"
+import { Skill } from "@opencode-ai/core/skill"
+import { Global } from "@opencode-ai/util/global"
 import { location } from "./fixture/location"
 import { testEffect } from "./lib/effect"
 import { agentHost, host } from "./plugin/host"
 
 const testLocation = location({ directory: AbsolutePath.make("/project") })
 const locationLayer = Layer.succeed(Location.Service, Location.Service.of(testLocation))
+const referencePath = AbsolutePath.make("/references/docs")
+const skillPath = AbsolutePath.make("/skills/team")
+const references = Reference.Service.of({
+  list: () =>
+    Effect.succeed([
+      Reference.Info.make({
+        name: "docs",
+        path: referencePath,
+        source: Reference.LocalSource.make({ type: "local", path: referencePath }),
+      }),
+    ]),
+  transform: () => Effect.succeed({ dispose: Effect.void }),
+  reload: () => Effect.void,
+})
+const skills = Skill.Service.of({
+  sources: () => Effect.succeed([Skill.DirectorySource.make({ type: "directory", path: skillPath })]),
+  list: () => Effect.succeed([]),
+  transform: () => Effect.succeed({ dispose: Effect.void }),
+  reload: () => Effect.void,
+})
 
 const it = testEffect(
   AppNodeBuilder.build(LayerNode.group([Agent.node, Bus.node, Location.node]), [
@@ -120,13 +143,31 @@ describe("Agent", () => {
       const id = Agent.ID.make("custom")
 
       yield* agent.transform((editor) => editor.update(id, () => {}))
-      expect(yield* agent.get(id)).toEqual(Agent.Info.empty(id))
+      expect(yield* agent.get(id)).toEqual(Agent.Info.default(id))
 
       yield* agent.transform((editor) => editor.remove(id))
       expect(yield* agent.get(id)).toBeUndefined()
     }),
   )
 
+  it.effect("applies runtime permissions to existing and future agents", () =>
+    Effect.gen(function* () {
+      const agent = yield* Agent.Service
+      const existing = Agent.ID.make("existing")
+      const future = Agent.ID.make("future")
+      const permission = { action: "external_directory", resource: "/tmp/*", effect: "allow" } as const
+
+      yield* agent.transform((draft) => {
+        draft.update(existing, () => {})
+        draft.permissions([permission])
+        draft.update(future, () => {})
+      })
+
+      expect((yield* agent.get(existing))?.permissions).toContainEqual(permission)
+      expect((yield* agent.get(future))?.permissions).toContainEqual(permission)
+    }),
+  )
+
   it.effect("does not ambiently opt built-in agents into bash", () =>
     Effect.gen(function* () {
       const agent = yield* Agent.Service
@@ -135,6 +176,9 @@ describe("Agent", () => {
           agent: agentHost(agent),
         }),
       ).pipe(
+        Effect.provideService(Global.Service, Global.Service.of(Global.make())),
+        Effect.provideService(Reference.Service, references),
+        Effect.provideService(Skill.Service, skills),
         Effect.provideService(
           Location.Service,
           Location.Service.of(location({ directory: AbsolutePath.make("/project") })),
@@ -152,6 +196,12 @@ describe("Agent", () => {
         "title",
       ])
       expect((yield* agent.get(Agent.defaultID))?.system).toBeUndefined()
+      const permissions = (yield* agent.get(Agent.defaultID))?.permissions ?? []
+      expect(Permission.evaluate("external_directory", "/references/docs/*", permissions).effect).toBe("allow")
+      expect(Permission.evaluate("external_directory", "/skills/team/*", permissions).effect).toBe("allow")
+      expect(
+        Permission.evaluate("external_directory", `${Global.Path.config}/*`, permissions).effect,
+      ).toBe("allow")
       for (const item of agents) {
         expect(item.permissions.some((rule) => rule.action === "bash" && rule.effect !== "deny")).toBe(false)
       }
@@ -166,6 +216,9 @@ describe("Agent", () => {
           agent: agentHost(agent),
         }),
       ).pipe(
+        Effect.provideService(Global.Service, Global.Service.of(Global.make())),
+        Effect.provideService(Reference.Service, references),
+        Effect.provideService(Skill.Service, skills),
         Effect.provideService(
           Location.Service,
           Location.Service.of(location({ directory: AbsolutePath.make("/project") })),

packages/core/test/config/agent.test.ts

@@ -23,6 +23,9 @@ const decode = Schema.decodeUnknownSync(Config.Info)
 const defaultPermissions = [
   { action: "*", resource: "*", effect: "allow" },
   { action: "external_directory", resource: "*", effect: "ask" },
+  { action: "read", resource: "*.env", effect: "ask" },
+  { action: "read", resource: "*.env.*", effect: "ask" },
+  { action: "read", resource: "*.env.example", effect: "allow" },
 ] satisfies Permission.Ruleset
 
 test("rejects named agent color tokens", () => {
@@ -266,6 +269,7 @@ permissions:
 Use native v2 fields.`,
             )
             await fs.writeFile(path.join(tmp.path, "agents", "disabled.md"), "---\ndisabled: true\n---\nDisabled")
+            await fs.writeFile(path.join(tmp.path, "agents", "empty.md"), "")
             await fs.writeFile(path.join(tmp.path, "modes", "plan.md"), "Make a plan.")
           })
           const agents = yield* Agent.Service
@@ -295,6 +299,7 @@ Use native v2 fields.`,
             permissions: [...defaultPermissions, { action: "edit", resource: "*", effect: "deny" }],
           })
           expect(yield* agents.get(Agent.ID.make("disabled"))).toBeUndefined()
+          expect(yield* agents.get(Agent.ID.make("empty"))).toBeUndefined()
           expect(yield* agents.get(Agent.ID.make("plan"))).toMatchObject({ system: "Make a plan.", mode: "primary" })
         }),
       ),

packages/core/test/config/reload.test.ts

@@ -38,10 +38,10 @@ describe("config plugin reloads", () => {
       const host = yield* PluginHost.make(plugins)
       const test = yield* Config.Test
 
+      yield* ConfigReferencePlugin.Plugin.effect(host)
       yield* ConfigAgentPlugin.Plugin.effect(host)
       yield* ConfigCommandPlugin.Plugin.effect(host)
       yield* ConfigSkillPlugin.Plugin.effect(host)
-      yield* ConfigReferencePlugin.Plugin.effect(host)
       yield* ConfigProviderPlugin.Plugin.effect(host)
 
       expect((yield* agents.get(Agent.ID.make("first")))?.description).toBe("First agent")

packages/core/test/mcp-instructions.test.ts

@@ -12,7 +12,7 @@ import { readInitial, readUpdate } from "./lib/instructions"
 const build = Agent.ID.make("build")
 
 const selection = (permissions: Permission.Ruleset = []) => {
-  const info = Agent.Info.make({ ...Agent.Info.empty(build), permissions })
+  const info = Agent.Info.make({ ...Agent.Info.default(build), permissions })
   return { id: info.id, info }
 }
 

packages/core/test/plugin/host.ts

@@ -145,6 +145,7 @@ export function agentHost(agent: Agent.Interface): Plugin.Context["agent"] {
             return value && agentInfo(value)
           },
           default: (id) => draft.default(id === undefined ? undefined : Agent.ID.make(id)),
+          permissions: draft.permissions,
           update: (id, update) =>
             draft.update(Agent.ID.make(id), (value) => {
               const current = agentInfo(value)

packages/core/test/shared-schema.test.ts

@@ -166,7 +166,7 @@ test("Core reuses the canonical shared schemas", async () => {
   ]
   for (const [core, shared] of schemas) expect(core).toBe(shared)
 
-  expect(Agent.Info.empty(Agent.ID.make("test"))).toEqual(Agent.Info.empty(Agent.ID.make("test")))
+  expect(Agent.Info.default(Agent.ID.make("test"))).toEqual(Agent.Info.default(Agent.ID.make("test")))
   expect(coreModel.Info.default(coreProvider.ID.make("test"), coreModel.ID.make("model"))).toEqual(
     Model.Info.default(Provider.ID.make("test"), Model.ID.make("model")),
   )

packages/core/test/skill/instructions.test.ts

@@ -47,7 +47,7 @@ const layer = (list: () => Skill.Info[]) =>
 describe("SkillInstructions", () => {
   it.effect("renders described agent skills and updates the complete available list", () => {
     const agent = Agent.Info.make({
-      ...Agent.Info.empty(build),
+      ...Agent.Info.default(build),
       permissions: [{ action: "skill", resource: "denied", effect: "deny" }],
     })
     let skills = [hidden, denied, manual, effect]
@@ -80,7 +80,7 @@ describe("SkillInstructions", () => {
   })
 
   it.effect("announces added and removed skills as deltas without restating the list", () => {
-    const agent = Agent.Info.make(Agent.Info.empty(build))
+    const agent = Agent.Info.make(Agent.Info.default(build))
     const debugging = Skill.Info.make({
       id: Skill.ID.make("debugging"),
       name: Skill.Name.make("Debugging"),
@@ -117,7 +117,7 @@ describe("SkillInstructions", () => {
   })
 
   it.effect("restates the full skill list when a description changes", () => {
-    const agent = Agent.Info.make(Agent.Info.empty(build))
+    const agent = Agent.Info.make(Agent.Info.default(build))
     let skills = [effect]
     return Effect.gen(function* () {
       const instructions = yield* SkillInstructions.Service
@@ -138,7 +138,7 @@ describe("SkillInstructions", () => {
 
   it.effect("omits instructions when the selected agent denies all skills", () => {
     const agent = Agent.Info.make({
-      ...Agent.Info.empty(build),
+      ...Agent.Info.default(build),
       permissions: [{ action: "skill", resource: "*", effect: "deny" }],
     })
     return Effect.gen(function* () {
@@ -149,7 +149,7 @@ describe("SkillInstructions", () => {
 
   it.effect("omits instructions when a resource-specific denial follows the global denial", () => {
     const agent = Agent.Info.make({
-      ...Agent.Info.empty(build),
+      ...Agent.Info.default(build),
       permissions: [
         { action: "skill", resource: "*", effect: "deny" },
         { action: "skill", resource: "hidden", effect: "deny" },
@@ -163,7 +163,7 @@ describe("SkillInstructions", () => {
 
   it.effect("retains specifically allowed skills after a global denial", () => {
     const agent = Agent.Info.make({
-      ...Agent.Info.empty(build),
+      ...Agent.Info.default(build),
       permissions: [
         { action: "skill", resource: "*", effect: "deny" },
         { action: "skill", resource: "effect", effect: "allow" },
@@ -179,7 +179,7 @@ describe("SkillInstructions", () => {
 
   it.effect("omits instructions when a specifically allowed skill is denied again", () => {
     const agent = Agent.Info.make({
-      ...Agent.Info.empty(build),
+      ...Agent.Info.default(build),
       permissions: [
         { action: "skill", resource: "*", effect: "deny" },
         { action: "skill", resource: "effect", effect: "allow" },

packages/plugin/src/effect/agent.ts

@@ -7,6 +7,7 @@ export interface AgentDraft {
   list(): readonly Types.DeepMutable<Agent.Info>[]
   get(id: string): Types.DeepMutable<Agent.Info> | undefined
   default(id: string | undefined): void
+  permissions(permissions: Agent.Info["permissions"]): void
   update(id: string, update: (agent: Types.DeepMutable<Agent.Info>) => void): void
   remove(id: string): void
 }

packages/plugin/src/promise/agent.ts

@@ -7,6 +7,7 @@ export interface AgentDraft {
   list(): readonly DeepMutable<Agent.Info>[]
   get(id: string): DeepMutable<Agent.Info> | undefined
   default(id: string | undefined): void
+  permissions(permissions: Agent.Info["permissions"]): void
   update(id: string, update: (agent: DeepMutable<Agent.Info>) => void): void
   remove(id: string): void
 }

packages/schema/src/agent.ts

@@ -36,7 +36,7 @@ export const Info = Schema.Struct({
   .annotate({ identifier: "Agent.Info" })
   .pipe(
     statics(() => ({
-      empty: (id: ID) =>
+      default: (id: ID) =>
         ({
           id,
           name: Name.make(id),
@@ -46,6 +46,9 @@ export const Info = Schema.Struct({
           permissions: [
             { action: "*", resource: "*", effect: "allow" },
             { action: "external_directory", resource: "*", effect: "ask" },
+            { action: "read", resource: "*.env", effect: "ask" },
+            { action: "read", resource: "*.env.*", effect: "ask" },
+            { action: "read", resource: "*.env.example", effect: "allow" },
           ],
         }) satisfies Info,
     })),

packages/tui/src/mini/tool.ts

@@ -125,7 +125,6 @@ type ToolName =
   | "webfetch"
   | "websearch"
   | "skill"
-  | "plan_exit"
 
 type ToolRule = {
   view: ToolView
@@ -516,15 +515,6 @@ function runLsp(p: ToolProps): ToolInline {
   }
 }
 
-function runPlanExit(p: ToolProps): ToolInline {
-  return {
-    icon: "→",
-    title: "Switching to build agent",
-    mode: "block",
-    body: p.frame.status === "completed" ? p.frame.output : undefined,
-  }
-}
-
 function patchTitle(file: PatchFile, directory?: string): string {
   if (file.status === "added") {
     return `# Created ${toolPath(file.file, { directory })}`
@@ -1077,16 +1067,6 @@ const TOOL_RULES = {
       start: scrollSkillStart,
     },
   },
-  plan_exit: {
-    view: {
-      output: true,
-      final: false,
-    },
-    run: runPlanExit,
-    scroll: {
-      start: () => "",
-    },
-  },
 } as const satisfies ToolRegistry
 
 function key(name: string): name is ToolName {

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

@@ -81,8 +81,7 @@ current built-in actions use these resources:
 | `<server>_<tool>` | `*` for an MCP tool; unsupported characters in both names become `_` |
 | `execute` | `*`; controls availability of the Code Mode dispatcher, while each nested tool still enforces its own permission |
 
-Built-in agent policy also reserves `plan_enter` and `plan_exit` for plan-mode
-transitions. `doom_loop` and `lsp` are not current V2 Core permission actions.
+`doom_loop` and `lsp` are not current V2 Core permission actions.
 
 ## External directories
 
@@ -132,7 +131,9 @@ matching, so authorize only trusted directory boundaries.
 
 ## Defaults
 
-The evaluator's fallback is `ask`, but shipped agents include ordered defaults:
+Every agent, including custom agents, starts with ordered defaults that allow
+tools, ask for external directories, ask for `.env` reads, and allow
+`.env.example` reads. Shipped agents then add their own policies:
 
 | Agent | Effective default policy |
 | --- | --- |
@@ -153,8 +154,11 @@ The base read rules are ordered as follows:
 ]
 ```
 
-OpenCode also permits its managed tool-output and temporary directories where
-needed. These exceptions do not grant general external-directory access.
+OpenCode also permits its managed tool-output, shell-output, temporary, global
+configuration, configured reference, and discovered skill directories. These
+exceptions apply only to the external-directory boundary for every agent; the
+underlying action still uses its own permission rules. Later global and
+agent-specific rules can override them.
 
 ## Agent overrides