test(core): make websocket overflow fixture deterministic

.changeset/session-capabilities.md

@@ -0,0 +1,8 @@
+---
+"@opencode-ai/core": minor
+"@opencode-ai/schema": patch
+---
+
+Open durable sessions with in-process model, tool, instruction, and permission capabilities. Live Sources update at safe boundaries through existing instruction epochs, while capability replacement waits for the next busy period. Capability-owned sessions remain pending after restart until their host reopens and drives them.
+
+Close an open's in-process capabilities after settlement without deleting durable history. Tool executors may yield domain errors, which normalize to tool failures while canonical permission declines retain their interruption behavior.

packages/core/src/effect/websocket-constructor.ts

@@ -1,4 +1,5 @@
-import { NodeSocket } from "@effect/platform-node"
+// The platform barrel also exposes Redis and its optional native hash loader, which workerd cannot resolve.
+import { NodeWS } from "@effect/platform-node/NodeSocket"
 import { HttpProxyAgent } from "http-proxy-agent"
 import { HttpsProxyAgent } from "https-proxy-agent"
 import { Layer } from "effect"
@@ -80,8 +81,8 @@ const layer = Layer.succeed(Socket.WebSocketConstructor, (url, input) => {
     followRedirects: false,
   }
   const socket = config.protocols
-    ? new NodeSocket.NodeWS.WebSocket(url, config.protocols, native)
-    : new NodeSocket.NodeWS.WebSocket(url, native)
+    ? new NodeWS.WebSocket(url, config.protocols, native)
+    : new NodeWS.WebSocket(url, native)
   // oxlint-disable-next-line typescript-eslint/no-unsafe-type-assertion -- ws implements the WebSocket surface consumed by the AI transport.
   return socket as unknown as globalThis.WebSocket
 })

packages/core/src/image.ts

