fix(core): preserve model capability semantics

packages/core/src/models-dev.ts

@@ -65,7 +65,7 @@ export const Model = Schema.Struct({
   name: Schema.String,
   family: Schema.optional(Schema.String),
   release_date: Schema.String,
-  attachment: Schema.Boolean,
+  attachment: Schema.optional(Schema.Boolean),
   reasoning: Schema.Boolean,
   reasoning_options: Schema.optional(Schema.Array(ReasoningOption)),
   temperature: Schema.optional(Schema.Boolean),

packages/core/src/plugin/models-dev.ts

@@ -185,11 +185,12 @@ function applyModel(
   draft.family = model.family ? ModelV2.Family.make(model.family) : undefined
   draft.package = model.provider?.npm ? ProviderV2.aisdk(model.provider.npm) : undefined
   draft.settings = model.provider?.api ? { ...draft.settings, baseURL: model.provider.api } : draft.settings
-  draft.capabilities = {
+  const capabilities = ModelV2.Capabilities.defaults({
     tools: model.tool_call,
-    input: [...(model.modalities?.input ?? [])],
+    input: model.modalities?.input ?? (model.attachment === false ? ["text"] : undefined),
-    output: [...(model.modalities?.output ?? [])],
+    output: model.modalities?.output,
-  }
+  })
+  draft.capabilities = { ...capabilities, input: [...capabilities.input], output: [...capabilities.output] }
   mergeVariants(draft, input.variants ?? [])
   draft.time.released = released(model.release_date)
   draft.cost = (input.cost ?? cost(model.cost)).map((item) => ({

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

@@ -237,9 +237,10 @@ const layer = Layer.effect(
       const entries = yield* SessionHistory.entriesForRunner(db, session.id, checkpoint.baselineSeq)
       const context = entries.map((entry) => entry.message)
       const isLastStep = agent.info?.steps !== undefined && currentStep >= agent.info.steps
-      const toolMaterialization = isLastStep
+      const toolMaterialization =
-        ? undefined
+        isLastStep || !resolved.capabilities.tools
-        : yield* tools.materialize({ permissions: agent.info?.permissions, model })
+          ? undefined
+          : yield* tools.materialize({ permissions: agent.info?.permissions, model })
       const promptCacheKey = /^ses_[0-9a-f]{64}$/.test(session.id) ? session.id.slice(4) : session.id
       const request = LLM.request({
         model,
@@ -251,7 +252,7 @@ const layer = Layer.effect(
           .filter((part): part is string => part !== undefined && part.length > 0)
           .map(SystemPart.make),
         messages: [
-          ...toLLMMessages(context, resolved.ref, providerMetadataKey),
+          ...toLLMMessages(context, resolved.ref, providerMetadataKey, resolved.capabilities),
           ...(isLastStep ? [Message.assistant(MAX_STEPS_PROMPT)] : []),
         ],
         tools: toolMaterialization?.definitions ?? [],

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

@@ -82,6 +82,8 @@ export interface Resolved {
   readonly model: Model
   /** Selected catalog identity. Durable records and displays must use this, never the API model id. */
   readonly ref: ModelV2.Ref
+  /** Capabilities of the selected catalog model. */
+  readonly capabilities: ModelV2.Capabilities
   /** Catalog pricing in dollars per million tokens. */
   readonly cost: ModelV2.Info["cost"]
 }
@@ -96,13 +98,19 @@ export class Service extends Context.Service<Service, Interface>()("@opencode/v2
 export const layerWith = (resolve: Interface["resolve"]) => Layer.succeed(Service, Service.of({ resolve }))
 
 /** Builds a Resolved whose catalog identity mirrors the route model. Test or embedding seam. */
-export const resolved = (model: Model, variant?: ModelV2.VariantID, cost: ModelV2.Info["cost"] = []): Resolved => ({
+export const resolved = (
+  model: Model,
+  variant?: ModelV2.VariantID,
+  cost: ModelV2.Info["cost"] = [],
+  capabilities = ModelV2.Capabilities.defaults(),
+): Resolved => ({
   model,
   ref: ModelV2.Ref.make({
     id: ModelV2.ID.make(model.id),
     providerID: ProviderV2.ID.make(model.provider),
     ...(variant === undefined ? {} : { variant }),
   }),
+  capabilities,
   cost,
 })
 
@@ -344,6 +352,7 @@ const layer = Layer.effect(
             providerID: selected.providerID,
             ...(session.model?.variant === undefined ? {} : { variant: session.model.variant }),
           }),
+          capabilities: selected.capabilities,
           cost: selected.cost,
         }
       }),

packages/core/src/session/runner/to-llm-message.ts

@@ -11,8 +11,6 @@ import type { ModelV2 } from "../../model"
 import { SessionMessage } from "../message"
 import type { FileAttachment } from "@opencode-ai/schema/prompt"
 
-const imageMimes = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"])
-
 const media = (file: FileAttachment): ContentPart => ({
   type: "media",
   mediaType: file.mime,
@@ -21,6 +19,23 @@ const media = (file: FileAttachment): ContentPart => ({
   metadata: file.description === undefined ? undefined : { description: file.description },
 })
 
+const modality = (mime: string) => {
+  if (mime.startsWith("image/")) return "image"
+  if (mime.startsWith("audio/")) return "audio"
+  if (mime.startsWith("video/")) return "video"
+  if (mime === "application/pdf") return "pdf"
+  return undefined
+}
+
+const attachment = (file: FileAttachment, capabilities?: ModelV2.Capabilities): ContentPart => {
+  const type = modality(file.mime)
+  if (!type || (capabilities?.input ?? ["text", "image"]).includes(type)) return media(file)
+  return {
+    type: "text",
+    text: `ERROR: Cannot read ${file.name ? `"${file.name}"` : type} (this model does not support ${type} input). Inform the user.`,
+  }
+}
+
 const textAttachment = (file: FileAttachment) =>
   Message.make({
     role: "user",
@@ -168,7 +183,12 @@ const assistant = (message: SessionMessage.Assistant, model: ModelV2.Ref, provid
   ]
 }
 
-function toLLMMessage(message: SessionMessage.Info, model: ModelV2.Ref, providerMetadataKey: string): Message[] {
+function toLLMMessage(
+  message: SessionMessage.Info,
+  model: ModelV2.Ref,
+  providerMetadataKey: string,
+  capabilities?: ModelV2.Capabilities,
+): Message[] {
   switch (message.type) {
     case "agent-switched":
     case "model-switched":
@@ -183,7 +203,9 @@ function toLLMMessage(message: SessionMessage.Info, model: ModelV2.Ref, provider
           role: "user",
           content: [
             { type: "text", text: message.text },
-            ...files.filter((file) => imageMimes.has(file.mime)).map(media),
+            ...files
+              .filter((file) => file.mime !== "text/plain" && file.mime !== "application/x-directory")
+              .map((file) => attachment(file, capabilities)),
           ],
           metadata: {
             ...message.metadata,
@@ -236,4 +258,5 @@ export const toLLMMessages = (
   messages: readonly SessionMessage.Info[],
   model: ModelV2.Ref,
   providerMetadataKey: string = model.providerID,
-) => messages.flatMap((message) => toLLMMessage(message, model, providerMetadataKey))
+  capabilities?: ModelV2.Capabilities,
+) => messages.flatMap((message) => toLLMMessage(message, model, providerMetadataKey, capabilities))

packages/core/src/v1/config/migrate.ts

@@ -7,6 +7,7 @@ import { ConfigMCPV1 } from "./mcp"
 import { ConfigPermissionV1 } from "./permission"
 import { ConfigProviderV1 } from "./provider"
 import { ConfigProviderOptionsV1 } from "./provider-options"
+import { ModelV2 } from "../../model"
 import { ProviderV2 } from "../../provider"
 
 const keys = new Set([
@@ -245,8 +246,15 @@ function migrateModel(info: typeof ConfigProviderV1.Model.Type) {
       : []),
   ]
   const capabilities =
-    info.tool_call !== undefined || info.modalities?.input !== undefined || info.modalities?.output !== undefined
+    info.tool_call !== undefined ||
-      ? { tools: info.tool_call ?? false, input: info.modalities?.input ?? [], output: info.modalities?.output ?? [] }
+    info.attachment !== undefined ||
+    info.modalities?.input !== undefined ||
+    info.modalities?.output !== undefined
+      ? ModelV2.Capabilities.defaults({
+          tools: info.tool_call,
+          input: info.modalities?.input ?? (info.attachment === false ? ["text"] : undefined),
+          output: info.modalities?.output,
+        })
       : undefined
   return {
     modelID: info.id,

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

@@ -680,9 +680,17 @@ describe("Config", () => {
                     options: { apiKey: "secret" },
                     models: {
                       model: {
+                        attachment: true,
                         options: { reasoningEffort: "high" },
                         variants: { fast: { temperature: 0.2 } },
                       },
+                      text: {
+                        attachment: false,
+                      },
+                      audio: {
+                        attachment: true,
+                        modalities: { input: ["audio"], output: ["audio"] },
+                      },
                     },
                   },
                   openai: {
@@ -758,9 +766,16 @@ describe("Config", () => {
               settings: { apiKey: "secret" },
               models: {
                 model: {
+                  capabilities: { tools: true, input: ["text", "image"], output: ["text"] },
                   settings: { reasoningEffort: "high" },
                   variants: [{ id: "fast", settings: { temperature: 0.2 } }],
                 },
+                text: {
+                  capabilities: { tools: true, input: ["text"], output: ["text"] },
+                },
+                audio: {
+                  capabilities: { tools: true, input: ["audio"], output: ["audio"] },
+                },
               },
             })
             expect(documents[0]?.info.providers?.openai).toMatchObject({

packages/core/test/config/provider.test.ts

@@ -237,6 +237,7 @@ describe("ConfigProviderPlugin.Plugin", () => {
 
         const provider = required(yield* catalog.provider.get(providerID))
         const model = required(yield* catalog.model.get(providerID, modelID))
+        const defaultModel = required(yield* catalog.model.get(providerID, ModelV2.ID.make("default")))
         expect((yield* catalog.model.default())?.id).toBe(ModelV2.ID.make("default"))
         expect(provider.name).toBe("Renamed")
         expect((yield* integrations.get(Integration.ID.make("custom")))?.methods).toContainEqual({
@@ -252,6 +253,7 @@ describe("ConfigProviderPlugin.Plugin", () => {
         expect(model.modelID).toBe(ModelV2.ID.make("api-chat"))
         expect(model.name).toBe("Last")
         expect(model.capabilities).toEqual({ tools: true, input: ["text"], output: ["text"] })
+        expect(defaultModel.capabilities).toEqual({ tools: true, input: ["text", "image"], output: ["text"] })
         expect(model.enabled).toBe(false)
         expect(model.limit).toEqual({ context: 100, output: 75 })
         expect(model.cost).toEqual([

packages/core/test/models.test.ts

@@ -165,6 +165,21 @@ describe("ModelsDev Service", () => {
     }),
   )
 
+  it.effect("allows models.dev entries without legacy attachment metadata", () =>
+    Effect.sync(() => {
+      const result = Schema.decodeUnknownSync(ModelsDev.Model)({
+        id: "no-attachment-model",
+        name: "No Attachment Model",
+        release_date: "2026-01-01",
+        reasoning: false,
+        tool_call: true,
+        limit: { context: 128000, output: 8192 },
+      })
+
+      expect(result.attachment).toBeUndefined()
+    }),
+  )
+
   it.live("get() returns providers from disk when cache file exists", () =>
     Effect.gen(function* () {
       yield* writeCache(fixture)

packages/core/test/plugin/models-dev.test.ts

@@ -85,6 +85,24 @@ describe("ModelsDevPlugin", () => {
                     },
                   },
                 },
+                default: {
+                  id: "default",
+                  name: "Default",
+                  release_date: "2026-01-01",
+                  reasoning: false,
+                  tool_call: false,
+                  limit: { context: 128_000, output: 8_192 },
+                },
+                explicit: {
+                  id: "explicit",
+                  name: "Explicit",
+                  release_date: "2026-01-01",
+                  attachment: true,
+                  reasoning: false,
+                  tool_call: false,
+                  modalities: { input: ["audio"], output: ["audio"] },
+                  limit: { context: 128_000, output: 8_192 },
+                },
               },
             },
           } satisfies Record<string, ModelsDev.Provider>),
@@ -101,9 +119,14 @@ describe("ModelsDevPlugin", () => {
       const providerID = ProviderV2.ID.make("acme")
       const base = yield* catalog.model.get(providerID, ModelV2.ID.make("gpt-5.4"))
       const fast = yield* catalog.model.get(providerID, ModelV2.ID.make("gpt-5.4-fast"))
+      const defaults = yield* catalog.model.get(providerID, ModelV2.ID.make("default"))
+      const explicit = yield* catalog.model.get(providerID, ModelV2.ID.make("explicit"))
 
       expect(base?.variants).toEqual([])
       expect(base?.body).toEqual({})
+      expect(base?.capabilities).toEqual({ tools: true, input: ["text"], output: ["text"] })
+      expect(defaults?.capabilities).toEqual({ tools: false, input: ["text", "image"], output: ["text"] })
+      expect(explicit?.capabilities).toEqual({ tools: false, input: ["audio"], output: ["audio"] })
       expect(fast).toMatchObject({
         id: "gpt-5.4-fast",
         modelID: "gpt-5.4",
@@ -181,6 +204,9 @@ describe("ModelsDevPlugin", () => {
               connections: [],
             }),
           ])
+          expect(yield* catalog.model.get(ProviderV2.ID.opencode, ModelV2.ID.make("gpt-5.5"))).toMatchObject({
+            capabilities: { tools: true, input: ["text", "image"], output: ["text"] },
+          })
         }).pipe(Effect.provide(AppNodeBuilder.build(ModelsDev.node))),
       (previous) =>
         Effect.sync(() => {

packages/core/test/session-runner-message.test.ts

@@ -240,7 +240,7 @@ Recent work
     expect(messages[1]?.content).toEqual([{ type: "text", text: "Review this directory" }])
   })
 
-  test("uses materialized image data as provider media and drops unsupported attachments", () => {
+  test("defaults missing model capabilities to text and image input", () => {
     const data = Base64.make("AAECAw==")
     const messages = toLLMMessages(
       [
@@ -266,6 +266,113 @@ Recent work
     expect(messages[0]?.content).toEqual([
       { type: "text", text: "Inspect this image" },
       { type: "media", mediaType: "image/png", data, filename: "image.png" },
+      {
+        type: "text",
+        text: 'ERROR: Cannot read "document.pdf" (this model does not support pdf input). Inform the user.',
+      },
+    ])
+  })
+
+  test("uses explicit model input capabilities instead of attachment defaults", () => {
+    const data = Base64.make("AAECAw==")
+    const messages = toLLMMessages(
+      [
+        SessionMessage.User.make({
+          id: id("user-unsupported-pdf"),
+          type: "user",
+          text: "Inspect these files",
+          files: [
+            FileAttachment.make({ data, mime: "image/png", source: { type: "inline" }, name: "image.png" }),
+            FileAttachment.make({
+              data: Base64.make("JVBERg=="),
+              mime: "application/pdf",
+              source: { type: "inline" },
+              name: "document.pdf",
+            }),
+          ],
+          time: { created },
+        }),
+      ],
+      model,
+      model.providerID,
+      { tools: true, input: ["text", "pdf"], output: ["text"] },
+    )
+
+    expect(messages[0]?.content).toEqual([
+      { type: "text", text: "Inspect these files" },
+      {
+        type: "text",
+        text: 'ERROR: Cannot read "image.png" (this model does not support image input). Inform the user.',
+      },
+      { type: "media", mediaType: "application/pdf", data: "JVBERg==", filename: "document.pdf" },
+    ])
+  })
+
+  test("treats explicit empty input capabilities as authoritative", () => {
+    const messages = toLLMMessages(
+      [
+        SessionMessage.User.make({
+          id: id("user-empty-capabilities"),
+          type: "user",
+          text: "Inspect this image",
+          files: [
+            FileAttachment.make({
+              data: Base64.make("AAECAw=="),
+              mime: "image/png",
+              source: { type: "inline" },
+              name: "image.png",
+            }),
+          ],
+          time: { created },
+        }),
+      ],
+      model,
+      model.providerID,
+      { tools: false, input: [], output: [] },
+    )
+
+    expect(messages[0]?.content).toEqual([
+      { type: "text", text: "Inspect this image" },
+      {
+        type: "text",
+        text: 'ERROR: Cannot read "image.png" (this model does not support image input). Inform the user.',
+      },
+    ])
+  })
+
+  test("classifies audio and video MIME families through explicit capabilities", () => {
+    const messages = toLLMMessages(
+      [
+        SessionMessage.User.make({
+          id: id("user-media-capabilities"),
+          type: "user",
+          text: "Inspect this media",
+          files: [
+            FileAttachment.make({
+              data: Base64.make("AAECAw=="),
+              mime: "audio/mpeg",
+              source: { type: "inline" },
+              name: "audio.mp3",
+            }),
+            FileAttachment.make({
+              data: Base64.make("AAECAw=="),
+              mime: "video/webm",
+              source: { type: "inline" },
+              name: "video.webm",
+            }),
+          ],
+          time: { created },
+        }),
+      ],
+      model,
+      model.providerID,
+      { tools: false, input: ["text", "audio", "video"], output: ["text"] },
+    )
+
+    expect(messages[0]?.content).toEqual([
+      { type: "text", text: "Inspect this media" },
+      { type: "media", mediaType: "audio/mpeg", data: "AAECAw==", filename: "audio.mp3" },
+      { type: "media", mediaType: "video/webm", data: "AAECAw==", filename: "video.webm" },
     ])
   })
 

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

@@ -235,12 +235,15 @@ const echo = Layer.effectDiscard(
 const echoNode = makeLocationNode({ name: "test/session-runner-tools", layer: echo, deps: [ToolRegistry.node] })
 let modelResolveHook = Effect.void
 let currentModel = model
+let modelCapabilities = ModelV2.Capabilities.defaults()
 const models = SessionRunnerModel.layerWith((session) =>
   modelResolveHook.pipe(
     Effect.as(
       SessionRunnerModel.resolved(
         session.model?.id === "replacement" ? replacementModel : currentModel,
         session.model?.variant,
+        [],
+        modelCapabilities,
       ),
     ),
   ),
@@ -412,6 +415,7 @@ const setup = Effect.gen(function* () {
   systemLoadHook = Effect.void
   modelResolveHook = Effect.void
   currentModel = model
+  modelCapabilities = ModelV2.Capabilities.defaults()
   skillBaselines.clear()
   responses = undefined
   streamFailure = undefined
@@ -787,6 +791,22 @@ describe("SessionRunnerLLM", () => {
     }),
   )
 
+  it.effect("does not advertise tools to a model without tool capability", () =>
+    Effect.gen(function* () {
+      yield* setup
+      modelCapabilities = ModelV2.Capabilities.defaults({ tools: false })
+      const session = yield* SessionV2.Service
+      yield* session.prompt({ sessionID, prompt: PromptInput.Prompt.make({ text: "No tools" }), resume: false })
+
+      requests.length = 0
+      response = []
+      yield* session.resume(sessionID)
+
+      expect(requests).toHaveLength(1)
+      expect(requests[0]?.tools).toEqual([])
+    }),
+  )
+
   it.effect("retries the first provider turn after system context becomes available", () =>
     Effect.gen(function* () {
       const session = yield* setup

packages/schema/src/model.ts

@@ -26,7 +26,24 @@ export const Capabilities = Schema.Struct({
   tools: Schema.Boolean,
   input: Schema.Array(Schema.String),
   output: Schema.Array(Schema.String),
-}).annotate({ identifier: "Model.Capabilities" })
+})
+  .annotate({ identifier: "Model.Capabilities" })
+  .pipe(
+    statics((schema) => ({
+      defaults: (
+        input: {
+          readonly tools?: boolean
+          readonly input?: ReadonlyArray<string>
+          readonly output?: ReadonlyArray<string>
+        } = {},
+      ) =>
+        schema.make({
+          tools: input.tools ?? true,
+          input: input.input === undefined ? ["text", "image"] : [...input.input],
+          output: input.output === undefined ? ["text"] : [...input.output],
+        }),
+    })),
+  )
 
 export interface Cost extends Schema.Schema.Type<typeof Cost> {}
 export const Cost = Schema.Struct({
@@ -80,7 +97,7 @@ export const Info = Schema.Struct({
           modelID: id,
           providerID,
           name: id,
-          capabilities: { tools: false, input: [], output: [] },
+          capabilities: Capabilities.defaults(),
           variants: [],
           time: { released: 0 },
           cost: [],