@@ -55,7 +55,7 @@ export interface Interface extends State.Transformable<Draft> {
 
 export class Service extends Context.Service<Service, Interface>()("@opencode/Image") {}
 
-const layer = Layer.effect(
+export const layer = Layer.effect(
   Service,
   Effect.gen(function* () {
     const state = State.create<Limits, Draft>({

packages/core/src/job.ts

@@ -402,14 +402,7 @@ export const make = Effect.gen(function* () {
   })
 
   const pendingBackground: Interface["pendingBackground"] = Effect.gen(function* () {
-    const recovered: Background[] = []
-    let after: string | undefined
-    do {
-      const page = yield* kv.scan({ prefix: backgroundPrefix, after })
-      recovered.push(...Array.filterMap(page.entries, (entry) => decodeBackground(entry.value)))
-      after = page.next
-    } while (after)
-    return recovered
+    return Array.filterMap(yield* kv.scanAll(backgroundPrefix), (entry) => decodeBackground(entry.value))
   }).pipe(Effect.withSpan("Job.pendingBackground"))
 
   const completeBackground: Interface["completeBackground"] = Effect.fn("Job.completeBackground")((notificationID) =>

packages/core/src/kv.ts

@@ -29,6 +29,7 @@ export interface Interface {
   readonly set: (key: string, value: Value) => Effect.Effect<void>
   readonly remove: (key: string) => Effect.Effect<void>
   readonly scan: (options: ScanOptions) => Effect.Effect<ScanResult>
+  readonly scanAll: (prefix: string) => Effect.Effect<readonly Entry[]>
 }
 
 export class Service extends Context.Service<Service, Interface>()("@opencode/KV") {}
@@ -37,6 +38,28 @@ const layer = Layer.effect(
   Service,
   Effect.gen(function* () {
     const db = (yield* Database.Service).db
+    const scan: Interface["scan"] = Effect.fn("KV.scan")(function* (options) {
+      const limit = Number.isNaN(options.limit) ? 100 : Math.min(Math.max(Math.floor(options.limit ?? 100), 1), 1000)
+      const end = prefixEnd(options.prefix)
+      const rows = yield* db
+        .select({ key: KVTable.key, value: KVTable.value })
+        .from(KVTable)
+        .where(
+          and(
+            options.prefix === "" ? undefined : gte(KVTable.key, options.prefix),
+            end === undefined ? undefined : lt(KVTable.key, end),
+            options.after === undefined ? undefined : gt(KVTable.key, options.after),
+          ),
+        )
+        .orderBy(asc(KVTable.key))
+        .limit(limit + 1)
+        .all()
+        .pipe(Effect.orDie)
+      const entries = rows.slice(0, limit)
+      if (rows.length <= limit) return { entries }
+      return { entries, next: entries[entries.length - 1].key }
+    })
+
     return Service.of({
       get: Effect.fn("KV.get")(function* (key) {
         return (yield* db
@@ -57,26 +80,16 @@ const layer = Layer.effect(
       remove: Effect.fn("KV.remove")(function* (key) {
         yield* db.delete(KVTable).where(eq(KVTable.key, key)).run().pipe(Effect.orDie)
       }),
-      scan: Effect.fn("KV.scan")(function* (options) {
-        const limit = Number.isNaN(options.limit) ? 100 : Math.min(Math.max(Math.floor(options.limit ?? 100), 1), 1000)
-        const end = prefixEnd(options.prefix)
-        const rows = yield* db
-          .select({ key: KVTable.key, value: KVTable.value })
-          .from(KVTable)
-          .where(
-            and(
-              options.prefix === "" ? undefined : gte(KVTable.key, options.prefix),
-              end === undefined ? undefined : lt(KVTable.key, end),
-              options.after === undefined ? undefined : gt(KVTable.key, options.after),
-            ),
-          )
-          .orderBy(asc(KVTable.key))
-          .limit(limit + 1)
-          .all()
-          .pipe(Effect.orDie)
-        const entries = rows.slice(0, limit)
-        if (rows.length <= limit) return { entries }
-        return { entries, next: entries[entries.length - 1].key }
+      scan,
+      scanAll: Effect.fn("KV.scanAll")(function* (prefix) {
+        const entries: Entry[] = []
+        let after: string | undefined
+        do {
+          const page = yield* scan({ prefix, after, limit: 1000 })
+          entries.push(...page.entries)
+          after = page.next
+        } while (after !== undefined)
+        return entries
       }),
     })
   }),

packages/core/src/permission.ts

@@ -100,6 +100,10 @@ export function merge(...rulesets: Permission.Ruleset[]): Permission.Ruleset {
   return rulesets.flat()
 }
 
+export function relevant(input: Pick<Request, "action">, rules: Permission.Ruleset) {
+  return rules.filter((rule) => Wildcard.match(input.action, rule.action))
+}
+
 export interface Interface {
   readonly ask: (input: AssertInput) => Effect.Effect<AskResult, SessionErrors.NotFoundError>
   readonly assert: (input: AssertInput) => Effect.Effect<void, Error | SessionErrors.NotFoundError>
@@ -161,10 +165,6 @@ const layer = Layer.effect(
       return input.resources.some((resource) => evaluate(input.action, resource, rules).effect === "deny")
     }
 
-    function relevant(input: AssertInput, rules: Permission.Ruleset) {
-      return rules.filter((rule) => Wildcard.match(input.action, rule.action))
-    }
-
     const evaluateInput = Effect.fnUntraced(function* (input: AssertInput) {
       const rules = yield* configured(input.sessionID, input.agent)
       if (denied(input, rules)) return { effect: "deny" as const, rules }

packages/core/src/permissions.ts

@@ -0,0 +1,38 @@
+export * as Permissions from "./permissions.js"
+
+import { Effect } from "effect"
+import { Permission } from "./permission.js"
+import type { SessionSchema } from "./session/schema.js"
+import { Source } from "./source.js"
+
+export interface Interface {
+  readonly visibility: Source.Interface<Permission.Ruleset>
+  readonly ask: (
+    session: SessionSchema.Info,
+    request: Omit<Permission.AssertInput, "sessionID" | "agent">,
+  ) => Effect.Effect<void, Permission.Error | Permission.DeclinedError>
+}
+
+export const allowAll: Interface = {
+  visibility: Source.constant([{ action: "*", resource: "*", effect: "allow" }]),
+  ask: () => Effect.void,
+}
+
+export function rules(source: Source.Value<Permission.Ruleset>): Interface {
+  const visibility = Source.from(source)
+  return {
+    visibility,
+    ask: Effect.fn("Permissions.ask")(function* (session, request) {
+      const rules = yield* visibility.get(session)
+      if (
+        request.resources.every((resource) => Permission.evaluate(request.action, resource, rules).effect === "allow")
+      )
+        return
+      return yield* new Permission.BlockedError({
+        rules: Permission.relevant(request, rules),
+        permission: request.action,
+        resources: request.resources,
+      })
+    }),
+  }
+}

packages/core/src/plugin/hooks.ts

@@ -60,7 +60,7 @@ export interface Interface {
 
 export class Service extends Context.Service<Service, Interface>()("@opencode/PluginHooks") {}
 
-const layer = Layer.effect(
+export const layer = Layer.effect(
   Service,
   Effect.gen(function* () {
     const callbacks = new Map<string, Entry[]>()

packages/core/src/project.ts

@@ -46,6 +46,15 @@ export interface Resolved {
   readonly vcsBackend?: string
 }
 
+export function markerless(directory: AbsolutePath): Resolved {
+  return {
+    id: ID.make(Hash.fast(`directory:${directory}`)),
+    directory,
+    canonical: directory,
+    vcs: undefined,
+  }
+}
+
 // Keep this filesystem-only; permission checks use it and should not execute VCS commands.
 export const root = Effect.fn("Project.root")(function* (
   fs: FSUtil.Interface,
@@ -361,12 +370,7 @@ const layer = Layer.effect(
         })
       }
 
-      return yield* persist({
-        id: ID.make(Hash.fast(`directory:${directory}`)),
-        directory,
-        canonical: directory,
-        vcs: undefined,
-      })
+      return yield* persist(markerless(directory))
     })
 
     return Service.of({ list, update, resolve })

packages/core/src/session.ts

@@ -1,5 +1,6 @@
 export * as Session from "./session.js"
 export * from "./session/schema.js"
+export type { OpenInput, Handle } from "./session/capabilities.js"
 
 import { Cause, Effect, Layer, Schema, Context, RcMap, Stream, Scope } from "effect"
 import { ListAnchor } from "@opencode-ai/schema/session"
@@ -56,6 +57,8 @@ import { fileURLToPath } from "url"
 import { SessionEnvironment } from "./session/environment.js"
 import { SessionHistory } from "./session/history.js"
 import { InstructionEntry } from "./session/instruction-entry.js"
+import { SessionResolve } from "./session/resolve.js"
+import type { SessionCapabilities } from "./session/capabilities.js"
 
 // get project -> project.locations
 //
@@ -188,6 +191,7 @@ export const MessageNotFoundError = SessionRevert.MessageNotFoundError
 export type MessageNotFoundError = SessionRevert.MessageNotFoundError
 
 export interface Interface {
+  readonly open: (input: SessionCapabilities.OpenInput) => Effect.Effect<SessionCapabilities.Handle>
   readonly list: (input?: ListInput) => Effect.Effect<{
     readonly data: SessionSchema.Info[]
   }>
@@ -342,6 +346,7 @@ const layer = Layer.effect(
     const execution = yield* SessionExecution.Service
     const store = yield* SessionStore.Service
     const locations = yield* LocationServiceMap.Service
+    const resolve = yield* SessionResolve.Service
     const fs = yield* FSUtil.Service
     const jobs = yield* Job.Service
     const environments = yield* SessionEnvironment.Service
@@ -349,6 +354,9 @@ const layer = Layer.effect(
     const activeShells = new Set<SessionSchema.ID>()
     const shellLocks = KeyedMutex.makeUnsafe<SessionSchema.ID>()
     const closeTransport = Effect.fn("Session.closeTransport")(function* (session: SessionSchema.Info) {
+      const resolved = yield* resolve.resolve(session)
+      if (resolved.status === "attached") return yield* resolved.capabilities.transport.close(session.id)
+      if (resolved.status === "owned-detached") return
       const location = Location.Ref.make({
         directory: session.location.directory,
         workspaceID: session.location.workspaceID,
@@ -357,7 +365,7 @@ const layer = Layer.effect(
       yield* SessionModelTransport.Service.use((transport) => transport.close(session.id)).pipe(
         Effect.provide(locations.get(location)),
       )
-    })
+    }, Effect.scoped)
     const isDurableSessionEvent = Schema.is(SessionEvent.Durable)
     const persistProject = (project: Project.Resolved) => upsertProject(db, project).pipe(Effect.orDie)
 
@@ -384,61 +392,90 @@ const layer = Layer.effect(
         }),
       )
 
+    const create = Effect.fn("Session.create")(function* (input: CreateInput, resolved?: Project.Resolved) {
+      const sessionID = input.id ?? SessionSchema.ID.create()
+      const recorded = yield* store.get(sessionID)
+      if (recorded) return recorded
+      const parent = input.parentID ? yield* store.get(input.parentID) : undefined
+      if (input.parentID && parent === undefined) return yield* new NotFoundError({ sessionID: input.parentID })
+      const location = parent?.location ?? input.location
+      if (location === undefined)
+        return yield* Effect.die(new Error("Session.create requires either location or an existing parentID"))
+      const project = resolved ?? (yield* projects.resolve(location.directory))
+      yield* persistProject(project)
+      const projected = yield* bus
+        .publish(
+          SessionEvent.Created,
+          {
+            sessionID,
+            slug: Slug.create(),
+            version: app.version,
+            projectID: project.id,
+            parentID: input.parentID,
+            location,
+            subpath: RelativePath.make(path.relative(project.directory, location.directory).replaceAll("\\", "/")),
+            title: input.title,
+            agent: input.agent,
+            model: input.model
+              ? {
+                  id: Model.ID.make(input.model.id),
+                  providerID: input.model.providerID,
+                  variant: input.model.variant,
+                }
+              : undefined,
+          },
+          { location },
+        )
+        .pipe(
+          Effect.as({ type: "created" } as const),
+          Effect.catchDefect((defect) => {
+            if (!(defect instanceof SessionProjector.SessionAlreadyProjected)) {
+              return Effect.die(defect)
+            }
+            // Concurrent creation lost the projection race. The existing Session identity wins.
+            return store
+              .get(sessionID)
+              .pipe(
+                Effect.flatMap((session) =>
+                  session ? Effect.succeed({ type: "existing", session } as const) : Effect.die(defect),
+                ),
+              )
+          }),
+        )
+      if (projected.type === "existing") return projected.session
+      // TODO: Restore recorded sessions onto replacement synchronized workspaces in a future API slice.
+      return yield* result.get(sessionID).pipe(Effect.orDie)
+    })
     const result = Service.of({
-      create: Effect.fn("Session.create")(function* (input) {
-        const sessionID = input.id ?? SessionSchema.ID.create()
-        const recorded = yield* store.get(sessionID)
-        if (recorded) return recorded
-        const parent = input.parentID ? yield* store.get(input.parentID) : undefined
-        if (input.parentID && parent === undefined) return yield* new NotFoundError({ sessionID: input.parentID })
-        const location = parent?.location ?? input.location
-        if (location === undefined)
-          return yield* Effect.die(new Error("Session.create requires either location or an existing parentID"))
-        const project = yield* projects.resolve(location.directory)
-        yield* persistProject(project)
-        const projected = yield* bus
-          .publish(
-            SessionEvent.Created,
-            {
-              sessionID,
-              slug: Slug.create(),
-              version: app.version,
-              projectID: project.id,
-              parentID: input.parentID,
-              location,
-              subpath: RelativePath.make(path.relative(project.directory, location.directory).replaceAll("\\", "/")),
-              title: input.title,
-              agent: input.agent,
-              model: input.model
-                ? {
-                    id: Model.ID.make(input.model.id),
-                    providerID: input.model.providerID,
-                    variant: input.model.variant,
-                  }
-                : undefined,
-            },
-            { location },
-          )
-          .pipe(
-            Effect.as({ type: "created" } as const),
-            Effect.catchDefect((defect) => {
-              if (!(defect instanceof SessionProjector.SessionAlreadyProjected)) {
-                return Effect.die(defect)
-              }
-              // Concurrent creation lost the projection race. The existing Session identity wins.
-              return store
-                .get(sessionID)
-                .pipe(
-                  Effect.flatMap((session) =>
-                    session ? Effect.succeed({ type: "existing", session } as const) : Effect.die(defect),
-                  ),
-                )
-            }),
-          )
-        if (projected.type === "existing") return projected.session
-        // TODO: Restore recorded sessions onto replacement synchronized workspaces in a future API slice.
-        return yield* result.get(sessionID).pipe(Effect.orDie)
-      }),
+      create,
+      open: Effect.fn("Session.open")((input) =>
+        Effect.uninterruptible(
+          Effect.gen(function* () {
+            const directory = AbsolutePath.make(process.cwd())
+            // Transitional placement is unused by supplied capabilities, but listings group
+            // these Sessions under the deterministic cwd-derived project. Adoption never moves it.
+            const session = yield* resolve.own(
+              create(
+                { id: input.id, title: input.title, location: Location.Ref.make({ directory }) },
+                Project.markerless(directory),
+              ).pipe(Effect.orDie),
+            )
+            const close = yield* resolve.attach(session.id, input)
+            return {
+              id: session.id,
+              prompt: (prompt) =>
+                Effect.gen(function* () {
+                  const admitted = yield* result.prompt({ ...prompt, sessionID: session.id, resume: false })
+                  if (prompt.resume !== false) yield* result.resume(session.id)
+                  return admitted
+                }),
+              resume: () => result.resume(session.id),
+              interrupt: (options) => result.interrupt(session.id, options),
+              close,
+            } satisfies SessionCapabilities.Handle
+          }),
+        ),
+      ),
       fork: Effect.fn("Session.fork")(function* (input) {
         const parent = yield* result.get(input.sessionID)
         const boundary = yield* db
@@ -511,6 +548,7 @@ const layer = Layer.effect(
         yield* Effect.forEach(children.data, (child) => result.remove(child.id), { concurrency: 1, discard: true })
         yield* environments.clear(sessionID)
         yield* bus.publish(SessionEvent.Deleted, { sessionID })
+        yield* resolve.remove(sessionID)
         yield* bus.remove(sessionID)
       }),
       list: Effect.fn("Session.list")(function* (input = {}) {
@@ -652,11 +690,33 @@ const layer = Layer.effect(
                 delivery: input.delivery ?? "steer",
               })
               if (existing) return existing
+              const resolved = yield* resolve.resolve(session)
+              // TODO: typed unavailable-operation errors belong to the capability-gated operations phase.
+              if (resolved.status === "owned-detached" && (input.files?.length || input.skills?.length))
+                return yield* SessionResolve.unavailable(session.id)
               const item = yield* restore(
-                preparePrompt(input, messageID).pipe(
-                  Effect.provide(locations.get(session.location)),
-                  Effect.provideService(FSUtil.Service, fs),
-                ),
+                (resolved.status === "unowned"
+                  ? Effect.gen(function* () {
+                      const plugins = yield* PluginSupervisor.Service
+                      yield* plugins.flush
+                      const hooks = yield* PluginHooks.Service
+                      return yield* preparePrompt(
+                        input,
+                        messageID,
+                        Effect.service(Image.Service),
+                        Effect.service(Skill.Service),
+                        hooks,
+                      )
+                    }).pipe(Effect.provide(locations.get(session.location)))
+                  : preparePrompt(
+                      input,
+                      messageID,
+                      resolved.status === "attached"
+                        ? Effect.succeed(resolved.capabilities.image)
+                        : SessionResolve.unavailable(session.id),
+                      Effect.undefined,
+                    )
+                ).pipe(Effect.provideService(FSUtil.Service, fs)),
               )
               // Commit a staged revert only after preparation succeeds, before admitting new work.
               if (session.revert) yield* SessionRevert.commit(session).pipe(Effect.provideService(Bus.Service, bus))
@@ -682,7 +742,7 @@ const layer = Layer.effect(
             }
             return admitted
           }),
-        ),
+        ).pipe(Effect.scoped),
       ),
       generate: Effect.fn("Session.generate")(function* (input) {
         const session = yield* result.get(input.sessionID)
@@ -770,6 +830,7 @@ const layer = Layer.effect(
       }),
       skill: Effect.fn("Session.skill")(function* (input) {
         const session = yield* result.get(input.sessionID)
+        if (resolve.status(session.id) !== "unowned") return yield* new SkillNotFoundError({ skill: input.skill })
         const skills = yield* Skill.Service.pipe(Effect.provide(locations.get(session.location)))
         const skill = yield* skills.get(input.skill)
         if (!skill) return yield* new SkillNotFoundError({ skill: input.skill })
@@ -1010,14 +1071,14 @@ function synthesizeTerminalShellInfo(started: ShellSchema.Info): ShellSchema.Inf
   }
 }
 
-const preparePrompt = Effect.fn("Session.preparePrompt")(function* (
+const preparePrompt = Effect.fn("Session.preparePrompt")(function* <RImage, RSkills>(
   request: Parameters<Interface["prompt"]>[0],
   messageID: SessionMessage.ID,
+  image: Effect.Effect<Image.Interface, never, RImage>,
+  skills: Effect.Effect<Skill.Interface | undefined, never, RSkills>,
+  hooks?: PluginHooks.Interface,
 ) {
-  const plugins = yield* PluginSupervisor.Service
-  yield* plugins.flush
-  const hooks = yield* PluginHooks.Service
-  const event = yield* hooks.trigger("session", "prompt", {
+  const initial: PluginHooks.Domains["session"]["prompt"] = {
     sessionID: request.sessionID,
     messageID,
     prompt: structuredClone({
@@ -1028,16 +1089,19 @@ const preparePrompt = Effect.fn("Session.preparePrompt")(function* (
     }),
     metadata: structuredClone(request.metadata),
     delivery: request.delivery ?? "steer",
-  })
+  }
+  // Supplied capabilities have no configured prompt interceptors; discovery owns those hooks.
+  const event = hooks ? yield* hooks.trigger("session", "prompt", initial) : initial
   const input = event.prompt
   const fs = yield* FSUtil.Service
   const files = input.files
-    ? yield* Effect.forEach(input.files, (file) => materializeAttachment(fs, file), { concurrency: 8 })
+    ? yield* Effect.forEach(input.files, (file) => materializeAttachment(fs, file, image), { concurrency: 8 })
     : undefined
   const requested = input.skills
   const selected = yield* Effect.gen(function* () {
     if (!requested?.length) return undefined
-    const skillService = yield* Skill.Service
+    const skillService = yield* skills
+    if (!skillService) return yield* new SkillNotFoundError({ skill: requested[0].id })
     const prepared = new Map<Skill.ID, Skill.Name>()
     return yield* Effect.forEach(requested, (attachment) =>
       Effect.gen(function* () {
@@ -1072,9 +1136,10 @@ const preparePrompt = Effect.fn("Session.preparePrompt")(function* (
 
 const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024
 
-const materializeAttachment = Effect.fn("Session.materializeAttachment")(function* (
+const materializeAttachment = Effect.fn("Session.materializeAttachment")(function* <R>(
   fs: FSUtil.Interface,
   input: PromptInput.FileAttachment,
+  image: Effect.Effect<Image.Interface, never, R>,
 ) {
   const resolved = input.uri.startsWith("data:")
     ? {
@@ -1103,7 +1168,7 @@ const materializeAttachment = Effect.fn("Session.materializeAttachment")(functio
             .join("\n"),
         )
       : resolved.bytes
-  const normalized = yield* normalizeImageAttachment(input, Buffer.from(content).toString("base64"), mime)
+  const normalized = yield* normalizeImageAttachment(input, Buffer.from(content).toString("base64"), mime, image)
   return FileAttachment.create({
     data: normalized.data,
     mime: normalized.mime,
@@ -1114,13 +1179,14 @@ const materializeAttachment = Effect.fn("Session.materializeAttachment")(functio
   })
 })
 
-const normalizeImageAttachment = Effect.fn("Session.normalizeImageAttachment")(function* (
+const normalizeImageAttachment = Effect.fn("Session.normalizeImageAttachment")(function* <R>(
   input: PromptInput.FileAttachment,
   data: string,
   mime: string,
+  image: Effect.Effect<Image.Interface, never, R>,
 ) {
   if (!mime.startsWith("image/")) return { data: Base64.make(data), mime }
-  const service = yield* Image.Service
+  const service = yield* image
   const label = input.name ?? (input.uri.startsWith("data:") ? "inline attachment" : input.uri)
   const content = { uri: label, content: data, encoding: "base64" as const, mime }
   const normalized = yield* service.normalize(label, content).pipe(
@@ -1218,6 +1284,7 @@ export const node = makeGlobalNode({
     Project.node,
     SessionExecution.node,
     SessionStore.node,
+    SessionResolve.node,
     LocationServiceMap.node,
     SessionProjector.node,
     FSUtil.node,

packages/core/src/session/capabilities.ts

@@ -0,0 +1,38 @@
+export * as SessionCapabilities from "./capabilities.js"
+
+import type { Effect } from "effect"
+import type { Instructions } from "../instructions/index.js"
+import type { Permissions } from "../permissions.js"
+import type { Source } from "../source.js"
+import type { Tool } from "../tool.js"
+import type { Session } from "../session.js"
+import type { SessionRunner } from "./runner/index.js"
+import type { SessionRunnerModel } from "./runner/model.js"
+import type { SessionSchema } from "./schema.js"
+
+export interface OpenInput {
+  readonly id?: SessionSchema.ID
+  readonly title?: string
+  readonly model: Source.Value<SessionRunnerModel.Resolved, SessionRunnerModel.Error>
+  readonly tools?: Source.Value<ReadonlyArray<Tool.Info>>
+  readonly instructions?: Source.Value<ReadonlyArray<string> | Instructions.Unavailable>
+  readonly permissions?: Permissions.Interface
+  readonly system?: Source.Value<string | Instructions.Unavailable>
+  readonly limits?: Source.Value<{ readonly steps?: number }>
+  /** Called after replacement or host teardown, once all in-flight work has settled. */
+  readonly retire?: () => Effect.Effect<void>
+}
+
+export interface Handle {
+  readonly id: SessionSchema.ID
+  readonly prompt: (
+    input: Omit<Parameters<Session.Interface["prompt"]>[0], "sessionID">,
+  ) => Effect.Effect<
+    Effect.Success<ReturnType<Session.Interface["prompt"]>>,
+    Effect.Error<ReturnType<Session.Interface["prompt"]>> | SessionRunner.RunError
+  >
+  readonly resume: () => ReturnType<Session.Interface["resume"]>
+  readonly interrupt: (options?: { readonly continue?: boolean }) => Effect.Effect<boolean>
+  /** Releases this open's capabilities after settlement without interrupting or deleting the Session. */
+  readonly close: () => Effect.Effect<void>
+}

packages/core/src/session/context.ts

@@ -1,6 +1,6 @@
 export * as SessionContext from "./context.js"
 
-import { Context, Effect, Layer } from "effect"
+import { Context, Effect, Layer, Schema } from "effect"
 import { Agent } from "../agent.js"
 import { Catalog } from "../catalog.js"
 import { CodeModeInstructions } from "../codemode/instructions.js"
@@ -17,6 +17,13 @@ import { PluginSupervisor } from "../plugin/supervisor.js"
 import { ReferenceInstructions } from "../reference/instructions.js"
 import { SkillInstructions } from "../skill/instructions.js"
 import { Tool } from "../tool.js"
+import { Permission } from "../permission.js"
+import { Permissions } from "../permissions.js"
+import { Image } from "../image.js"
+import { PluginHooks } from "../plugin/hooks.js"
+import { Source } from "../source.js"
+import type { SessionCapabilities } from "./capabilities.js"
+import { SessionSystemPrompt } from "./system-prompt.js"
 import { AgentNotFoundError } from "./error.js"
 import { SessionHistory } from "./history.js"
 import { InstructionEntry } from "./instruction-entry.js"
@@ -31,6 +38,8 @@ export interface Selection {
   readonly agent: Agent.Selection & { readonly info: Agent.Info }
   readonly instructions: Instructions.List
   readonly tools: Tool.Snapshot
+  /** `baseTranscript` uses its default prefix for undefined; "" omits it when system text lives in the instruction epoch. */
+  readonly system?: string
 }
 
 export interface Loaded {
@@ -40,6 +49,7 @@ export interface Loaded {
   readonly initial: string
   readonly messages: ReadonlyArray<SessionMessage.Info>
   readonly tools: Tool.Snapshot
+  readonly system?: Selection["system"]
 }
 
 /**
@@ -157,23 +167,144 @@ const layer = Layer.effect(
       }
     })
 
-    const load = Effect.fn("SessionContext.load")(function* (selection: Selection) {
-      const model = yield* resolveModel(selection.session)
-      const history = yield* SessionHistory.entriesForRunner(db, selection.session.id, selection.instructions)
-      return {
-        session: selection.session,
-        agent: selection.agent,
-        model,
-        initial: history.initial,
-        messages: history.entries.map((entry) => entry.message),
-        tools: selection.tools,
-      }
+    return Service.of({
+      select,
+      load: load(db, resolveModel),
+      resolveModel,
+      selectTitle,
+      prepare: modelRequests.prepare,
     })
-
-    return Service.of({ select, load, resolveModel, selectTitle, prepare: modelRequests.prepare })
   }),
 )
 
+/** The values path shares instruction persistence and history assembly with discovery. */
+export const values = (input: SessionCapabilities.OpenInput) =>
+  Layer.effect(
+    Service,
+    Effect.gen(function* () {
+      const db = (yield* Database.Service).db
+      const store = yield* SessionStore.Service
+      const entries = yield* InstructionEntry.Service
+      const requests = yield* SessionModelRequest.Service
+      const hooks = yield* PluginHooks.Service
+      const image = yield* Image.Service
+      const tools = Source.from(input.tools ?? [])
+      const instructions = Source.from(input.instructions ?? [])
+      const limits = Source.from(input.limits ?? {})
+      const permissions = input.permissions ?? Permissions.allowAll
+      const model = Source.from(input.model)
+      const resolveModel: Interface["resolveModel"] = (session) => model.get(session)
+      let cached:
+        | {
+            readonly tools: ReadonlyArray<Tool.Info>
+            readonly rules: Permission.Ruleset
+            readonly snapshot: Tool.Snapshot
+          }
+        | undefined
+      const select: Interface["select"] = Effect.fn("SessionContext.selectValues")(function* (sessionID) {
+        const session = yield* store.get(sessionID)
+        if (!session) return yield* Effect.die(new Error(`Session not found: ${sessionID}`))
+        const selected = yield* Effect.all(
+          {
+            tools: tools.get(session),
+            rules: permissions.visibility.get(session),
+            limits: limits.get(session),
+            entries: entries.load(sessionID),
+          },
+          { concurrency: "unbounded" },
+        )
+        if (cached?.tools !== selected.tools || cached.rules !== selected.rules)
+          cached = {
+            tools: selected.tools,
+            rules: selected.rules,
+            snapshot: yield* Tool.snapshot(selected.tools, selected.rules).pipe(
+              Effect.provideService(PluginHooks.Service, hooks),
+              Effect.provideService(Image.Service, image),
+            ),
+          }
+        const snapshot = cached.snapshot
+        const id = session.agent ?? Agent.defaultID
+        return {
+          session,
+          agent: { id, info: { ...Agent.Info.default(id), permissions: selected.rules, steps: selected.limits.steps } },
+          // System text participates in the epoch instead of changing the privileged prefix.
+          system: "",
+          tools: snapshot,
+          instructions: Instructions.combine([
+            Instructions.make({
+              key: Instructions.Key.make("session/system"),
+              codec: Schema.String,
+              read:
+                input.system === undefined
+                  ? Effect.succeed(SessionSystemPrompt.make(snapshot.definitions.map((tool) => tool.name)))
+                  : Source.from(input.system)
+                      .get(session)
+                      .pipe(Effect.map((value) => (value === "" ? Instructions.removed : value))),
+              render: {
+                initial: (value) => value,
+                changed: (_previous, value) =>
+                  `The system instructions changed and supersede the previous value:\n${value}`,
+                removed: () => "The previous system instructions no longer apply.",
+              },
+            }),
+            CodeModeInstructions.make(snapshot.codeModeCatalog),
+            Instructions.make({
+              key: Instructions.Key.make("session/instructions"),
+              codec: Schema.Array(Schema.String),
+              read: instructions
+                .get(session)
+                .pipe(
+                  Effect.map((value) =>
+                    Array.isArray(value) && !value.some((part) => part.length > 0) ? Instructions.removed : value,
+                  ),
+                ),
+              render: {
+                initial: (value) => value.join("\n\n"),
+                changed: (_previous, value) =>
+                  `The session instructions changed and supersede the previous value:\n${value.join("\n\n")}`,
+                removed: () => "The previous session instructions no longer apply.",
+              },
+            }),
+            Instructions.make({
+              key: Instructions.Key.make("session/permissions"),
+              codec: Schema.toCodecJson(Permission.Ruleset),
+              read: Effect.succeed(selected.rules.length > 0 ? selected.rules : Instructions.removed),
+              render: {
+                initial: (value) => `Permission rules:\n${JSON.stringify(value)}`,
+                changed: (_previous, value) => `Permission rules changed:\n${JSON.stringify(value)}`,
+                removed: () => "The previous permission rules no longer apply.",
+              },
+            }),
+            selected.entries,
+          ]),
+        }
+      })
+      return Service.of({
+        select,
+        load: load(db, resolveModel),
+        resolveModel,
+        selectTitle: () => Effect.undefined,
+        prepare: requests.prepare,
+      })
+    }),
+  )
+
+function load(db: Database.Interface["db"], resolveModel: Interface["resolveModel"]): Interface["load"] {
+  return Effect.fn("SessionContext.load")(function* (selection: Selection) {
+    const model = yield* resolveModel(selection.session)
+    const history = yield* SessionHistory.entriesForRunner(db, selection.session.id, selection.instructions)
+    return {
+      session: selection.session,
+      agent: selection.agent,
+      model,
+      initial: history.initial,
+      messages: history.entries.map((entry) => entry.message),
+      tools: selection.tools,
+      ...(selection.system === undefined ? {} : { system: selection.system }),
+    }
+  })
+}
+
 /** Variant IDs that minimize reasoning output, in preference order. */
 const MINIMAL_REASONING_VARIANTS = ["none", "minimal", "low"].map((id) => Model.VariantID.make(id))
 

packages/core/src/session/execution.ts

@@ -14,6 +14,7 @@ import { SessionStore } from "./store.js"
 import { toSessionError } from "./to-session-error.js"
 import { UserInterruptedError } from "./error.js"
 import { SessionInbox } from "./inbox.js"
+import { SessionResolve } from "./resolve.js"
 
 export interface Interface {
   /** Snapshots active execution owned by this process. */
@@ -52,6 +53,7 @@ export const layer = Layer.effect(
   Effect.gen(function* () {
     const store = yield* SessionStore.Service
     const locations = yield* LocationServiceMap.Service
+    const resolve = yield* SessionResolve.Service
     const bus = yield* Bus.Service
     const jobs = yield* Job.Service
     const db = (yield* Database.Service).db
@@ -86,10 +88,14 @@ export const layer = Layer.effect(
       return Effect.gen(function* () {
         const session = yield* store.get(sessionID)
         if (!session) return yield* Effect.die(new Error(`Session not found: ${sessionID}`))
-        const result = yield* SessionRunner.Service.use((runner) =>
-          runner.drain({ sessionID, force, continuation, promotable }),
+        const pinned = resolve.pinned(sessionID)
+        const result = yield* (
+          pinned
+            ? pinned.drain({ sessionID, force, continuation, promotable })
+            : SessionRunner.Service.use((runner) => runner.drain({ sessionID, force, continuation, promotable })).pipe(
+                Effect.provide(locations.get(session.location)),
+              )
         ).pipe(
-          Effect.provide(locations.get(session.location)),
           Effect.tapCause((cause) =>
             Cause.hasInterruptsOnly(cause)
               ? Effect.void
@@ -101,11 +107,14 @@ export const layer = Layer.effect(
       })
     }
     const coordinator = yield* SessionRunCoordinator.make<SessionSchema.ID, SessionRunner.RunError, InterruptReason>({
-      started: (sessionID) =>
-        reportLifecycle(
+      eligible: (sessionID) => resolve.status(sessionID) !== "owned-detached",
+      started: (sessionID) => {
+        resolve.pin(sessionID)
+        return reportLifecycle(
           sessionID,
           bus.publish(SessionEvent.Execution.Started, { sessionID }, claimOnCommit(sessionID)),
-        ),
+        )
+      },
       drain: (sessionID, force, promotable) => drain(sessionID, force, undefined, promotable),
       // One terminal observation per busy period, covering every coalesced drain.
       settled: (sessionID, exit, reason) =>
@@ -137,7 +146,7 @@ export const layer = Layer.effect(
               releaseOnCommit(sessionID),
             )
           }),
-        ),
+        ).pipe(Effect.ensuring(resolve.settle(sessionID))),
     })
 
     return Service.of({
@@ -160,7 +169,12 @@ export const layer = Layer.effect(
             yield* coordinator.wake(sessionID, "steer")
           return interrupted
         }),
-      resume: coordinator.run,
+      resume: (sessionID) =>
+        Effect.gen(function* () {
+          // TODO: typed unavailable-operation errors belong to the capability-gated operations phase.
+          if (resolve.status(sessionID) === "owned-detached") return yield* SessionResolve.unavailable(sessionID)
+          yield* coordinator.run(sessionID)
+        }),
       wake: coordinator.wake,
       awaitIdle: coordinator.awaitIdle,
     })
@@ -170,7 +184,7 @@ export const layer = Layer.effect(
 export const node = makeGlobalNode({
   service: Service,
   layer,
-  deps: [SessionStore.node, LocationServiceMap.node, Bus.node, Database.node, Job.node],
+  deps: [SessionStore.node, LocationServiceMap.node, Bus.node, Database.node, Job.node, SessionResolve.node],
 })
 
 /** Low-level compatibility layer for callers that only need durable Session recording. */

packages/core/src/session/execution/restart.ts

@@ -7,6 +7,7 @@ import { Job } from "../../job.js"
 import { Session } from "../../session.js"
 import { SessionEvent } from "../event.js"
 import { SessionExecution } from "../execution.js"
+import { SessionResolve } from "../resolve.js"
 import { SessionSchema } from "../schema.js"
 import { SessionStore } from "../store.js"
 
@@ -37,6 +38,8 @@ export interface Interface {
    * shutdown (which preserves the claim on purpose). The claim is never
    * cleared here: only a terminal event releases it, so a death anywhere in
    * the resume path leaves the same orphaned claim for the next boot.
+   * Capability-owned Sessions stay pending even when reopened; they require
+   * an explicit prompt or resume instead of automatic recovery.
    */
   readonly resumeSuspendedSessions: Effect.Effect<void>
 }
@@ -66,6 +69,7 @@ export const layer = (options?: Options) =>
     Effect.gen(function* () {
       const store = yield* SessionStore.Service
       const execution = yield* SessionExecution.Service
+      const resolve = yield* SessionResolve.Service
       const bus = yield* Bus.Service
       const jobs = yield* Job.Service
       const sessions = yield* Session.Service
@@ -73,6 +77,8 @@ export const layer = (options?: Options) =>
       const maxAttempts = options?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS
 
       const prepareResume = Effect.fnUntraced(function* (sessionID: SessionSchema.ID) {
+        // Reopening capabilities does not opt a Session into automatic recovery.
+        if (resolve.status(sessionID) !== "unowned") return undefined
         // Durable before the resume runs, so a crash inside the resumed turn is
         // counted by the next sweep and the budget cannot be dodged.
         const attempts = yield* store.countResume(sessionID)
@@ -95,6 +101,14 @@ export const layer = (options?: Options) =>
         return true
       })
 
+      const eligibleJob = (recovery: Job.Recovery) => {
+        if (recovery.kind === "shell") return resolve.status(recovery.sessionID) === "unowned"
+        return (
+          resolve.status(recovery.parentSessionID) === "unowned" &&
+          resolve.status(recovery.childSessionID) === "unowned"
+        )
+      }
+
       const recoverShell = Effect.fnUntraced(function* (
         background: Job.Background,
         recovery: Extract<Job.Recovery, { kind: "shell" }>,
@@ -143,6 +157,7 @@ export const layer = (options?: Options) =>
 
         const notify = Effect.fnUntraced(function* (result: Pick<Job.Background, "status" | "output" | "error">) {
           if (result.status === "running") return
+          if (!eligibleJob(recovery)) return
           const text =
             result.status === "completed"
               ? (result.output ?? "Subagent completed without a text response.")
@@ -172,7 +187,9 @@ export const layer = (options?: Options) =>
           return
         }
         if ((yield* execution.active).has(recovery.childSessionID)) return
-        if (!(yield* prepareResume(recovery.childSessionID))) {
+        const prepared = yield* prepareResume(recovery.childSessionID)
+        if (prepared === undefined) return
+        if (!prepared) {
           yield* notify({ status: "error", error: RESUME_EXHAUSTED.message })
           return
         }
@@ -214,18 +231,20 @@ export const layer = (options?: Options) =>
           // Early notices wait for root recovery's accounting, including roots that exhaust their budget.
           const suspended = new Set((yield* store.listSuspended()).filter((sessionID) => !active.has(sessionID)))
           const pending = yield* jobs.pendingBackground
-          yield* store.releaseChildClaims(
-            pending.flatMap((background) =>
+          yield* store.releaseChildClaims([
+            ...(yield* resolve.ownedIDs),
+            ...pending.flatMap((background) =>
               background.status === "running" && background.recovery.kind === "subagent"
                 ? [background.recovery.childSessionID]
                 : [],
             ),
-          )
+          ])
           yield* Effect.forEach(
             pending,
             Effect.fnUntraced(function* (background) {
               if ((yield* jobs.get(background.id))?.status === "running") return
               const recovery = background.recovery
+              if (!eligibleJob(recovery)) return
               yield* recovery.kind === "shell"
                 ? recoverShell(background, recovery)
                 : recoverSubagent(background, recovery, suspended)
@@ -237,10 +256,10 @@ export const layer = (options?: Options) =>
           const resumed = yield* execution.active
           yield* Effect.forEach(
             (yield* store.listSuspended()).filter((sessionID) => !resumed.has(sessionID)),
-            (sessionID) =>
-              execution
-                .resume(sessionID)
-                .pipe(Effect.ignore, Effect.forkIn(scope), Effect.when(prepareResume(sessionID))),
+            Effect.fnUntraced(function* (sessionID) {
+              if (!(yield* prepareResume(sessionID))) return
+              yield* execution.resume(sessionID).pipe(Effect.ignore, Effect.forkIn(scope))
+            }),
             { concurrency: "unbounded", discard: true },
           )
           // Async observers consult this set at delivery; later completions wake parents normally.
@@ -253,5 +272,5 @@ export const layer = (options?: Options) =>
 export const node = makeGlobalNode({
   service: Service,
   layer: layer(),
-  deps: [SessionStore.node, SessionExecution.node, Bus.node, Job.node, Session.node],
+  deps: [SessionStore.node, SessionExecution.node, SessionResolve.node, Bus.node, Job.node, Session.node],
 })

packages/core/src/session/instruction-entry.ts

@@ -103,7 +103,7 @@ const source = (entry: Info & { readonly removed: boolean }) =>
     },
   })
 
-const layer = Layer.effect(
+export const layer = Layer.effect(
   Service,
   Effect.gen(function* () {
     const { db } = yield* Database.Service

packages/core/src/session/model-request.ts

@@ -84,14 +84,16 @@ export const baseTranscript = (input: {
   readonly tools: Tool.Snapshot
   readonly initial: string
   readonly messages: ReadonlyArray<SessionMessage.Info>
+  readonly system?: string
 }) => {
   const providerMetadataKey = input.model.model.route.providerMetadataKey ?? input.model.model.provider
   return {
     providerMetadataKey,
     system: [
-      input.agent.system
-        ? input.agent.system
-        : SessionSystemPrompt.make(input.tools.definitions.map((tool) => tool.name)),
+      input.system ??
+        (input.agent.system
+          ? input.agent.system
+          : SessionSystemPrompt.make(input.tools.definitions.map((tool) => tool.name))),
       input.initial,
     ]
       .filter((part) => part.length > 0)

packages/core/src/session/resolve.ts

@@ -0,0 +1,291 @@
+export * as SessionResolve from "./resolve.js"
+
+import type { LLMClientService } from "@opencode-ai/ai"
+import { FSUtil } from "@opencode-ai/util/fs-util"
+import { Global } from "@opencode-ai/util/global"
+import { makeGlobalNode } from "@opencode-ai/util/effect/app-node"
+import { Context, Deferred, Effect, Exit, Layer, Scope } from "effect"
+import { Bus } from "../bus.js"
+import { App } from "../app.js"
+import { Database } from "../database/database.js"
+import { llmClient, webSocketConstructor } from "../effect/app-node-platform.js"
+import { KV } from "../kv.js"
+import type { SessionCapabilities } from "./capabilities.js"
+import type { SessionRunner } from "./runner/index.js"
+import { SessionSchema } from "./schema.js"
+import { SessionStore } from "./store.js"
+import { Socket } from "effect/unstable/socket"
+import type { Image } from "../image.js"
+import type { SessionContext } from "./context.js"
+import type { SessionModelTransport } from "./model-transport.js"
+
+const prefix = "session.capabilities/"
+
+/**
+ * Live operations, never an attempt snapshot. Title, request hooks, compaction,
+ * media/skills, snapshots, output, and transport customization are deferred;
+ * open supplies their internal defaults without directory discovery.
+ */
+interface Capabilities extends SessionContext.Interface {
+  readonly image: Image.Interface
+  readonly transport: SessionModelTransport.Interface
+}
+
+type Status = "attached" | "owned-detached" | "unowned"
+type Resolved =
+  | { readonly status: "attached"; readonly capabilities: Capabilities }
+  | { readonly status: "owned-detached" | "unowned" }
+
+type Opened = {
+  readonly capabilities: Capabilities
+  readonly runner: SessionRunner.Interface
+  readonly scope: Scope.Closeable
+  readonly onRetire: () => Effect.Effect<void>
+  readonly done: Deferred.Deferred<void>
+  current: boolean
+  users: number
+}
+
+export interface Interface {
+  readonly own: <A extends { readonly id: SessionSchema.ID }, R>(
+    record: Effect.Effect<A, never, R>,
+  ) => Effect.Effect<A, never, R>
+  readonly status: (id: SessionSchema.ID) => Status
+  readonly ownedIDs: Effect.Effect<ReadonlyArray<SessionSchema.ID>>
+  readonly attach: (
+    id: SessionSchema.ID,
+    input: SessionCapabilities.OpenInput,
+  ) => Effect.Effect<() => Effect.Effect<void>>
+  readonly resolve: (session: SessionSchema.Info) => Effect.Effect<Resolved, never, Scope.Scope>
+  /** Called synchronously when the coordinator installs a busy period, before its first fiber yield. */
+  readonly pin: (id: SessionSchema.ID) => void
+  readonly pinned: (id: SessionSchema.ID) => SessionRunner.Interface | undefined
+  readonly settle: (id: SessionSchema.ID) => Effect.Effect<void>
+  readonly remove: (id: SessionSchema.ID) => Effect.Effect<void>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@opencode/SessionResolve") {}
+
+export const layer = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const kv = yield* KV.Service
+    const db = (yield* Database.Service).db
+    const owned = new Set(
+      (yield* kv.scanAll(prefix))
+        .filter((entry) => entry.value === true)
+        .map((entry) => SessionSchema.ID.make(entry.key.slice(prefix.length))),
+    )
+    const globals = yield* Effect.context<
+      | Database.Service
+      | Bus.Service
+      | SessionStore.Service
+      | LLMClientService
+      | FSUtil.Service
+      | Global.Service
+      | Socket.WebSocketConstructor
+    >()
+    const current = new Map<SessionSchema.ID, Opened>()
+    const pinned = new Map<SessionSchema.ID, Opened>()
+    const opened = new Map<Deferred.Deferred<void>, Opened>()
+    // LayerMap invalidation cannot choose synchronously at coordinator start or
+    // run a host hook after all generation-specific users settle. Keep explicit leases.
+    const retire = (value: Opened) =>
+      Effect.suspend(() => {
+        if (value.current || value.users > 0 || !opened.delete(value.done)) return Effect.void
+        return Scope.close(value.scope, Exit.void).pipe(
+          Effect.andThen(value.onRetire()),
+          Effect.onExit((exit) => Deferred.done(value.done, exit)),
+        )
+      })
+    const release = (value: Opened) =>
+      Effect.sync(() => {
+        value.users--
+      }).pipe(Effect.andThen(retire(value)))
+    yield* Effect.addFinalizer(() =>
+      Effect.sync(() => current.clear()).pipe(
+        Effect.andThen(
+          Effect.forEach(
+            opened.values(),
+            (value) => {
+              value.current = false
+              return retire(value)
+            },
+            { discard: true },
+          ),
+        ),
+      ),
+    )
+
+    return Service.of({
+      // Ownership is transitionally one-way: retirement never hands a Session back to discovery.
+      own: (record) =>
+        Effect.uninterruptible(
+          Effect.gen(function* () {
+            const session = yield* db
+              .transaction(() =>
+                Effect.gen(function* () {
+                  const session = yield* record
+                  if (!owned.has(session.id)) yield* kv.set(prefix + session.id, true)
+                  return session
+                }),
+              )
+              .pipe(Effect.orDie)
+            // Publish the memory index only after the durable transaction commits.
+            owned.add(session.id)
+            return session
+          }),
+        ),
+      status: (id) => (current.has(id) ? "attached" : owned.has(id) ? "owned-detached" : "unowned"),
+      ownedIDs: Effect.sync(() => Array.from(owned)),
+      attach: Effect.fn("SessionResolve.attach")(function* (id, input) {
+        const [
+          { Image },
+          { PluginHooks },
+          { PluginSupervisor },
+          { Snapshot },
+          { ToolOutput },
+          { SessionCompaction },
+          { SessionContext },
+          { InstructionEntry },
+          { SessionModelRequest },
+          { SessionModelTransport },
+          { SessionRunner },
+          { SessionRunnerLLM },
+          { SessionTitle },
+        ] = yield* Effect.promise(() =>
+          Promise.all([
+            import("../image.js"),
+            import("../plugin/hooks.js"),
+            import("../plugin/supervisor-service.js"),
+            import("../snapshot.js"),
+            import("../tool-output.js"),
+            import("./compaction.js"),
+            import("./context.js"),
+            import("./instruction-entry.js"),
+            import("./model-request.js"),
+            import("./model-transport.js"),
+            import("./runner/index.js"),
+            import("./runner/llm.js"),
+            import("./title.js"),
+          ]),
+        )
+        const scope = yield* Scope.make()
+        const base = Layer.mergeAll(
+          PluginHooks.layer,
+          Image.layer,
+          InstructionEntry.layer,
+          SessionModelTransport.layer,
+          ToolOutput.layer,
+          Snapshot.noopLayer,
+          SessionCompaction.layer,
+          Layer.succeed(PluginSupervisor.Service, { flush: Effect.void }),
+        ).pipe(Layer.provide(Layer.succeedContext(globals)))
+        const requests = SessionModelRequest.layer.pipe(Layer.provideMerge(base))
+        const capabilities = SessionContext.values(input).pipe(Layer.provideMerge(requests))
+        const runner = SessionRunnerLLM.layer.pipe(
+          Layer.provideMerge(SessionTitle.layer.pipe(Layer.provideMerge(capabilities))),
+          Layer.provide(Layer.succeedContext(globals)),
+        )
+        // Each open builds fresh local state over the SAME captured durable/global services.
+        const services = yield* Layer.buildWithScope(Layer.fresh(runner), scope).pipe(
+          Effect.onError(() => Scope.close(scope, Exit.void)),
+        )
+        const value: Opened = {
+          capabilities: {
+            ...Context.get(services, SessionContext.Service),
+            image: Context.get(services, Image.Service),
+            transport: Context.get(services, SessionModelTransport.Service),
+          },
+          runner: Context.get(services, SessionRunner.Service),
+          scope,
+          onRetire: input.retire ?? (() => Effect.void),
+          done: Deferred.makeUnsafe<void>(),
+          current: true,
+          users: 0,
+        }
+        const previous = current.get(id)
+        current.set(id, value)
+        opened.set(value.done, value)
+        if (previous) {
+          previous.current = false
+          yield* retire(previous)
+        }
+        // Closed handles retain only completion, not retired capability functions or layers.
+        const done = value.done
+        return () =>
+          Effect.gen(function* () {
+            yield* Effect.uninterruptible(
+              Effect.gen(function* () {
+                const value = opened.get(done)
+                if (!value) return
+                if (current.get(id) === value) current.delete(id)
+                value.current = false
+                yield* retire(value)
+              }),
+            )
+            yield* Deferred.await(done)
+          })
+      }),
+      resolve: (session) =>
+        Effect.gen(function* () {
+          const value = current.get(session.id)
+          if (!value) return { status: owned.has(session.id) ? ("owned-detached" as const) : ("unowned" as const) }
+          yield* Effect.acquireRelease(
+            Effect.sync(() => {
+              value.users++
+            }),
+            () => release(value),
+          )
+          return { status: "attached" as const, capabilities: value.capabilities }
+        }),
+      pin: (id) => {
+        const value = current.get(id)
+        if (!value) return
+        value.users++
+        pinned.set(id, value)
+      },
+      pinned: (id) => pinned.get(id)?.runner,
+      settle: (id) =>
+        Effect.suspend(() => {
+          const value = pinned.get(id)
+          if (!value) return Effect.void
+          pinned.delete(id)
+          return release(value)
+        }),
+      remove: (id) =>
+        Effect.gen(function* () {
+          const value = current.get(id)
+          current.delete(id)
+          if (value) {
+            value.current = false
+            yield* retire(value)
+          }
+          if (!owned.has(id)) return
+          yield* kv.remove(prefix + id)
+          owned.delete(id)
+        }),
+    })
+  }),
+)
+
+export const node = makeGlobalNode({
+  service: Service,
+  layer,
+  deps: [
+    KV.node,
+    Database.node,
+    Bus.node,
+    SessionStore.node,
+    llmClient,
+    FSUtil.node,
+    Global.node,
+    webSocketConstructor,
+    // Request preparation reads this Reference from the captured globals, not its fallback metadata.
+    App.node,
+  ],
+})
+
+/** TODO: replace this defect with the typed error in the capability-gated operations phase. */
+export const unavailable = (sessionID: SessionSchema.ID) =>
+  Effect.die(new Error(`Session must be reopened with capabilities: ${sessionID}`))

packages/core/src/session/run-coordinator.ts

@@ -52,6 +52,8 @@ type Execution<E, Reason> = {
  */
 export const make = <Key, E, Reason = never>(options: {
   readonly drain: (key: Key, force: boolean, scope: Promotable) => Effect.Effect<void, E>
+  /** Controls new busy periods, including late successors; existing execution may finish. */
+  readonly eligible?: (key: Key) => boolean
   /** Runs once when a process-local busy period begins, before its first drain. */
   readonly started?: (key: Key) => Effect.Effect<void>
   /**
@@ -107,7 +109,7 @@ export const make = <Key, E, Reason = never>(options: {
     // A doorbell that survives the execution loop (rung after the loop decided to end, or
     // during failure or interruption cleanup) starts a fresh execution for the remaining work.
     const settle = (key: Key, execution: Execution<E, Reason>, exit: Exit.Exit<void, E>) => {
-      if (execution.pendingWake) start(key, false, execution.pendingWake)
+      if (execution.pendingWake && (options.eligible?.(key) ?? true)) start(key, false, execution.pendingWake)
       else executions.delete(key)
       Deferred.doneUnsafe(execution.done, exit)
     }
@@ -121,11 +123,13 @@ export const make = <Key, E, Reason = never>(options: {
             return Deferred.await(execution.done).pipe(Effect.ignoreCause, Effect.andThen(run(key)))
           return Deferred.await(execution.done)
         }
+        if (options.eligible?.(key) === false) return Effect.interrupt
         return Deferred.await(start(key, true, "input").done)
       })
 
     const wake = (key: Key, scope: Promotable = "input") =>
       Effect.sync(() => {
+        if (options.eligible?.(key) === false) return
         const execution = executions.get(key)
         if (execution !== undefined) {
           // Coalesced wakes keep the widest scope: "input" subsumes "steer".

packages/core/src/session/runner/llm.ts

@@ -30,7 +30,7 @@ import { MAX_STEPS_PROMPT } from "./max-steps.js"
 const CONTINUE_AFTER_INCOMPLETE_STREAM =
   "The previous response was interrupted. Continue from where you left off without repeating completed content."
 
-const layer = Layer.effect(
+export const layer = Layer.effect(
   Service,
   Effect.gen(function* () {
     const bus = yield* Bus.Service
@@ -235,6 +235,7 @@ const layer = Layer.effect(
           tools: loaded.tools,
           initial: loaded.initial,
           messages: loaded.messages,
+          system: loaded.system,
         })
         const prepared = yield* context.prepare({
           scope: { session: loaded.session, agentID: loaded.agent.id, model: loaded.model, tools: loaded.tools },

packages/core/src/session/store.ts

@@ -33,7 +33,7 @@ export interface Interface {
   readonly release: (sessionID: Session.ID) => Effect.Effect<void>
   /**
    * Clears orphaned child claims except children owned by recoverable
-   * background subagent jobs.
+   * background subagent jobs or capability-owned Sessions.
    */
   readonly releaseChildClaims: (recoverable: ReadonlyArray<Session.ID>) => Effect.Effect<void>
   /**

packages/core/src/source.ts

@@ -0,0 +1,37 @@
+export * as Source from "./source.js"
+
+import { Effect, Ref } from "effect"
+import type { SessionSchema } from "./session/schema.js"
+
+export interface Interface<T, E = never> {
+  /** Return replacement values when changing state; consumers may reuse derived results by reference identity. */
+  readonly get: (session: SessionSchema.Info) => Effect.Effect<T, E>
+}
+
+export type Value<T, E = never> = T | Interface<T, E>
+
+export interface Mutable<T> extends Interface<T> {
+  readonly set: (value: T) => Effect.Effect<void>
+  readonly update: (update: (value: T) => T) => Effect.Effect<void>
+}
+
+export function mutable<T>(initial: T): Mutable<T> {
+  const ref = Ref.makeUnsafe(initial)
+  return {
+    get: () => Ref.get(ref),
+    set: (value) => Ref.set(ref, value),
+    update: (update) => Ref.update(ref, update),
+  }
+}
+
+export function constant<T>(value: T): Interface<T> {
+  return { get: () => Effect.succeed(value) }
+}
+
+export function from<T, E = never>(value: Value<T, E>): Interface<T, E> {
+  return isSource(value) ? value : constant(value)
+}
+
+function isSource<T, E>(value: Value<T, E>): value is Interface<T, E> {
+  return typeof value === "object" && value !== null && "get" in value && typeof value.get === "function"
+}

packages/core/src/tool-output.ts

@@ -45,7 +45,7 @@ const cleanup = Effect.fn("ToolOutput.cleanup")(function* (fs: FSUtil.Interface,
   )
 })
 
-const layer = Layer.effect(
+export const layer = Layer.effect(
   Service,
   Effect.gen(function* () {
     const fs = yield* FSUtil.Service

packages/core/src/tool.ts

@@ -1,6 +1,6 @@
 export * as Tool from "./tool.js"
 export { CallID, Content, Error, FileContent, TextContent } from "@opencode-ai/schema/tool"
-export type { Context, Metadata, Options, Result } from "@opencode-ai/schema/tool"
+export type { Context, Info, Metadata, Options, Result } from "@opencode-ai/schema/tool"
 
 import { ToolDefinition, type ToolCall } from "@opencode-ai/ai"
 import { Tool } from "@opencode-ai/schema/tool"
@@ -56,205 +56,212 @@ export interface Snapshot {
 
 export class Service extends Context.Service<Service, Interface>()("@opencode/Tool") {}
 
-const layer = Layer.effect(
-  Service,
-  Effect.gen(function* () {
-    const hooks = yield* PluginHooks.Service
-    const image = yield* Image.Service
+const make = Effect.gen(function* () {
+  const hooks = yield* PluginHooks.Service
+  const image = yield* Image.Service
 
-    type NormalizedItem = Tool.Content | "decode" | "size"
-    const normalizeImages = Effect.fnUntraced(function* (content: ReadonlyArray<Tool.Content>) {
-      const normalized = yield* Effect.forEach(content, (item): Effect.Effect<NormalizedItem> => {
-        if (item.type !== "file" || !item.mime.startsWith("image/")) return Effect.succeed(item)
-        const base64 = /^data:[^,]*;base64,(.*)$/s.exec(item.uri)?.[1]
-        if (base64 === undefined) return Effect.succeed(item)
-        const resource = item.name ?? `${item.mime} tool output`
-        return image.normalize(resource, { uri: resource, content: base64, encoding: "base64", mime: item.mime }).pipe(
-          Effect.map((result) => ({
-            ...item,
-            uri: `data:${result.mime};base64,${result.content}`,
-            mime: result.mime,
-          })),
-          Effect.catchTag("Image.ResizerUnavailableError", () => Effect.succeed(item)),
-          Effect.catchTag("Image.DecodeError", () => Effect.succeed("decode" as const)),
-          Effect.catchTag("Image.SizeError", () => Effect.succeed("size" as const)),
-        )
-      })
-      const note = (reason: "decode" | "size", text: string) => {
-        const count = normalized.filter((item) => item === reason).length
-        if (count === 0) return []
-        return [{ type: "text" as const, text: `[${count} image${count === 1 ? "" : "s"} omitted: ${text}]` }]
-      }
-      return [
-        ...normalized.filter((item) => typeof item !== "string"),
-        ...note("decode", "could not be decoded."),
-        ...note("size", "could not be resized below the image size limit."),
-      ]
+  type NormalizedItem = Tool.Content | "decode" | "size"
+  const normalizeImages = Effect.fnUntraced(function* (content: ReadonlyArray<Tool.Content>) {
+    const normalized = yield* Effect.forEach(content, (item): Effect.Effect<NormalizedItem> => {
+      if (item.type !== "file" || !item.mime.startsWith("image/")) return Effect.succeed(item)
+      const base64 = /^data:[^,]*;base64,(.*)$/s.exec(item.uri)?.[1]
+      if (base64 === undefined) return Effect.succeed(item)
+      const resource = item.name ?? `${item.mime} tool output`
+      return image.normalize(resource, { uri: resource, content: base64, encoding: "base64", mime: item.mime }).pipe(
+        Effect.map((result) => ({
+          ...item,
+          uri: `data:${result.mime};base64,${result.content}`,
+          mime: result.mime,
+        })),
+        Effect.catchTag("Image.ResizerUnavailableError", () => Effect.succeed(item)),
+        Effect.catchTag("Image.DecodeError", () => Effect.succeed("decode" as const)),
+        Effect.catchTag("Image.SizeError", () => Effect.succeed("size" as const)),
+      )
+    })
+    const note = (reason: "decode" | "size", text: string) => {
+      const count = normalized.filter((item) => item === reason).length
+      if (count === 0) return []
+      return [{ type: "text" as const, text: `[${count} image${count === 1 ? "" : "s"} omitted: ${text}]` }]
+    }
+    return [
+      ...normalized.filter((item) => typeof item !== "string"),
+      ...note("decode", "could not be decoded."),
+      ...note("size", "could not be resized below the image size limit."),
+    ]
+  })
+
+  const beforeExecute = (name: string, input: unknown, context: Tool.Context) =>
+    hooks.trigger("tool", "execute.before", {
+      tool: name,
+      sessionID: context.sessionID,
+      agent: context.agent,
+      messageID: context.messageID,
+      id: context.id,
+      input,
     })
 
-    const beforeExecute = (name: string, input: unknown, context: Tool.Context) =>
-      hooks.trigger("tool", "execute.before", {
-        tool: name,
-        sessionID: context.sessionID,
-        agent: context.agent,
-        messageID: context.messageID,
-        id: context.id,
-        input,
-      })
-
-    const executeTool = Effect.fn("Tool.execute")(function* (
-      tool: Tool.Info,
-      name: string,
-      input: unknown,
-      context: Tool.Context,
-    ) {
-      const execution = yield* execute(tool, input, context).pipe(
-        Effect.map((value) => ({ value })),
-        Effect.catchTag("Tool.Error", (failure) => Effect.succeed({ failure })),
-      )
-      const base = {
-        tool: name,
-        sessionID: context.sessionID,
-        agent: context.agent,
-        messageID: context.messageID,
-        id: context.id,
-        input,
-      }
-      if ("failure" in execution) {
-        const afterEvent: PluginHooks.Domains["tool"]["execute.after"] = {
-          ...base,
-          status: "error",
-          error: execution.failure,
-        }
-        yield* hooks.trigger("tool", "execute.after", afterEvent)
-        return yield* afterEvent.error
-      }
+  const executeTool = Effect.fn("Tool.execute")(function* (
+    tool: Tool.Info,
+    name: string,
+    input: unknown,
+    context: Tool.Context,
+  ) {
+    const execution = yield* execute(tool, input, context).pipe(
+      Effect.map((value) => ({ value })),
+      Effect.catchTag("Tool.Error", (failure) => Effect.succeed({ failure })),
+    )
+    const base = {
+      tool: name,
+      sessionID: context.sessionID,
+      agent: context.agent,
+      messageID: context.messageID,
+      id: context.id,
+      input,
+    }
+    if ("failure" in execution) {
       const afterEvent: PluginHooks.Domains["tool"]["execute.after"] = {
         ...base,
-        status: "completed",
-        result: {
-          ...(execution.value.output === undefined ? {} : { output: execution.value.output }),
-          content: execution.value.content,
-          ...(execution.value.metadata === undefined ? {} : { metadata: execution.value.metadata }),
-        },
+        status: "error",
+        error: execution.failure,
       }
       yield* hooks.trigger("tool", "execute.after", afterEvent)
-      const afterContent = yield* normalizeImages(normalizeContent(afterEvent.result.content, afterEvent.result.output))
-      return {
-        ...(afterEvent.result.output === undefined ? {} : { output: afterEvent.result.output }),
-        content: afterContent,
-        ...(afterEvent.result.metadata === undefined ? {} : { metadata: afterEvent.result.metadata }),
-      }
-    })
+      return yield* afterEvent.error
+    }
+    const afterEvent: PluginHooks.Domains["tool"]["execute.after"] = {
+      ...base,
+      status: "completed",
+      result: {
+        ...(execution.value.output === undefined ? {} : { output: execution.value.output }),
+        content: execution.value.content,
+        ...(execution.value.metadata === undefined ? {} : { metadata: execution.value.metadata }),
+      },
+    }
+    yield* hooks.trigger("tool", "execute.after", afterEvent)
+    const afterContent = yield* normalizeImages(normalizeContent(afterEvent.result.content, afterEvent.result.output))
+    return {
+      ...(afterEvent.result.output === undefined ? {} : { output: afterEvent.result.output }),
+      content: afterContent,
+      ...(afterEvent.result.metadata === undefined ? {} : { metadata: afterEvent.result.metadata }),
+    }
+  })
 
-    const state: State.Interface<Data, Draft> = State.create<Data, Draft>({
-      name: "tool",
-      initial: () => ({
-        tools: new Map(),
-        errors: [],
-      }),
-      draft: (draft) => ({
-        list: () => Array.from(draft.tools.values()),
-        get: (id) => draft.tools.get(id),
-        add: (tool) => {
-          const error = registrationError(tool)
-          if (error) {
-            draft.errors.push({ tool, error })
-            return
-          }
-          const id = effectiveName(tool)
-          draft.tools.set(id, { ...tool, id, options: tool.options && { ...tool.options } })
-        },
-        update: (id, update) => {
-          const current = draft.tools.get(id)
-          if (!current) return
-          const tool = { ...current, options: current.options && { ...current.options } }
-          update(tool)
-          tool.name = current.name
-          tool.id = id
-          if (tool.options?.namespace !== current.options?.namespace)
-            tool.options = { ...tool.options, namespace: current.options?.namespace }
-          const error = registrationError(tool)
-          if (error) {
-            draft.errors.push({ tool, error })
-            return
-          }
-          draft.tools.set(id, tool)
-        },
-        remove: (id) => {
-          draft.tools.delete(id)
-        },
-      }),
-      finalize: () =>
-        Effect.forEach(
-          state.get().errors,
-          ({ tool, error }) =>
-            Effect.logError("Skipping invalid tool registration", {
-              name: tool.name,
-              namespace: tool.options?.namespace,
-              error: error.message,
-            }),
-          { discard: true },
-        ),
-    })
-
-    return Service.of({
-      transform: state.transform,
-      reload: state.reload,
-      snapshot: Effect.fn("Tool.snapshot")((permissions) =>
-        Effect.sync(() => {
-          const active = new Map<string, Tool.Info>()
-          const rules = permissions ?? []
-          for (const [name, tool] of state.get().tools) {
-            if (whollyDisabled(tool.options?.permission ?? name, rules)) continue
-            active.set(name, tool)
-          }
-          const direct = new Map(Array.from(active).filter(([, tool]) => tool.options?.codemode === false))
-          const codemode = new Map(Array.from(active).filter(([, tool]) => tool.options?.codemode !== false))
-          const executeRule = rules.findLast((rule) => Wildcard.match("execute", rule.action))
-          const codemodeEnabled = executeRule?.resource !== "*" || executeRule.effect !== "deny"
-          const codemodeTool = codemodeEnabled
-            ? CodeModeTool.create(codemode, (name, tool, input, context) =>
-                beforeExecute(name, input, context).pipe(
-                  Effect.flatMap((event) => executeTool(tool, name, event.input, context)),
-                ),
-              )
-            : undefined
-          const codeModeCatalog = codemodeEnabled ? CodeModeTool.catalog(codemode) : undefined
-          return {
-            ...(codeModeCatalog === undefined ? {} : { codeModeCatalog }),
-            definitions: [
-              ...Array.from(direct)
-                .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
-                .map(([, tool]) => definition(tool)),
-              ...(codemodeTool ? [definition(codemodeTool)] : []),
-            ],
-            execute: Effect.fnUntraced(function* (input: Parameters<Snapshot["execute"]>[0]) {
-              const context: Tool.Context = {
-                sessionID: input.sessionID,
-                agent: input.agent,
-                messageID: input.messageID,
-                id: Tool.CallID.make(input.call.id),
-                progress: input.progress ?? (() => Effect.void),
-              }
-              const event = yield* beforeExecute(input.call.name, input.call.input, context)
-              const requested = input.definitions?.get(event.tool)
-              // Preserve session context removal and alias resolution, now after the repair hook.
-              if (!requested && input.definitions && (direct.has(event.tool) || codemodeTool?.name === event.tool))
-                return yield* new Tool.Error({ message: `Tool is not available for this request: ${event.tool}` })
-              const name = requested?.name ?? event.tool
-              if (name === "execute" && codemodeTool)
-                return yield* executeTool(codemodeTool, name, event.input, context)
-              const tool = direct.get(name)
-              if (tool) return yield* executeTool(tool, name, event.input, context)
-              return yield* new Tool.Error({ message: `Unknown tool: ${name}` })
-            }),
-          }
-        }),
+  const state: State.Interface<Data, Draft> = State.create<Data, Draft>({
+    name: "tool",
+    initial: () => ({
+      tools: new Map(),
+      errors: [],
+    }),
+    draft: (draft) => ({
+      list: () => Array.from(draft.tools.values()),
+      get: (id) => draft.tools.get(id),
+      add: (tool) => {
+        const error = registrationError(tool)
+        if (error) {
+          draft.errors.push({ tool, error })
+          return
+        }
+        const id = effectiveName(tool)
+        draft.tools.set(id, { ...tool, id, options: tool.options && { ...tool.options } })
+      },
+      update: (id, update) => {
+        const current = draft.tools.get(id)
+        if (!current) return
+        const tool = { ...current, options: current.options && { ...current.options } }
+        update(tool)
+        tool.name = current.name
+        tool.id = id
+        if (tool.options?.namespace !== current.options?.namespace)
+          tool.options = { ...tool.options, namespace: current.options?.namespace }
+        const error = registrationError(tool)
+        if (error) {
+          draft.errors.push({ tool, error })
+          return
+        }
+        draft.tools.set(id, tool)
+      },
+      remove: (id) => {
+        draft.tools.delete(id)
+      },
+    }),
+    finalize: () =>
+      Effect.forEach(
+        state.get().errors,
+        ({ tool, error }) =>
+          Effect.logError("Skipping invalid tool registration", {
+            name: tool.name,
+            namespace: tool.options?.namespace,
+            error: error.message,
+          }),
+        { discard: true },
       ),
-    })
-  }),
-)
+  })
+
+  return Service.of({
+    transform: state.transform,
+    reload: state.reload,
+    snapshot: Effect.fn("Tool.snapshot")((permissions) =>
+      Effect.sync(() => {
+        const active = new Map<string, Tool.Info>()
+        const rules = permissions ?? []
+        for (const [name, tool] of state.get().tools) {
+          if (whollyDisabled(tool.options?.permission ?? name, rules)) continue
+          active.set(name, tool)
+        }
+        const direct = new Map(Array.from(active).filter(([, tool]) => tool.options?.codemode === false))
+        const codemode = new Map(Array.from(active).filter(([, tool]) => tool.options?.codemode !== false))
+        const executeRule = rules.findLast((rule) => Wildcard.match("execute", rule.action))
+        const codemodeEnabled = executeRule?.resource !== "*" || executeRule.effect !== "deny"
+        const codemodeTool = codemodeEnabled
+          ? CodeModeTool.create(codemode, (name, tool, input, context) =>
+              beforeExecute(name, input, context).pipe(
+                Effect.flatMap((event) => executeTool(tool, name, event.input, context)),
+              ),
+            )
+          : undefined
+        const codeModeCatalog = codemodeEnabled ? CodeModeTool.catalog(codemode) : undefined
+        return {
+          ...(codeModeCatalog === undefined ? {} : { codeModeCatalog }),
+          definitions: [
+            ...Array.from(direct)
+              .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+              .map(([, tool]) => definition(tool)),
+            ...(codemodeTool ? [definition(codemodeTool)] : []),
+          ],
+          execute: Effect.fnUntraced(function* (input: Parameters<Snapshot["execute"]>[0]) {
+            const context: Tool.Context = {
+              sessionID: input.sessionID,
+              agent: input.agent,
+              messageID: input.messageID,
+              id: Tool.CallID.make(input.call.id),
+              progress: input.progress ?? (() => Effect.void),
+            }
+            const event = yield* beforeExecute(input.call.name, input.call.input, context)
+            const requested = input.definitions?.get(event.tool)
+            // Preserve session context removal and alias resolution, now after the repair hook.
+            if (!requested && input.definitions && (direct.has(event.tool) || codemodeTool?.name === event.tool))
+              return yield* new Tool.Error({ message: `Tool is not available for this request: ${event.tool}` })
+            const name = requested?.name ?? event.tool
+            if (name === "execute" && codemodeTool) return yield* executeTool(codemodeTool, name, event.input, context)
+            const tool = direct.get(name)
+            if (tool) return yield* executeTool(tool, name, event.input, context)
+            return yield* new Tool.Error({ message: `Unknown tool: ${name}` })
+          }),
+        }
+      }),
+    ),
+  })
+})
+
+const layer = Layer.effect(Service, make)
+
+export const snapshot = Effect.fn("Tool.snapshot")(function* (
+  values: readonly Tool.Info[],
+  permissions?: Permission.Ruleset,
+) {
+  const tools = yield* make
+  yield* tools.transform((draft) => values.forEach((tool) => draft.add(tool)))
+  return yield* tools.snapshot(permissions)
+}, Effect.scoped)
 
 const whollyDisabled = (action: string, rules: Permission.Ruleset) => {
   const rule = rules.findLast((rule) => Wildcard.match(action, rule.action))

packages/core/src/tool/runtime.ts

@@ -3,6 +3,7 @@ import { Tool } from "@opencode-ai/schema/tool"
 import type { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec"
 import { Cache, Effect, JsonSchema, Schema, SchemaIssue, SchemaRepresentation } from "effect"
 import { $ZodType, toJSONSchema } from "zod/v4/core"
+import { Permission } from "../permission.js"
 
 const formatEffectIssues = SchemaIssue.makeFormatterStandardSchemaV1()
 
@@ -27,19 +28,14 @@ export const definition = (tool: Tool.Info<any, any>): ToolDefinition => ({
 export const execute = (tool: Tool.Info<any, any>, input: unknown, context: Tool.Context) =>
   Effect.gen(function* () {
     const decoded = yield* decodeInput(tool, input)
-    // Tool implementations declare `Tool.Error` but plugins can fail with anything at
-    // runtime. A foreign typed failure would slip past every `catchTag("Tool.Error")`
-    // downstream and leave its call permanently unsettled, so the declared contract is
-    // enforced here at the untrusted boundary. Declines tunnel through as defects and
-    // interrupts are not errors; neither is touched.
+    // Normalize foreign typed failures so downstream Tool.Error handlers settle the call.
+    // Host declines enter Permission.assert's defect tunnel; existing defects and interrupts pass through.
     const result = yield* tool.execute(decoded, context).pipe(
-      Effect.mapError((error: unknown) =>
-        error instanceof Tool.Error
-          ? error
-          : new Tool.Error({
-              message: error instanceof globalThis.Error ? error.message : String(error),
-            }),
-      ),
+      Effect.catch((error) => {
+        if (error instanceof Permission.DeclinedError) return Effect.die(error)
+        if (error instanceof Tool.Error) return Effect.fail(error)
+        return Effect.fail(new Tool.Error({ message: error instanceof Error ? error.message : String(error) }))
+      }),
     )
     if (tool.output === undefined) {
       if ("output" in result) return yield* Effect.die("Tool result declared output without an output schema")

packages/core/test/fixture/capabilities.ts

@@ -0,0 +1,20 @@
+import { Effect, Schema } from "effect"
+import { SessionSchema } from "../../src/session/schema"
+import { Tool } from "../../src/tool"
+
+export const session = Schema.decodeUnknownSync(SessionSchema.Info)({
+  id: "ses_capabilities",
+  projectID: "global",
+  cost: 0,
+  tokens: { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } },
+  time: { created: 0, updated: 0 },
+  location: { directory: "/project" },
+})
+
+export const echo = (execute: (text: string) => Effect.Effect<string>, name = "echo"): Tool.Info => ({
+  name,
+  description: `Echo text with ${name}`,
+  input: Schema.Struct({ text: Schema.String }),
+  output: Schema.String,
+  execute: (input) => execute(input.text).pipe(Effect.map((output) => ({ output }))),
+})

packages/core/test/kv.test.ts

@@ -51,6 +51,8 @@ describe("KV", () => {
         entries: [{ key: `${prefix}éclair`, value: { order: 3 } }],
       })
       expect(yield* kv.scan({ prefix: `${prefix}%_` })).toEqual({ entries: [] })
+      expect(yield* kv.scanAll(`${prefix}%_`)).toEqual([])
+      expect(yield* kv.scanAll(prefix)).toEqual([...first.entries, { key: `${prefix}éclair`, value: { order: 3 } }])
     }),
   )
 
@@ -76,6 +78,15 @@ describe("KV", () => {
       expect((yield* kv.scan({ prefix, limit: 0 })).entries).toHaveLength(1)
       expect((yield* kv.scan({ prefix, limit: -10 })).entries).toHaveLength(1)
       expect((yield* kv.scan({ prefix, limit: Number.NaN })).entries).toHaveLength(100)
+
+      const all = kv.scanAll(prefix)
+      const entries = Array.from({ length: 1001 }, (_, index) => {
+        const key = `${prefix}${index.toString().padStart(4, "0")}`
+        return { key, value: key }
+      })
+      expect(yield* all).toEqual(entries)
+      yield* kv.remove(`${prefix}0000`)
+      expect(yield* all).toEqual(entries.slice(1))
     }),
   )
 })

packages/core/test/permissions-capabilities.test.ts

@@ -0,0 +1,102 @@
+import { expect } from "bun:test"
+import { Effect } from "effect"
+import { Permission } from "../src/permission"
+import { Permissions } from "../src/permissions"
+import { SessionSchema } from "../src/session/schema"
+import { Source } from "../src/source"
+import { session } from "./fixture/capabilities"
+import { it } from "./lib/effect"
+
+it.effect("allowAll permits requests and exposes an allow-all visibility rule", () =>
+  Effect.gen(function* () {
+    expect(yield* Permissions.allowAll.visibility.get(session)).toEqual([
+      { action: "*", resource: "*", effect: "allow" },
+    ])
+    yield* Permissions.allowAll.ask(session, { action: "write", resources: ["src/file.ts", "other/file.ts"] })
+  }),
+)
+
+it.effect("rules fail immediately for unmatched, ask, and denied resources", () =>
+  Effect.gen(function* () {
+    const request = { action: "read", resources: ["src/file.ts"] }
+    yield* Effect.forEach(
+      [
+        [],
+        [{ action: "read", resource: "*", effect: "ask" }],
+        [{ action: "read", resource: "*", effect: "deny" }],
+      ] satisfies Permission.Ruleset[],
+      (rules) =>
+        Effect.gen(function* () {
+          const permissions = Permissions.rules(rules)
+          expect(yield* permissions.visibility.get(session)).toBe(rules)
+          expect(yield* permissions.ask(session, request).pipe(Effect.flip)).toEqual(
+            new Permission.BlockedError({ rules, permission: request.action, resources: request.resources }),
+          )
+        }),
+    )
+  }),
+)
+
+it.effect("rules use wildcard precedence and require every resource to be allowed", () =>
+  Effect.gen(function* () {
+    const permissions = Permissions.rules([
+      { action: "*", resource: "*", effect: "deny" },
+      { action: "re*", resource: "src/*", effect: "allow" },
+      { action: "read", resource: "src/private/*", effect: "ask" },
+      { action: "read", resource: "src/private/public.ts", effect: "allow" },
+    ])
+    yield* permissions.ask(session, { action: "read", resources: ["src/file.ts", "src/private/public.ts"] })
+    expect(
+      yield* permissions
+        .ask(session, { action: "read", resources: ["src/file.ts", "src/private/file.ts"] })
+        .pipe(Effect.flip),
+    ).toBeInstanceOf(Permission.BlockedError)
+    expect(
+      yield* permissions.ask(session, { action: "write", resources: ["src/file.ts"] }).pipe(Effect.flip),
+    ).toBeInstanceOf(Permission.BlockedError)
+  }),
+)
+
+it.effect("blocked requests report action-relevant rules without inventing a reason", () =>
+  Effect.gen(function* () {
+    const rules: Permission.Ruleset = [
+      { action: "*", resource: "*", effect: "deny" },
+      { action: "write", resource: "*", effect: "allow" },
+      { action: "re*", resource: "other/*", effect: "allow" },
+      { action: "read", resource: "src/*", effect: "deny" },
+    ]
+    const request = { action: "read", resources: ["src/file.ts"] }
+    const relevant = [rules[0], rules[2], rules[3]]
+    expect(Permission.relevant(request, rules)).toEqual(relevant)
+    const error = yield* Permissions.rules(rules).ask(session, request).pipe(Effect.flip)
+    expect(error).toEqual(
+      new Permission.BlockedError({ rules: relevant, permission: request.action, resources: request.resources }),
+    )
+    if (error._tag !== "Permission.BlockedError") return yield* Effect.die("Expected blocked permission")
+    expect(error.reason).toBeUndefined()
+    expect(error.message).toBe("Permission denied: read")
+  }),
+)
+
+it.effect("rules sample mutable and session-dependent sources for visibility and each request", () =>
+  Effect.gen(function* () {
+    const source = Source.mutable<Permission.Ruleset>([])
+    const permissions = Permissions.rules(source)
+    const request = { action: "read", resources: ["src/file.ts"] }
+    expect(permissions.visibility).toBe(source)
+    expect(yield* permissions.ask(session, request).pipe(Effect.flip)).toBeInstanceOf(Permission.BlockedError)
+    yield* source.set([{ action: "read", resource: "*", effect: "allow" }])
+    yield* permissions.ask(session, request)
+    yield* source.update((rules) => [...rules, { action: "read", resource: "src/*", effect: "deny" }])
+    expect(yield* permissions.ask(session, request).pipe(Effect.flip)).toBeInstanceOf(Permission.BlockedError)
+
+    const scoped = Permissions.rules({
+      get: (current) =>
+        Effect.succeed([{ action: "read", resource: "*", effect: current.id === session.id ? "allow" : "deny" }]),
+    })
+    yield* scoped.ask(session, request)
+    const other = { ...session, id: SessionSchema.ID.make("ses_other") }
+    expect(yield* scoped.visibility.get(other)).toEqual([{ action: "read", resource: "*", effect: "deny" }])
+    expect(yield* scoped.ask(other, request).pipe(Effect.flip)).toBeInstanceOf(Permission.BlockedError)
+  }),
+)

packages/core/test/session-capabilities-recovery.test.ts

@@ -0,0 +1,223 @@
+import { describe, expect } from "bun:test"
+import { Bus } from "@opencode-ai/core/bus"
+import { Database } from "@opencode-ai/core/database/database"
+import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
+import { EventTable } from "@opencode-ai/core/event/sql"
+import { Job } from "@opencode-ai/core/job"
+import { KV } from "@opencode-ai/core/kv"
+import { LocationServiceMap } from "@opencode-ai/core/location-service-map"
+import { Project } from "@opencode-ai/core/project"
+import { ProjectTable } from "@opencode-ai/core/project/sql"
+import { AbsolutePath } from "@opencode-ai/core/schema"
+import { Session } from "@opencode-ai/core/session"
+import { SessionExecution } from "@opencode-ai/core/session/execution"
+import { SessionRestart } from "@opencode-ai/core/session/execution/restart"
+import { SessionResolve } from "@opencode-ai/core/session/resolve"
+import { SessionInboxTable, SessionMessageTable, SessionTable } from "@opencode-ai/core/session/sql"
+import { SessionStore } from "@opencode-ai/core/session/store"
+import { LayerNode } from "@opencode-ai/util/effect/layer-node"
+import { Effect, RcMap } from "effect"
+import { testEffect } from "./lib/effect"
+
+const it = testEffect(
+  AppNodeBuilder.build(
+    LayerNode.group([
+      Database.node,
+      Bus.node,
+      Job.node,
+      KV.node,
+      Session.node,
+      SessionStore.node,
+      SessionExecution.node,
+      SessionRestart.node,
+      SessionResolve.node,
+      LocationServiceMap.node,
+    ]),
+  ),
+)
+
+describe("capability-owned Session recovery", () => {
+  for (const claimed of [false, true]) {
+    it.effect(`leaves an owned Session ${claimed ? "with an exhausted claim" : "without a claim"} inert`, () =>
+      Effect.gen(function* () {
+        const database = yield* Database.Service
+        const resolve = yield* SessionResolve.Service
+        const restart = yield* SessionRestart.Service
+        const sessionID = Session.ID.make("ses_capability_recovery")
+        yield* seedSession(sessionID, claimed ? { time_suspended: 123, resume_attempts: 10 } : {})
+        yield* resolve.own(Effect.succeed({ id: sessionID }))
+        const before = yield* accounting(database)
+
+        expect(resolve.status(sessionID)).toBe("owned-detached")
+        yield* restart.resumeSuspendedSessions
+        yield* restart.resumeSuspendedSessions
+
+        expect(yield* accounting(database)).toEqual(before)
+        expect(resolve.status(sessionID)).toBe("owned-detached")
+        yield* assertInert()
+      }),
+    )
+  }
+
+  it.effect("keeps a completed Job pending for an unclaimed owned parent without waking it", () =>
+    Effect.gen(function* () {
+      const database = yield* Database.Service
+      const resolve = yield* SessionResolve.Service
+      const jobs = yield* Job.Service
+      const restart = yield* SessionRestart.Service
+      const parent = Session.ID.make("ses_capability_completed_parent")
+      const child = Session.ID.make("ses_capability_completed_child")
+      yield* seedSession(parent)
+      yield* seedSession(child, { parent_id: parent })
+      yield* resolve.own(Effect.succeed({ id: parent }))
+      yield* seedJob(
+        { kind: "subagent", parentSessionID: parent, childSessionID: child, agent: "explore", description: "Inspect" },
+        "completed",
+      )
+      const pending = yield* jobs.pendingBackground
+      const before = yield* accounting(database)
+
+      expect(pending).toMatchObject([{ status: "completed", output: "Recovered result" }])
+      yield* restart.resumeSuspendedSessions
+      yield* restart.resumeSuspendedSessions
+
+      expect(yield* jobs.pendingBackground).toEqual(pending)
+      expect(yield* jobs.get("recovery-job")).toBeUndefined()
+      expect(yield* accounting(database)).toEqual(before)
+      yield* assertInert()
+    }),
+  )
+
+  for (const owner of ["parent", "child"] as const) {
+    it.effect(`preserves child claims with a capability-owned ${owner} and pending running Job`, () =>
+      Effect.gen(function* () {
+        const database = yield* Database.Service
+        const resolve = yield* SessionResolve.Service
+        const jobs = yield* Job.Service
+        const restart = yield* SessionRestart.Service
+        const parent = Session.ID.make("ses_capability_running_parent")
+        const child = Session.ID.make("ses_capability_running_child")
+        const orphan = Session.ID.make("ses_capability_orphan_child")
+        yield* seedSession(parent, owner === "parent" ? { time_suspended: 789, resume_attempts: 10 } : {})
+        yield* seedSession(child, { parent_id: parent, time_suspended: 123, resume_attempts: 10 })
+        yield* seedSession(orphan, { parent_id: parent, time_suspended: 456, resume_attempts: 1 })
+        yield* resolve.own(Effect.succeed({ id: owner === "parent" ? parent : child }))
+        yield* resolve.own(Effect.succeed({ id: orphan }))
+        yield* seedJob(
+          {
+            kind: "subagent",
+            parentSessionID: parent,
+            childSessionID: child,
+            agent: "explore",
+            description: "Inspect",
+          },
+          "running",
+        )
+        const pending = yield* jobs.pendingBackground
+        const before = yield* accounting(database)
+
+        expect(pending).toMatchObject([{ status: "running" }])
+        yield* restart.resumeSuspendedSessions
+        yield* restart.resumeSuspendedSessions
+
+        expect(yield* jobs.pendingBackground).toEqual(pending)
+        expect(yield* jobs.get("recovery-job")).toBeUndefined()
+        expect(yield* accounting(database)).toEqual(before)
+        yield* assertInert()
+      }),
+    )
+  }
+
+  for (const status of ["running", "completed"] as const) {
+    it.effect(`keeps a ${status} shell Job pending for an owned Session`, () =>
+      Effect.gen(function* () {
+        const database = yield* Database.Service
+        const resolve = yield* SessionResolve.Service
+        const jobs = yield* Job.Service
+        const restart = yield* SessionRestart.Service
+        const sessionID = Session.ID.make("ses_capability_shell")
+        yield* seedSession(sessionID)
+        yield* resolve.own(Effect.succeed({ id: sessionID }))
+        yield* seedJob({ kind: "shell", sessionID, shellID: "sh_recovery", command: "echo result" }, status)
+        const pending = yield* jobs.pendingBackground
+        const before = yield* accounting(database)
+
+        yield* restart.resumeSuspendedSessions
+
+        expect(yield* jobs.pendingBackground).toEqual(pending)
+        expect(yield* accounting(database)).toEqual(before)
+        yield* assertInert()
+      }),
+    )
+  }
+})
+
+function seedSession(
+  sessionID: Session.ID,
+  values: Partial<Pick<typeof SessionTable.$inferInsert, "time_suspended" | "resume_attempts" | "parent_id">> = {},
+) {
+  return Effect.gen(function* () {
+    const database = yield* Database.Service
+    yield* database.db
+      .insert(ProjectTable)
+      .values({ id: Project.ID.global, worktree: AbsolutePath.make("/project"), sandboxes: [] })
+      .onConflictDoNothing()
+      .run()
+      .pipe(Effect.orDie)
+    yield* database.db
+      .insert(SessionTable)
+      .values({
+        id: sessionID,
+        project_id: Project.ID.global,
+        slug: sessionID,
+        directory: "/project",
+        title: sessionID,
+        version: "test",
+        ...values,
+      })
+      .run()
+      .pipe(Effect.orDie)
+  })
+}
+
+function seedJob(recovery: Job.Recovery, status: "running" | "completed") {
+  // A previous process-local Job registry leaves only its durable record behind.
+  return Effect.gen(function* () {
+    const jobs = yield* Job.make
+    yield* jobs.start({
+      id: "recovery-job",
+      type: recovery.kind,
+      recovery,
+      run: status === "running" ? Effect.never : Effect.succeed("Recovered result"),
+    })
+    yield* jobs.background("recovery-job")
+    if (status === "completed") yield* jobs.wait({ id: "recovery-job" })
+  }).pipe(Effect.scoped)
+}
+
+function accounting(database: Database.Service["Service"]) {
+  return database.db
+    .select({
+      id: SessionTable.id,
+      claimed: SessionTable.time_suspended,
+      attempts: SessionTable.resume_attempts,
+      updated: SessionTable.time_updated,
+    })
+    .from(SessionTable)
+    .orderBy(SessionTable.id)
+    .all()
+    .pipe(Effect.orDie)
+}
+
+function assertInert() {
+  return Effect.gen(function* () {
+    const database = yield* Database.Service
+    const execution = yield* SessionExecution.Service
+    const locations = yield* LocationServiceMap.Service
+    expect(yield* execution.active).toEqual(new Set())
+    expect(yield* database.db.select().from(EventTable).all().pipe(Effect.orDie)).toEqual([])
+    expect(yield* database.db.select().from(SessionMessageTable).all().pipe(Effect.orDie)).toEqual([])
+    expect(yield* database.db.select().from(SessionInboxTable).all().pipe(Effect.orDie)).toEqual([])
+    expect(Array.from(yield* RcMap.keys(locations.rcMap))).toEqual([])
+  })
+}

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

@@ -0,0 +1,871 @@
+import { describe, expect } from "bun:test"
+import { LanguageModel } from "@opencode-ai/ai"
+import { OpenAIChat } from "@opencode-ai/ai/protocols/openai-chat"
+import { TestLLM } from "@opencode-ai/ai/testing"
+import { Context, Deferred, Effect, Exit, Fiber, Layer, RcMap, Scope } from "effect"
+import { eq } from "drizzle-orm"
+import { LayerNode } from "@opencode-ai/util/effect/layer-node"
+import { AppNodeBuilder } from "../src/effect/app-node-builder"
+import { LayerNodePlatform } from "../src/effect/app-node-platform"
+import { Bus } from "../src/bus"
+import { Database } from "../src/database/database"
+import { Instructions } from "../src/instructions/index"
+import { KV } from "../src/kv"
+import { Session } from "../src/session"
+import { InstructionState } from "../src/session/instruction-state"
+import { SessionResolve } from "../src/session/resolve"
+import { SessionRunnerModel } from "../src/session/runner/model"
+import { InstructionBlobTable, InstructionStateTable, SessionTable } from "../src/session/sql"
+import { SessionStore } from "../src/session/store"
+import { Source } from "../src/source"
+import { SessionRestart } from "../src/session/execution/restart"
+import { Location } from "../src/location"
+import { AbsolutePath } from "../src/schema"
+import { InstructionEntry } from "../src/session/instruction-entry"
+import { Tool } from "../src/tool"
+import { testEffect } from "./lib/effect"
+import { tmpdir } from "./fixture/tmpdir"
+import path from "path"
+import { LocationServiceMap } from "../src/location-service-map"
+import { Skill } from "../src/skill"
+import { Permissions } from "../src/permissions"
+import { Permission } from "../src/permission"
+import { SessionMessage } from "../src/session/message"
+import { PluginHooks } from "../src/plugin/hooks"
+import { echo } from "./fixture/capabilities"
+import { App } from "../src/app"
+import { SessionExecution } from "../src/session/execution"
+
+const scripted = TestLLM.layer()
+const application = AppNodeBuilder.build(
+  LayerNode.group([
+    Session.node,
+    SessionExecution.node,
+    LocationServiceMap.node,
+    SessionResolve.node,
+    SessionStore.node,
+    SessionRestart.node,
+    Database.node,
+    Bus.node,
+    KV.node,
+    InstructionEntry.node,
+    PluginHooks.node,
+  ]),
+  [
+    [App.node, App.configured({ name: "fixture-host" })],
+    [Bus.node, Bus.configured({ persist: true })],
+    [LayerNodePlatform.llmClient, TestLLM.clientLayer.pipe(Layer.provide(scripted))],
+  ],
+).pipe(Layer.provideMerge(scripted))
+const it = testEffect(application)
+const isolated = testEffect(scripted)
+const model = SessionRunnerModel.resolved(
+  LanguageModel.make({ id: "fixture-model", provider: "fixture", route: OpenAIChat.route }),
+  {
+    capabilities: { tools: true, input: ["text", "image"], output: ["text"] },
+    cost: [],
+    limit: { context: 200_000, output: 32_000 },
+  },
+)
+
+describe("Session capabilities", () => {
+  it.live("closing a replacement during retirement leaves late admitted work parked", () =>
+    Effect.gen(function* () {
+      const sessions = yield* Session.Service
+      const llm = yield* TestLLM.Service
+      const locations = yield* LocationServiceMap.Service
+      const retiring = yield* Deferred.make<void>()
+      const release = yield* Deferred.make<void>()
+      yield* Effect.addFinalizer(() => Deferred.succeed(release, undefined))
+      const gate = yield* llm.gate
+      const session = yield* sessions.open({
+        model,
+        retire: () => Deferred.succeed(retiring, undefined).pipe(Effect.andThen(Deferred.await(release))),
+      })
+      yield* llm.push(TestLLM.text("first done", "late_close_reply"))
+      const running = yield* session.prompt({ text: "First busy period." }).pipe(Effect.forkScoped)
+      yield* llm.wait(1)
+      const replacement = yield* sessions.open({ id: session.id, model })
+      yield* gate.release
+      yield* Deferred.await(retiring)
+      yield* sessions.prompt({ sessionID: session.id, text: "Late work." })
+      yield* replacement.close()
+      yield* Deferred.succeed(release, undefined)
+      yield* Fiber.join(running)
+      yield* sessions.wait(session.id)
+      expect(Array.from(yield* RcMap.keys(locations.rcMap))).toEqual([])
+      expect(yield* sessions.inbox(session.id)).toHaveLength(1)
+      expect(llm.requests).toHaveLength(1)
+      const reopened = yield* sessions.open({ id: session.id, model })
+      yield* llm.push(TestLLM.text("late work drained", "late_reopened_reply"))
+      // An advisory wake after reopen delivers the already-admitted item, without a new prompt.
+      const execution = yield* SessionExecution.Service
+      yield* execution.wake(reopened.id)
+      yield* sessions.wait(reopened.id)
+      expect(yield* sessions.inbox(reopened.id)).toHaveLength(0)
+      expect(llm.requests).toHaveLength(2)
+      expect(JSON.stringify(llm.requests[1].messages)).toContain("Late work.")
+      expect(Array.from(yield* RcMap.keys(locations.rcMap))).toEqual([])
+    }),
+  )
+
+  it.live("failed durable ownership writes do not poison the memory index", () =>
+    Effect.gen(function* () {
+      const sessions = yield* Session.Service
+      const resolve = yield* SessionResolve.Service
+      const store = yield* SessionStore.Service
+      const db = (yield* Database.Service).db
+      const id = Session.ID.make("ses_rejected_marker")
+      yield* db
+        .run("CREATE TRIGGER reject_marker BEFORE INSERT ON kv BEGIN SELECT RAISE(ABORT, 'marker rejected'); END")
+        .pipe(Effect.orDie)
+      const exit = yield* sessions
+        .open({ id, model })
+        .pipe(Effect.exit, Effect.ensuring(db.run("DROP TRIGGER reject_marker").pipe(Effect.orDie)))
+      expect(exit._tag).toBe("Failure")
+      expect(yield* store.get(id)).toBeUndefined()
+      expect(resolve.status(id)).toBe("unowned")
+      const session = yield* sessions.open({ id, model })
+      expect(resolve.status(id)).toBe("attached")
+      yield* session.close()
+    }),
+  )
+
+  it.live("pins at coordinator start before a close can retire the new busy period", () =>
+    Effect.gen(function* () {
+      const sessions = yield* Session.Service
+      const execution = yield* SessionExecution.Service
+      const resolve = yield* SessionResolve.Service
+      const llm = yield* TestLLM.Service
+      const session = yield* sessions.open({ model })
+      yield* session.prompt({ text: "Begin before close.", resume: false })
+      yield* llm.push(TestLLM.text("settled", "start_close_reply"))
+      const running = yield* execution.resume(session.id).pipe(Effect.forkScoped({ startImmediately: true }))
+      expect((yield* execution.active).has(session.id)).toBe(true)
+      const closing = yield* session.close().pipe(Effect.forkScoped({ startImmediately: true }))
+      expect(resolve.status(session.id)).toBe("owned-detached")
+      yield* Fiber.join(running)
+      yield* Fiber.join(closing)
+      expect(llm.requests).toHaveLength(1)
+    }),
+  )
+
+  it.live("close waits for busy-period settlement, preserves history, and cannot close a replacement", () =>
+    Effect.gen(function* () {
+      const sessions = yield* Session.Service
+      const resolve = yield* SessionResolve.Service
+      const llm = yield* TestLLM.Service
+      const started = yield* Deferred.make<void>()
+      const release = yield* Deferred.make<void>()
+      const retired: string[] = []
+      const session = yield* sessions.open({
+        model,
+        tools: [
+          echo((text) =>
+            Deferred.succeed(started, undefined).pipe(
+              Effect.andThen(Deferred.await(release)),
+              Effect.as(text),
+              Effect.ensuring(
+                Effect.sync(() => {
+                  retired.push("tool")
+                }),
+              ),
+            ),
+          ),
+        ],
+        retire: () =>
+          Effect.sync(() => {
+            retired.push("old")
+          }),
+      })
+      yield* llm.push(
+        TestLLM.tool("close_tool", "execute", { code: 'return await tools.echo({ text: "settled" })' }),
+        TestLLM.text("settled", "close_reply"),
+      )
+      const prompting = yield* session.prompt({ text: "Work before close." }).pipe(Effect.forkScoped)
+      yield* Deferred.await(started)
+      const closing = yield* session.close().pipe(Effect.forkScoped({ startImmediately: true }))
+      expect(resolve.status(session.id)).toBe("owned-detached")
+      expect(retired).toEqual([])
+      expect(llm.requests).toHaveLength(1)
+      yield* Deferred.succeed(release, undefined)
+      yield* Fiber.join(prompting)
+      yield* Fiber.join(closing)
+      expect(retired).toEqual(["tool", "old"])
+      expect(llm.requests).toHaveLength(2)
+      expect(yield* sessions.messages({ sessionID: session.id })).toHaveLength(3)
+      expect((yield* session.resume().pipe(Effect.exit)).toString()).toContain("must be reopened with capabilities")
+      expect(llm.requests).toHaveLength(2)
+      const reopened = yield* sessions.open({
+        id: session.id,
+        model,
+        retire: () =>
+          Effect.sync(() => {
+            retired.push("new")
+          }),
+      })
+      yield* session.close()
+      expect(resolve.status(session.id)).toBe("attached")
+      yield* reopened.close()
+      yield* reopened.close()
+      expect(retired).toEqual(["tool", "old", "new"])
+      expect(resolve.status(session.id)).toBe("owned-detached")
+    }),
+  )
+
+  it.live("cached snapshots skip rebuilding but reread all selection capabilities", () =>
+    Effect.gen(function* () {
+      const sessions = yield* Session.Service
+      const resolve = yield* SessionResolve.Service
+      const entries = yield* InstructionEntry.Service
+      const tools = Source.mutable([echo(Effect.succeed)])
+      const rules = Source.mutable<Permission.Ruleset>([{ action: "*", resource: "*", effect: "allow" }])
+      const counts = { tools: 0, rules: 0, limits: 0 }
+      const session = yield* sessions.open({
+        model,
+        tools: {
+          get: (session) =>
+            Effect.sync(() => {
+              counts.tools++
+            }).pipe(Effect.andThen(tools.get(session))),
+        },
+        permissions: {
+          ask: Permissions.allowAll.ask,
+          visibility: {
+            get: (session) =>
+              Effect.sync(() => {
+                counts.rules++
+              }).pipe(Effect.andThen(rules.get(session))),
+          },
+        },
+        limits: { get: () => Effect.sync(() => ({ steps: ++counts.limits })) },
+      })
+      const resolved = yield* resolve.resolve(yield* sessions.get(session.id))
+      if (resolved.status !== "attached") return yield* Effect.die("Expected open capabilities")
+      const first = yield* resolved.capabilities.select(session.id)
+      yield* entries.put({ sessionID: session.id, key: InstructionEntry.Key.make("cache-proof"), value: "Fresh entry" })
+      const second = yield* resolved.capabilities.select(session.id)
+      expect(second.tools).toBe(first.tools)
+      expect(second.agent.info.steps).toBe(2)
+      expect(second.instructions.map((source) => source.key)).toContain(Instructions.Key.make("api/cache-proof"))
+      expect(counts).toEqual({ tools: 2, rules: 2, limits: 2 })
+      const original = yield* tools.get(first.session)
+      yield* tools.set([...original])
+      const replaced = yield* resolved.capabilities.select(session.id)
+      expect(replaced.tools).not.toBe(first.tools)
+      yield* tools.set(original)
+      const restored = yield* resolved.capabilities.select(session.id)
+      expect(restored.tools).not.toBe(first.tools)
+      expect(restored.tools).not.toBe(replaced.tools)
+      yield* rules.update((rules) => [...rules])
+      const repolicy = yield* resolved.capabilities.select(session.id)
+      expect(repolicy.tools).not.toBe(restored.tools)
+      expect(counts).toEqual({ tools: 5, rules: 5, limits: 5 })
+    }),
+  )
+
+  it.live("reopens already-owned Sessions without rewriting KV and skips unowned removal", () =>
+    Effect.gen(function* () {
+      const sessions = yield* Session.Service
+      const resolve = yield* SessionResolve.Service
+      const db = (yield* Database.Service).db
+      const session = yield* sessions.open({ model })
+      yield* db.run("PRAGMA query_only = ON").pipe(Effect.orDie)
+      yield* Effect.gen(function* () {
+        yield* sessions.open({ id: session.id, model })
+        yield* resolve.remove(Session.ID.make("ses_unowned_removal"))
+        expect(resolve.status(session.id)).toBe("attached")
+      }).pipe(Effect.ensuring(db.run("PRAGMA query_only = OFF").pipe(Effect.orDie)))
+    }),
+  )
+
+  it.live("fresh local defaults do not inherit plugin state from the host's root composition", () =>
+    Effect.gen(function* () {
+      const sessions = yield* Session.Service
+      const hooks = yield* PluginHooks.Service
+      const llm = yield* TestLLM.Service
+      const executed: string[] = []
+      yield* hooks.register(
+        "tool",
+        "execute.before",
+        () => new Tool.Error({ message: "Root plugin rejected execution" }),
+      )
+      yield* hooks.register("session", "prompt", (event) =>
+        Effect.sync(() => {
+          event.prompt.text = "Root prompt interceptor must not reach supplied capabilities"
+        }),
+      )
+      const session = yield* sessions.open({
+        model,
+        tools: [
+          echo((text) =>
+            Effect.sync(() => {
+              executed.push(text)
+              return text
+            }),
+          ),
+        ],
+      })
+      yield* llm.push(
+        TestLLM.tool("root_isolation", "execute", { code: 'return await tools.echo({ text: "local" })' }),
+        TestLLM.text("finished", "root_isolation_reply"),
+      )
+      yield* session.prompt({ text: "Execute with local defaults." })
+      expect(executed).toEqual(["local"])
+      expect(JSON.stringify(llm.requests)).not.toContain("Root plugin rejected execution")
+      expect(JSON.stringify(llm.requests)).not.toContain("Root prompt interceptor")
+    }),
+  )
+
+  isolated.live("reconstructs over durable storage with zero model calls until reopen and explicit drive", () =>
+    Effect.gen(function* () {
+      const directory = yield* Effect.acquireRelease(
+        Effect.promise(() => tmpdir("session-capabilities-")),
+        (directory) => Effect.promise(() => directory[Symbol.asyncDispose]()),
+      )
+      const llm = yield* TestLLM.Service
+      const root = AppNodeBuilder.build(
+        LayerNode.group([
+          Session.node,
+          SessionResolve.node,
+          SessionStore.node,
+          SessionRestart.node,
+          LocationServiceMap.node,
+          Database.node,
+        ]),
+        [
+          [Database.node, Database.configured({ path: path.join(directory.path, "sessions.db") })],
+          [Bus.node, Bus.configured({ persist: true })],
+          [LayerNodePlatform.llmClient, TestLLM.clientLayer.pipe(Layer.provide(Layer.succeed(TestLLM.Service, llm)))],
+        ],
+      )
+      const firstScope = yield* Scope.make()
+      yield* Effect.addFinalizer(() => Scope.close(firstScope, Exit.void))
+      const first = yield* Layer.buildWithScope(Layer.fresh(root), firstScope)
+      const sessions = Context.get(first, Session.Service)
+      const input = { model, instructions: ["Persist across restarts."], tools: [echo(Effect.succeed)] }
+      const session = yield* sessions.open(input)
+      const initial = yield* sessions.get(session.id)
+      // A process may die after open's durable writes, before admission or a claim.
+      yield* Context.get(first, SessionRestart.Service).resumeSuspendedSessions
+      expect(llm.requests).toHaveLength(0)
+      expect(yield* Context.get(first, SessionStore.Service).listSuspended()).toEqual([])
+      yield* session.prompt({ text: "Pending work.", resume: false })
+      yield* Context.get(first, SessionStore.Service).claim(session.id)
+      yield* Scope.close(firstScope, Exit.void)
+      // Status and unowned cleanup must remain pure memory operations, even with storage closed.
+      expect(Context.get(first, SessionResolve.Service).status(session.id)).toBe("owned-detached")
+      expect(Context.get(first, SessionResolve.Service).status(Session.ID.make("ses_unknown"))).toBe("unowned")
+      yield* Context.get(first, SessionResolve.Service).remove(Session.ID.make("ses_unknown"))
+
+      const secondScope = yield* Scope.make()
+      yield* Effect.addFinalizer(() => Scope.close(secondScope, Exit.void))
+      const second = yield* Layer.buildWithScope(Layer.fresh(root), secondScope)
+      const restarted = Context.get(second, Session.Service)
+      const recovery = Context.get(second, SessionRestart.Service)
+      const db = Context.get(second, Database.Service).db
+      yield* recovery.resumeSuspendedSessions
+      expect(llm.requests).toHaveLength(0)
+      expect(yield* Context.get(second, SessionStore.Service).listSuspended()).toEqual([session.id])
+      const waiting = yield* db
+        .select()
+        .from(SessionTable)
+        .where(eq(SessionTable.id, session.id))
+        .get()
+        .pipe(Effect.orDie)
+      expect(waiting?.time_suspended).not.toBeNull()
+      expect(waiting?.resume_attempts).toBe(0)
+      expect(Array.from(yield* RcMap.keys(Context.get(second, LocationServiceMap.Service).rcMap))).toEqual([])
+      const reopened = yield* restarted.open({ ...input, id: session.id, title: "ignored" })
+      expect((yield* restarted.get(session.id)).location).toEqual(initial.location)
+      expect((yield* restarted.get(session.id)).projectID).toBe(initial.projectID)
+      yield* recovery.resumeSuspendedSessions
+      expect(llm.requests).toHaveLength(0)
+      yield* llm.push(TestLLM.text("resumed", "recovery_reply"))
+      yield* reopened.resume()
+      expect(llm.requests).toHaveLength(1)
+      expect(llm.requests[0].system.map((part) => part.text).join("\n")).toContain("Persist across restarts.")
+      expect(yield* Context.get(second, SessionStore.Service).listSuspended()).toEqual([])
+      expect(
+        (yield* restarted.messages({ sessionID: session.id })).filter((message) => message.type === "assistant"),
+      ).toHaveLength(1)
+      expect(Array.from(yield* RcMap.keys(Context.get(second, LocationServiceMap.Service).rcMap))).toEqual([])
+    }),
+  )
+
+  it.live("opens with values and drains through tools, durable history, and the instruction epoch", () =>
+    Effect.gen(function* () {
+      const llm = yield* TestLLM.Service
+      const sessions = yield* Session.Service
+      const db = (yield* Database.Service).db
+      const kv = yield* KV.Service
+      const executed: string[] = []
+      const tools = Source.mutable([
+        echo((text) =>
+          Effect.sync(() => {
+            executed.push(text)
+            return text
+          }),
+        ),
+      ])
+      const session = yield* sessions.open({ model, tools, instructions: ["Keep replies brief."] })
+      expect(llm.requests).toHaveLength(0)
+      expect(yield* kv.get(`session.capabilities/${session.id}`)).toBe(true)
+      const row = yield* db.select().from(SessionTable).where(eq(SessionTable.id, session.id)).get().pipe(Effect.orDie)
+      expect(row?.time_suspended).toBeNull()
+      yield* llm.push(
+        TestLLM.tool("echo_call", "execute", { code: 'return await tools.echo({ text: "hello" })' }),
+        TestLLM.text("done", "reply"),
+      )
+      yield* session.prompt({ text: "Use echo." })
+      expect(executed).toEqual(["hello"])
+      expect(llm.requests).toHaveLength(2)
+      expect(llm.requests[0]?.tools.map((tool) => tool.name)).toEqual(["execute"])
+      expect(llm.requests[0]?.http?.headers?.["x-opencode-client"]).toBe("fixture-host")
+      expect(llm.requests[0]?.system.map((part) => part.text).join("\n")).toContain("Keep replies brief.")
+      const history = yield* sessions.messages({ sessionID: session.id })
+      expect(history.filter((message) => message.type === "user")).toHaveLength(1)
+      expect(history.filter((message) => message.type === "assistant")).toHaveLength(2)
+      expect(
+        history.some(
+          (message) =>
+            message.type === "assistant" &&
+            message.content.some((part) => part.type === "tool" && part.state.status === "completed"),
+        ),
+      ).toBe(true)
+      const state = yield* db
+        .select()
+        .from(InstructionStateTable)
+        .where(eq(InstructionStateTable.session_id, session.id))
+        .get()
+        .pipe(Effect.orDie)
+      expect(state?.initial_values["session/instructions"]).toBe(Instructions.hash(["Keep replies brief."]))
+      expect(state?.current_values).toEqual(state?.initial_values)
+      const blob = yield* db
+        .select()
+        .from(InstructionBlobTable)
+        .where(eq(InstructionBlobTable.hash, Instructions.hash(["Keep replies brief."])))
+        .get()
+        .pipe(Effect.orDie)
+      expect(blob?.value).toEqual(["Keep replies brief."])
+    }),
+  )
+
+  it.live("admits images without discovery and rejects undiscovered skill mentions as missing", () =>
+    Effect.gen(function* () {
+      const sessions = yield* Session.Service
+      const llm = yield* TestLLM.Service
+      const session = yield* sessions.open({ model })
+      const admitted = yield* session.prompt({
+        text: "Inspect this image.",
+        files: [
+          {
+            uri: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=",
+          },
+        ],
+        resume: false,
+      })
+      expect(admitted.payload.files?.[0]?.mime).toBe("image/png")
+      expect(llm.requests).toHaveLength(0)
+      expect(
+        yield* session
+          .prompt({ text: "Use a missing skill.", skills: [{ id: Skill.ID.make("missing") }], resume: false })
+          .pipe(Effect.flip),
+      ).toBeInstanceOf(Session.SkillNotFoundError)
+      yield* llm.push(TestLLM.text("image received", "image_reply"))
+      yield* session.resume()
+      expect(llm.requests).toHaveLength(1)
+    }),
+  )
+
+  it.live("an unavailable initial Source leaves admitted input pending without a model call", () =>
+    Effect.gen(function* () {
+      const llm = yield* TestLLM.Service
+      const sessions = yield* Session.Service
+      const instructions = Source.mutable<ReadonlyArray<string> | Instructions.Unavailable>(Instructions.unavailable)
+      const session = yield* sessions.open({ model, instructions })
+      expect(yield* session.prompt({ text: "Wait for policy." }).pipe(Effect.flip)).toBeInstanceOf(
+        Instructions.InitializationBlocked,
+      )
+      expect(llm.requests).toHaveLength(0)
+      expect(yield* sessions.inbox(session.id)).toHaveLength(1)
+      yield* instructions.set(["Policy is ready."])
+      yield* llm.push(TestLLM.text("ready", "ready_reply"))
+      yield* session.resume()
+      expect(llm.requests[0].system.map((part) => part.text).join("\n")).toContain("Policy is ready.")
+    }),
+  )
+
+  it.live("host permission declines interrupt while corrections remain model-facing", () =>
+    Effect.gen(function* () {
+      const llm = yield* TestLLM.Service
+      const sessions = yield* Session.Service
+      for (const outcome of ["decline", "correction", "foreign"]) {
+        const correction = outcome === "correction"
+        const declined = outcome === "decline"
+        const permissions: Permissions.Interface = {
+          visibility: Permissions.allowAll.visibility,
+          ask: () =>
+            correction
+              ? new Permission.CorrectedError({ feedback: "Use a safer value." })
+              : new Permission.DeclinedError(),
+        }
+        const tool: Tool.Info = {
+          ...echo(Effect.succeed),
+          options: { codemode: false },
+          execute: (input, invocation) =>
+            Effect.gen(function* () {
+              if (outcome === "foreign") return yield* Effect.fail(new Error("ordinary failure"))
+              const session = yield* sessions.get(Session.ID.make(invocation.sessionID))
+              yield* permissions
+                .ask(session, { action: "echo", resources: [input.text] })
+                .pipe(
+                  Effect.catchTag("Permission.CorrectedError", (error) => new Tool.Error({ message: error.feedback })),
+                )
+              return { output: input.text }
+            }),
+        }
+        const session = yield* sessions.open({ model, tools: [tool], permissions })
+        const before = llm.requests.length
+        yield* llm.push(TestLLM.tool(`permission_${outcome}`, "echo", { text: "requested" }))
+        if (!declined) yield* llm.push(TestLLM.text("continued", `continued_${outcome}`))
+        const exit = yield* session.prompt({ text: "Request echo." }).pipe(Effect.exit)
+        expect(exit._tag).toBe(declined ? "Failure" : "Success")
+        expect(llm.requests.length - before).toBe(declined ? 1 : 2)
+        const calls = (yield* sessions.messages({ sessionID: session.id })).flatMap((message) =>
+          message.type === "assistant" ? message.content.filter((part) => part.type === "tool") : [],
+        )
+        expect(calls[0].state.status).toBe("error")
+        if (calls[0].state.status !== "error") return yield* Effect.die("Expected durable tool failure")
+        expect(calls[0].state.error.message).toBe(
+          declined ? "The user declined this tool call" : correction ? "Use a safer value." : "ordinary failure",
+        )
+        if (!declined)
+          expect(JSON.stringify(llm.requests[before + 1].messages)).toContain(
+            correction ? "Use a safer value." : "ordinary failure",
+          )
+        if (!declined) {
+          const db = (yield* Database.Service).db
+          expect(
+            (yield* db.select().from(SessionTable).where(eq(SessionTable.id, session.id)).get().pipe(Effect.orDie))
+              ?.time_suspended,
+          ).toBeNull()
+        }
+      }
+    }),
+  )
+
+  it.live("fresh open and reopen share effective capabilities and identical request assembly", () =>
+    Effect.gen(function* () {
+      const sessions = yield* Session.Service
+      const resolve = yield* SessionResolve.Service
+      const db = (yield* Database.Service).db
+      const bus = yield* Bus.Service
+      const llm = yield* TestLLM.Service
+      const input = { model, tools: [echo(Effect.succeed)], instructions: ["Stable policy."], system: "Stable system." }
+      const session = yield* sessions.open(input)
+      yield* llm.push(TestLLM.text("done", "parity_reply"))
+      yield* session.prompt({ text: "hello" })
+      const before = yield* sessions.get(session.id)
+      const first = yield* resolve.resolve(before)
+      if (first.status !== "attached") return yield* Effect.die("Expected supplied capabilities")
+      const selected = yield* first.capabilities.select(session.id)
+      yield* InstructionState.prepare(db, bus, selected.instructions, session.id)
+      const loaded = yield* first.capabilities.load(selected)
+      const prepare = (capabilities: typeof first.capabilities, value: typeof loaded) =>
+        capabilities.prepare({
+          scope: { session: value.session, agentID: value.agent.id, model: value.model, tools: value.tools },
+          transcript: { system: [...llm.requests[0].system], messages: [...llm.requests[0].messages] },
+        })
+      const initial = yield* prepare(first.capabilities, loaded)
+      const sequence = yield* Bus.latestSequence(db, session.id)
+      const reopened = yield* sessions.open({ ...input, id: session.id, title: "ignored on adopt" })
+      expect(yield* sessions.get(reopened.id)).toEqual(before)
+      const second = yield* resolve.resolve(before)
+      if (second.status !== "attached") return yield* Effect.die("Expected reopened capabilities")
+      const reselected = yield* second.capabilities.select(reopened.id)
+      yield* InstructionState.prepare(db, bus, reselected.instructions, reopened.id)
+      const reloaded = yield* second.capabilities.load(reselected)
+      expect(reloaded.initial).toBe(loaded.initial)
+      expect(reloaded.agent).toEqual(loaded.agent)
+      expect(reloaded.model).toEqual(loaded.model)
+      expect(reloaded.tools.definitions).toEqual(loaded.tools.definitions)
+      expect((yield* prepare(second.capabilities, reloaded)).request).toEqual(initial.request)
+      const call = {
+        sessionID: session.id,
+        agent: loaded.agent.id,
+        messageID: SessionMessage.ID.create(),
+        call: {
+          type: "tool-call" as const,
+          id: "parity_echo",
+          name: "execute",
+          input: { code: 'return await tools.echo({ text: "same" })' },
+        },
+      }
+      expect(yield* reloaded.tools.execute(call)).toEqual(yield* loaded.tools.execute(call))
+      expect(yield* Bus.latestSequence(db, session.id)).toBe(sequence)
+
+      const prior = yield* sessions.create({
+        location: Location.Ref.make({ directory: AbsolutePath.make("/prior-host") }),
+      })
+      const adopted = yield* sessions.open({ ...input, id: prior.id })
+      expect(yield* sessions.get(adopted.id)).toEqual(prior)
+      yield* llm.push(TestLLM.text("reconnected", "adopt_reply"))
+      yield* adopted.prompt({ text: "Reconnect from a different cwd." })
+      expect((yield* sessions.get(prior.id)).location).toEqual(prior.location)
+    }),
+  )
+
+  it.live("hot Sources produce chronological diffs alongside durable entries between busy periods", () =>
+    Effect.gen(function* () {
+      const llm = yield* TestLLM.Service
+      const sessions = yield* Session.Service
+      const entries = yield* InstructionEntry.Service
+      const db = (yield* Database.Service).db
+      const instructions = Source.mutable<ReadonlyArray<string> | Instructions.Unavailable>(["First policy."])
+      const tools = Source.mutable([echo(Effect.succeed)])
+      const session = yield* sessions.open({ model, tools, instructions })
+      yield* entries.put({
+        sessionID: session.id,
+        key: InstructionEntry.Key.make("thread-policy"),
+        value: "Durable policy.",
+      })
+      yield* llm.push(TestLLM.text("first", "first_reply"))
+      yield* session.prompt({ text: "first" })
+      const initial = llm.requests[0].system
+      yield* instructions.update(() => ["Second policy."])
+      yield* tools.update(() => [echo(Effect.succeed, "second_echo")])
+      yield* llm.push(TestLLM.text("second", "second_reply"))
+      yield* session.prompt({ text: "second" })
+      expect(llm.requests[1].system).toEqual(initial)
+      const updates = (yield* sessions.messages({ sessionID: session.id })).filter(
+        (message) => message.type === "system",
+      )
+      expect(updates).toHaveLength(1)
+      expect(updates[0].text).toContain("Second policy.")
+      expect(updates[0].text).toContain("second_echo")
+      expect(
+        llm.requests[1].messages.some(
+          (message) =>
+            message.role === "system" &&
+            message.content.some((part) => part.type === "text" && part.text.includes("Second policy.")),
+        ),
+      ).toBe(true)
+      const state = yield* db
+        .select()
+        .from(InstructionStateTable)
+        .where(eq(InstructionStateTable.session_id, session.id))
+        .get()
+        .pipe(Effect.orDie)
+      expect(state?.initial_values["session/instructions"]).toBe(Instructions.hash(["First policy."]))
+      expect(state?.current_values["session/instructions"]).toBe(Instructions.hash(["Second policy."]))
+      expect(state?.current_values["api/thread-policy"]).toBe(Instructions.hash("Durable policy."))
+
+      yield* instructions.set(Instructions.unavailable)
+      yield* llm.push(TestLLM.text("retained", "retained_reply"))
+      yield* session.prompt({ text: "temporarily unavailable" })
+      expect(
+        (yield* sessions.messages({ sessionID: session.id })).filter((message) => message.type === "system"),
+      ).toHaveLength(1)
+      yield* instructions.set([])
+      yield* llm.push(TestLLM.text("removed", "removed_reply"))
+      yield* session.prompt({ text: "removed" })
+      expect(
+        (yield* sessions.messages({ sessionID: session.id, order: "asc" }))
+          .filter((message) => message.type === "system")
+          .at(-1)?.text,
+      ).toContain("no longer apply")
+    }),
+  )
+
+  it.live("pins capabilities across coalesced drains but rereads their Sources at safe boundaries", () =>
+    Effect.gen(function* () {
+      const llm = yield* TestLLM.Service
+      const sessions = yield* Session.Service
+      const began = yield* Deferred.make<void>()
+      const release = yield* Deferred.make<void>()
+      const settled: string[] = []
+      const executed: string[] = []
+      const tools = Source.mutable([
+        echo((text) =>
+          Deferred.succeed(began, undefined).pipe(
+            Effect.andThen(Deferred.await(release)),
+            Effect.andThen(
+              Effect.sync(() => {
+                executed.push("old")
+                return text
+              }),
+            ),
+            Effect.ensuring(
+              Effect.sync(() => {
+                settled.push("tool")
+              }),
+            ),
+          ),
+        ),
+      ])
+      const instructions = Source.mutable(["Old policy."])
+      const session = yield* sessions.open({
+        model,
+        tools,
+        instructions,
+        retire: () =>
+          Effect.sync(() => {
+            settled.push("retired")
+          }),
+      })
+      yield* llm.push(
+        TestLLM.tool("blocked_echo", "execute", { code: 'return await tools.echo({ text: "blocked" })' }),
+        TestLLM.tool("updated_echo", "execute", { code: 'return await tools.updated_echo({ text: "updated" })' }),
+        TestLLM.text("finished", "busy_reply"),
+      )
+      const prompting = yield* session.prompt({ text: "Start work." }).pipe(Effect.forkScoped)
+      yield* Deferred.await(began)
+      yield* sessions.open({
+        model,
+        id: session.id,
+        tools: [
+          echo(
+            (text) =>
+              Effect.sync(() => {
+                executed.push("replacement")
+                return text
+              }),
+            "replacement_echo",
+          ),
+        ],
+        instructions: ["Replacement policy."],
+      })
+      expect(settled).toEqual([])
+      yield* tools.set([
+        echo(
+          (text) =>
+            Effect.sync(() => {
+              executed.push("updated source")
+              return text
+            }),
+          "updated_echo",
+        ),
+      ])
+      yield* instructions.set(["Updated old policy."])
+      yield* sessions.prompt({ sessionID: session.id, text: "Steer during work." })
+      yield* Deferred.succeed(release, undefined)
+      yield* Fiber.join(prompting)
+      yield* sessions.wait(session.id)
+      expect(executed).toEqual(["old", "updated source"])
+      expect(settled).toEqual(["tool", "retired"])
+      expect(
+        llm.requests[1].messages.some(
+          (message) =>
+            message.role === "system" &&
+            message.content.some((part) => part.type === "text" && part.text.includes("Updated old policy.")),
+        ),
+      ).toBe(true)
+      expect(JSON.stringify(llm.requests.slice(0, 3))).not.toContain("Replacement policy.")
+      yield* llm.push(
+        TestLLM.tool("replacement_call", "execute", {
+          code: 'return await tools.replacement_echo({ text: "replacement" })',
+        }),
+        TestLLM.text("replacement finished", "replacement_reply"),
+      )
+      yield* session.prompt({ text: "Next busy period." })
+      expect(executed).toEqual(["old", "updated source", "replacement"])
+      expect(
+        llm.requests[3].messages.some(
+          (message) =>
+            message.role === "system" &&
+            message.content.some((part) => part.type === "text" && part.text.includes("Replacement policy.")),
+        ),
+      ).toBe(true)
+    }),
+  )
+
+  it.live("concurrent opens isolate their tools, instructions, and executable snapshots", () =>
+    Effect.gen(function* () {
+      const llm = yield* TestLLM.Service
+      const resolve = yield* SessionResolve.Service
+      const sessions = yield* Session.Service
+      const gate = yield* llm.gate
+      const executed: string[] = []
+      const first = yield* sessions.open({
+        model,
+        tools: [
+          echo(
+            (text) =>
+              Effect.sync(() => {
+                executed.push("first")
+                return text
+              }),
+            "first_echo",
+          ),
+        ],
+        instructions: ["First private policy."],
+      })
+      const second = yield* sessions.open({
+        model,
+        tools: [
+          echo(
+            (text) =>
+              Effect.sync(() => {
+                executed.push("second")
+                return text
+              }),
+            "second_echo",
+          ),
+        ],
+        instructions: ["Second private policy."],
+      })
+      yield* llm.push(
+        TestLLM.tool("first_call", "execute", { code: 'return await tools.first_echo({ text: "first" })' }),
+        TestLLM.tool("second_call", "execute", { code: 'return await tools.second_echo({ text: "second" })' }),
+        TestLLM.text("first done", "first_isolation_reply"),
+        TestLLM.text("second done", "second_isolation_reply"),
+      )
+      const firstPrompt = yield* first.prompt({ text: "first" }).pipe(Effect.forkScoped)
+      yield* llm.wait(1)
+      const secondPrompt = yield* second.prompt({ text: "second" }).pipe(Effect.forkScoped)
+      yield* llm.wait(2)
+      expect(llm.requests).toHaveLength(2)
+      const firstRequest = llm.requests.find((request) => request.http?.headers?.["X-Session-Id"] === first.id)
+      const secondRequest = llm.requests.find((request) => request.http?.headers?.["X-Session-Id"] === second.id)
+      expect(JSON.stringify(firstRequest)).toContain("First private policy.")
+      expect(JSON.stringify(firstRequest)).toContain("first_echo")
+      expect(JSON.stringify(firstRequest)).not.toContain("Second private policy.")
+      expect(JSON.stringify(firstRequest)).not.toContain("second_echo")
+      expect(JSON.stringify(secondRequest)).toContain("Second private policy.")
+      expect(JSON.stringify(secondRequest)).toContain("second_echo")
+      expect(JSON.stringify(secondRequest)).not.toContain("First private policy.")
+      yield* gate.release
+      yield* Fiber.join(firstPrompt)
+      yield* Fiber.join(secondPrompt)
+      expect(executed.toSorted()).toEqual(["first", "second"])
+      for (const session of [first, second]) {
+        const capabilities = yield* resolve.resolve(yield* sessions.get(session.id))
+        if (capabilities.status !== "attached") return yield* Effect.die("Expected isolated capabilities")
+        const selected = yield* capabilities.capabilities.select(session.id)
+        expect(selected.tools.codeModeCatalog?.map((tool) => tool.path)).toEqual([
+          session === first ? "first_echo" : "second_echo",
+        ])
+      }
+    }),
+  )
+
+  it.live("retires deleted capabilities and removes their durable ownership marker", () =>
+    Effect.gen(function* () {
+      const sessions = yield* Session.Service
+      const resolve = yield* SessionResolve.Service
+      const retired: string[] = []
+      const session = yield* sessions.open({
+        model,
+        retire: () =>
+          Effect.sync(() => {
+            retired.push("retired")
+          }),
+      })
+      yield* sessions.remove(session.id)
+      expect(retired).toEqual(["retired"])
+      expect(resolve.status(session.id)).toBe("unowned")
+      expect(yield* sessions.get(session.id).pipe(Effect.flip)).toBeInstanceOf(Session.NotFoundError)
+    }),
+  )
+})

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

@@ -18,6 +18,7 @@ import { UserInterruptedError } from "@opencode-ai/core/session/error"
 import { SessionEvent } from "@opencode-ai/core/session/event"
 import { SessionInbox } from "@opencode-ai/core/session/inbox"
 import { SessionMessage } from "@opencode-ai/core/session/message"
+import { SessionResolve } from "@opencode-ai/core/session/resolve"
 import { SessionRunner } from "@opencode-ai/core/session/runner/index"
 import { SessionInboxTable, SessionTable } from "@opencode-ai/core/session/sql"
 import { SessionStore } from "@opencode-ai/core/session/store"
@@ -26,7 +27,9 @@ import { eq } from "drizzle-orm"
 import { testEffect } from "./lib/effect"
 
 const it = testEffect(
-  AppNodeBuilder.build(LayerNode.group([Database.node, Bus.node, SessionStore.node, Job.node, KV.node, Session.node])),
+  AppNodeBuilder.build(
+    LayerNode.group([Database.node, Bus.node, SessionStore.node, Job.node, KV.node, Session.node, SessionResolve.node]),
+  ),
 )
 
 describe("SessionExecution lifecycle", () => {
@@ -1135,6 +1138,7 @@ function buildExecution(
     const store = yield* SessionStore.Service
     const jobs = overrideJobs ?? (yield* Job.Service)
     const sessions = yield* Session.Service
+    const resolve = yield* SessionResolve.Service
     const sessionLayer = Layer.effect(
       Session.Service,
       Effect.gen(function* () {
@@ -1170,6 +1174,7 @@ function buildExecution(
         Layer.provide(Layer.succeed(Database.Service, database)),
         Layer.provide(Layer.succeed(Bus.Service, bus)),
         Layer.provide(Layer.succeed(SessionStore.Service, store)),
+        Layer.provide(Layer.succeed(SessionResolve.Service, resolve)),
         Layer.provide(Layer.succeed(Job.Service, jobs)),
         Layer.provide(locations),
       ),

packages/core/test/session-model-transport.test.ts

@@ -698,16 +698,22 @@ describe("SessionModelTransport", () => {
 
   test("poisons instead of dropping data when the inbound queue overflows", async () => {
     const messages = queue<string | Uint8Array, AIError>()
+    const poisoned = Deferred.makeUnsafe<void>()
     let closed = 0
     const connector: WebSocketConnector = {
       open: () =>
         Effect.succeed({
           sendText: () =>
+            // Hold consumption at the send boundary until the reader fills and poisons the inbound queue.
             Effect.sync(() => {
               for (let index = 0; index <= 129; index++) Queue.offerUnsafe(messages, `frame:${index}`)
-            }),
-          messages: Stream.fromQueue(messages),
-          close: Effect.sync(() => closed++).pipe(Effect.andThen(Queue.shutdown(messages)), Effect.asVoid),
+            }).pipe(Effect.andThen(Deferred.await(poisoned))),
+          messages: Stream.fromQueue(messages).pipe(Stream.tap(() => Effect.yieldNow)),
+          close: Effect.sync(() => closed++).pipe(
+            Effect.andThen(Deferred.succeed(poisoned, undefined)),
+            Effect.andThen(Queue.shutdown(messages)),
+            Effect.asVoid,
+          ),
         }),
     }
 
@@ -721,7 +727,7 @@ describe("SessionModelTransport", () => {
             ...item,
             driver: {
               create: item.driver.create,
-              observe: (_create, frame) => Effect.sleep("1 millis").pipe(Effect.as({ type: "frame" as const, frame })),
+              observe: (_create, frame) => Effect.succeed({ type: "frame" as const, frame }),
             },
           }),
         )

packages/core/test/source.test.ts

@@ -0,0 +1,47 @@
+import { expect } from "bun:test"
+import { Effect } from "effect"
+import { Source } from "../src/source"
+import { session } from "./fixture/capabilities"
+import { it } from "./lib/effect"
+
+it.effect("mutable sources sample current values and defer writes until execution", () =>
+  Effect.gen(function* () {
+    const source = Source.mutable(1)
+    const independent = Source.mutable(1)
+    const read = source.get(session)
+    const set = source.set(2)
+    const update = source.update((value) => value + 3)
+
+    expect(yield* read).toBe(1)
+    yield* set
+    expect(yield* read).toBe(2)
+    yield* update
+    expect(yield* read).toBe(5)
+    expect(yield* independent.get(session)).toBe(1)
+  }),
+)
+
+it.effect("constant and plain values retain their identity", () =>
+  Effect.gen(function* () {
+    const values = ["read", "write"]
+    expect(yield* Source.constant(values).get(session)).toBe(values)
+    expect(yield* Source.from(values).get(session)).toBe(values)
+    expect(yield* Source.from(null).get(session)).toBeNull()
+    expect(yield* Source.from(undefined).get(session)).toBeUndefined()
+    expect(yield* Source.from(0).get(session)).toBe(0)
+    const record = { get: "not a source" }
+    expect(yield* Source.from(record).get(session)).toBe(record)
+  }),
+)
+
+it.effect("structural sources receive the session and preserve typed failures", () =>
+  Effect.gen(function* () {
+    const source: Source.Interface<string, "unavailable"> = {
+      get: (current) => (current.title === "unavailable" ? Effect.fail("unavailable") : Effect.succeed(current.id)),
+    }
+    const converted: Source.Interface<string, "unavailable"> = Source.from(source)
+    expect(converted).toBe(source)
+    expect(yield* converted.get(session)).toBe(session.id)
+    expect(yield* converted.get({ ...session, title: "unavailable" }).pipe(Effect.flip)).toBe("unavailable")
+  }),
+)

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

@@ -1,12 +1,13 @@
 import { expect, test } from "bun:test"
 import { CodeModeTool } from "@opencode-ai/core/codemode/tool"
+import { Permission } from "@opencode-ai/core/permission"
 import { Tool } from "@opencode-ai/core/tool"
 import { execute } from "@opencode-ai/core/tool/runtime"
 import { Agent } from "@opencode-ai/schema/agent"
 import { Session } from "@opencode-ai/schema/session"
 import { SessionMessage } from "@opencode-ai/schema/session-message"
 import type { Info } from "@opencode-ai/schema/tool"
-import { Effect, Schema } from "effect"
+import { Cause, Effect, Exit, Schema } from "effect"
 
 const context = {
   sessionID: Session.ID.make("ses_execute"),
@@ -98,18 +99,60 @@ test("foreign typed failures settle as Tool.Error at the untrusted boundary", as
   class ForeignFailure extends Schema.TaggedError<ForeignFailure>()("Plugin.ForeignFailure", {
     message: Schema.String,
   }) {}
-  const lying: Info = {
-    name: "lying",
+  const tool: Info = {
+    name: "foreign",
     description: "Fails with a non-Tool.Error typed failure",
     input: Schema.Struct({}),
-    execute: () => new ForeignFailure({ message: "transport died" }) as never,
+    execute: () => new ForeignFailure({ message: "transport died" }),
   }
 
-  const exit = await Effect.runPromiseExit(execute(lying, {}, context))
-  expect(exit._tag).toBe("Failure")
-  const error = exit._tag === "Failure" ? exit.cause.reasons.find((reason) => "error" in reason)?.error : undefined
+  const error = await Effect.runPromise(execute(tool, {}, context).pipe(Effect.flip))
   expect(error).toBeInstanceOf(Tool.Error)
-  expect((error as Tool.Error).message).toBe("transport died")
+  expect(error.message).toBe("transport died")
+})
+
+test("execution preserves Tool.Error identity and tunnels only canonical permission declines", async () => {
+  const failure = new Tool.Error({ message: "failed", metadata: { reason: "test" } })
+  const tool: Info = {
+    name: "failure",
+    description: "Fails",
+    input: Schema.Struct({}),
+    execute: () => failure,
+  }
+  expect(await Effect.runPromise(execute(tool, {}, context).pipe(Effect.flip))).toBe(failure)
+
+  const decline = new Permission.DeclinedError({})
+  const exit = await Effect.runPromiseExit(execute({ ...tool, execute: () => decline }, {}, context))
+  expect(
+    Exit.isFailure(exit) && exit.cause.reasons.some((reason) => reason._tag === "Die" && reason.defect === decline),
+  ).toBe(true)
+
+  class ForeignDecline extends Schema.TaggedError<ForeignDecline>()("Permission.DeclinedError", {
+    message: Schema.String,
+  }) {}
+  const normalized = await Effect.runPromise(
+    execute({ ...tool, execute: () => new ForeignDecline({ message: "not a host decline" }) }, {}, context).pipe(
+      Effect.flip,
+    ),
+  )
+  expect(normalized).toBeInstanceOf(Tool.Error)
+  expect(normalized.message).toBe("not a host decline")
+})
+
+test("execution leaves defects and interruption untouched", async () => {
+  const defect = new Error("unexpected")
+  const tool: Info = {
+    name: "defect",
+    description: "Dies",
+    input: Schema.Struct({}),
+    execute: () => Effect.die(defect),
+  }
+  const died = await Effect.runPromiseExit(execute(tool, {}, context))
+  expect(
+    Exit.isFailure(died) && died.cause.reasons.some((reason) => reason._tag === "Die" && reason.defect === defect),
+  ).toBe(true)
+  const interrupted = await Effect.runPromiseExit(execute({ ...tool, execute: () => Effect.interrupt }, {}, context))
+  expect(Exit.isFailure(interrupted) && Cause.hasInterruptsOnly(interrupted.cause)).toBe(true)
 })
 
 test("execute supports callable namespace tools", async () => {

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

@@ -0,0 +1,147 @@
+import { expect } from "bun:test"
+import { Agent } from "@opencode-ai/schema/agent"
+import { LayerNode } from "@opencode-ai/util/effect/layer-node"
+import { Effect, Schema } from "effect"
+import { Image } from "../src/image"
+import { PluginHooks } from "../src/plugin/hooks"
+import { SessionSchema } from "../src/session/schema"
+import { SessionMessage } from "../src/session/message"
+import { Tool } from "../src/tool"
+import { echo } from "./fixture/capabilities"
+import { testEffect } from "./lib/effect"
+
+const it = testEffect(LayerNode.compile(LayerNode.group([PluginHooks.node, Image.node])))
+const identity = {
+  sessionID: SessionSchema.ID.make("ses_tool_values"),
+  agent: Agent.ID.make("build"),
+  messageID: SessionMessage.ID.make("msg_tool_values"),
+}
+const call = (name: string, input: unknown): Parameters<Tool.Snapshot["execute"]>[0] => ({
+  ...identity,
+  call: { type: "tool-call", id: `call_${name}`, name, input },
+})
+
+it.effect("value snapshots preserve definitions and executors after sampling and replacement", () =>
+  Effect.gen(function* () {
+    const tool = { ...echo(Effect.succeed), options: { namespace: "demo", codemode: false } }
+    const values: Tool.Info[] = [tool]
+    const first = yield* Tool.snapshot(values)
+    tool.execute = () => Effect.succeed({ output: "changed executor" })
+    tool.description = "Changed description"
+    values[0] = {
+      ...tool,
+      input: Schema.Struct({ count: Schema.Finite }),
+      output: Schema.Finite,
+      execute: ({ count }) => Effect.succeed({ output: count + 1 }),
+    }
+    const second = yield* Tool.snapshot(values)
+    values.length = 0
+    expect((yield* Tool.snapshot(values)).definitions.map((tool) => tool.name)).toEqual(["execute"])
+
+    expect(first.definitions[0]?.description).toBe("Echo text with echo")
+    expect(first.definitions[0]?.inputSchema.properties).toEqual({ text: { type: "string" } })
+    expect(second.definitions[0]?.description).toBe("Changed description")
+    expect(second.definitions[0]?.inputSchema.properties).toEqual({ count: { type: "number" } })
+    expect(yield* first.execute(call("demo_echo", { text: "original" }))).toEqual({
+      output: "original",
+      content: [{ type: "text", text: "original" }],
+    })
+    expect((yield* second.execute(call("demo_echo", { count: 2 }))).output).toBe(3)
+    expect(yield* first.execute(call("demo_echo", { count: 2 })).pipe(Effect.flip)).toBeInstanceOf(Tool.Error)
+    expect(yield* second.execute(call("demo_echo", { text: "original" })).pipe(Effect.flip)).toBeInstanceOf(Tool.Error)
+  }),
+)
+
+it.effect("value snapshots reuse name normalization, validation, and last-valid precedence", () =>
+  Effect.gen(function* () {
+    const tool = { ...echo(Effect.succeed, "echo.text"), options: { namespace: "demo.tools", codemode: false } }
+    const snapshot = yield* Tool.snapshot([
+      tool,
+      { ...tool, name: "echo_text", execute: () => Effect.succeed({ output: "latest" }) },
+      { ...tool, options: { namespace: "invalid namespace", codemode: false } },
+      { ...echo(Effect.succeed, "execute"), options: { codemode: false } },
+    ])
+    expect(snapshot.definitions.map((tool) => tool.name)).toEqual(["demo_tools_echo_text", "execute"])
+    expect((yield* snapshot.execute(call("demo_tools_echo_text", { text: "input" }))).output).toBe("latest")
+
+    const invalidOutput = yield* Tool.snapshot([
+      { ...echo(Effect.succeed), options: { codemode: false }, execute: () => Effect.succeed({ output: 1 }) },
+    ])
+    expect((yield* invalidOutput.execute(call("echo", { text: "input" })).pipe(Effect.flip)).message).toContain(
+      "Tool returned an invalid value for its output schema",
+    )
+  }),
+)
+
+it.live("value snapshots default tools into CodeMode and retain executable catalog entries", () =>
+  Effect.gen(function* () {
+    const snapshot = yield* Tool.snapshot([{ ...echo(Effect.succeed), options: { namespace: "demo.tools" } }])
+    expect(snapshot.definitions.map((tool) => tool.name)).toEqual(["execute"])
+    expect(snapshot.codeModeCatalog?.map((tool) => tool.path)).toEqual(["demo.tools.echo"])
+    expect(yield* snapshot.execute(call("demo_tools_echo", { text: "input" })).pipe(Effect.flip)).toEqual(
+      new Tool.Error({ message: "Unknown tool: demo_tools_echo" }),
+    )
+    expect(
+      yield* snapshot.execute(call("execute", { code: 'return await tools.demo.tools.echo({ text: "input" })' })),
+    ).toMatchObject({
+      content: [{ type: "text", text: "input" }],
+      metadata: { toolCalls: [{ tool: "demo.tools.echo", status: "completed", input: { text: "input" } }] },
+    })
+  }),
+)
+
+it.effect("value snapshot permissions filter visibility without authorizing execution", () =>
+  Effect.gen(function* () {
+    const tools = [{ ...echo(Effect.succeed), options: { permission: "read", codemode: false } }]
+    const visible = yield* Tool.snapshot(tools, [{ action: "read", resource: "private/*", effect: "deny" }])
+    expect((yield* visible.execute(call("echo", { text: "private/file.ts" }))).output).toBe("private/file.ts")
+    const hidden = yield* Tool.snapshot(tools, [{ action: "read", resource: "*", effect: "deny" }])
+    expect(hidden.definitions.map((tool) => tool.name)).toEqual(["execute"])
+    expect(yield* hidden.execute(call("echo", { text: "input" })).pipe(Effect.flip)).toBeInstanceOf(Tool.Error)
+    const directOnly = yield* Tool.snapshot(tools, [{ action: "execute", resource: "*", effect: "deny" }])
+    expect(directOnly.definitions.map((tool) => tool.name)).toEqual(["echo"])
+    expect(directOnly.codeModeCatalog).toBeUndefined()
+  }),
+)
+
+it.live("value snapshots use externally scoped hooks and image normalization", () =>
+  Effect.gen(function* () {
+    const hooks = yield* PluginHooks.Service
+    const image = yield* Image.Service
+    const seen: string[] = []
+    yield* image.transform((draft) => draft.configure({ autoResize: false, maxBase64Bytes: 0 }))
+    yield* hooks.register("tool", "execute.before", (event) =>
+      Effect.sync(() => {
+        seen.push(`before:${event.tool}`)
+        event.input = { text: "reviewed" }
+      }),
+    )
+    yield* hooks.register("tool", "execute.after", (event) =>
+      Effect.sync(() => {
+        seen.push(`after:${event.tool}`)
+        if (event.status !== "completed") return
+        event.result = {
+          ...event.result,
+          content: [
+            { type: "text", text: "reviewed content" },
+            {
+              type: "file",
+              mime: "image/png",
+              uri: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=",
+            },
+          ],
+        }
+      }),
+    )
+    const snapshot = yield* Tool.snapshot([{ ...echo(Effect.succeed), options: { codemode: false } }])
+    expect(yield* hooks.has("tool", "execute.before")).toBe(true)
+    expect(yield* snapshot.execute(call("echo", { text: "input" }))).toEqual({
+      output: "reviewed",
+      content: [
+        { type: "text", text: "reviewed content" },
+        { type: "text", text: "[1 image omitted: could not be resized below the image size limit.]" },
+      ],
+    })
+    expect(seen).toEqual(["before:echo", "after:echo"])
+  }),
+)

packages/schema/src/tool.ts

@@ -91,7 +91,9 @@ export type Info<
   readonly name: string
   readonly input: Input
   readonly description: string
-  readonly execute: (input: InputValue<Input>, context: Context) => Effect.Effect<Result<Output>, Error>
+  // Heterogeneous implementations may fail with domain errors. Core normalizes foreign
+  // failures to Tool.Error; Permission.DeclinedError identity enters the decline tunnel.
+  readonly execute: (input: InputValue<Input>, context: Context) => Effect.Effect<Result<Output>, unknown>
   readonly output?: Output
   readonly options?: Options
 }