dsh-vision-router 2.1.1 → 2.1.2

package/docs/releases/v2.1.2.md

@@ -0,0 +1,30 @@
+# v2.1.2
+
+DVR 2.1.2 is a reliability hotfix for image-session ownership, delegated vision routing, text-only attachment projection, and composer Vision-mode authority. It also closes CI blind spots that could allow valid regression tests to exist without being executed by the normal release gate.
+
+## Fixed
+
+- Keeps uploaded image blocks as durable Session facts. Vision Router no longer rewrites the current user image into internal `[attached image: sha256:…]` marker text through the legacy pre-step path. Model-specific projection now stays at adapter/request boundaries instead of leaking into the conversation transcript.
+- Fixes #374 and the wider delegated call-config class: when Vision Router actually hands a request to another provider/model, source-route `maxTokens`, `reasoningEffort`, sampling and stop settings no longer override the target adapter's own defaults. This fixes GLM routes such as `glm-4v-flash` rejecting a Router-supplied 4096-token limit when the configured model cap is 1024.
+- Refines that handoff rule so transparent Vision Router twins keep caller-owned generation settings, while tool, Vision Chain and `agent/request` provider/model handoffs restore target-route authority. Reasoning memory is scoped to the relevant session and route instead of becoming cross-route state.
+- Keeps the `vision_describe` cache as a successful-answer cache. Structured Vision Router failures (`ok: false` with `VISION_*` errors) are no longer retained across turns, so repaired credentials or recovered backends can be retried immediately.
+- Recovers safely when a source adapter is incorrectly catalogued as image-capable. Generated Vision Router twins now recognize explicit runtime image-capability rejection before model-visible output, record bounded negative proof for the exact source route, and re-enter the canonical text-only fallback path instead of repeatedly sending raw pixels to a text-only backend. Generic 4xx/5xx, auth, rate-limit, media-format, cancellation and post-output failures do not trigger this fallback.
+- Resolves DSH text-only projected image handles such as `sha256:deadbeef` back to a canonical attachment only inside the current Session. Unique prefixes resolve, unknown or ambiguous prefixes fail closed, bounded cache eviction cannot erase ambiguity because durable Session history remains authoritative, and attachment-shaped input can no longer fall through into a guessed local filesystem path.
+- Makes the composer `👁 Vision` state the authoritative per-Session permission for Vision Router orchestration. Ordinary text-only and native-multimodal routes no longer receive Router-owned `vision_*` schemas, structured bootstrap, automatic deep-tool mounting or instant visual work while Vision is OFF. Native multimodal pixels remain Host-owned and continue to work normally without Router intervention.
+- Keeps the current Agent step internally stable if the model picker changes while it is running. The new selection is applied at the next real prompt-assembly boundary, while diagnostic/out-of-band prompt renders cannot clear or mutate the active step authority.
+- Keeps Settings `tool=false` as an independent global capability gate. Selecting a Vision Router wrapper cannot re-enable tools that the user explicitly disabled.
+
+## Regression and CI hardening
+
+- Adds production-shaped coverage for delegated target defaults, transparent wrapper behavior, `agent/request` route handoffs and ordinary non-delegated LLM calls.
+- Adds transcript ownership coverage ensuring accepted user images remain raw Session content and the retired pre-step bridge cannot synthesize attachment markers into durable history.
+- Adds false-multimodal metadata regressions across generated twins, custom wrappers, lazy source registration, route changes and negative-proof isolation.
+- Adds attachment-handle regressions for exact IDs, DSH short projected handles, cache eviction, same-Session prefix collisions, cross-Session isolation, malformed handles and attachment-vs-filesystem dispatch.
+- Adds Session Vision-mode regressions for OFF/ON isolation, native multimodal non-intervention, prompt-assembly visibility, PTC/scoped-tool behavior, mid-step picker changes, diagnostic assemblies, foreign `vision_*` tools and Settings `tool=false`.
+- Makes the default test manifest closed-world: every `tests/**/*.test.js` file must either run in the normal suite or have a documented PR-triggered specialist workflow owner.
+- Verifies specialist workflow ownership against the workflow source so exclusions cannot silently become stale or merely appear in a path trigger without being executed.
+- The final release head passes Node 22/24, DSH rc.6/rc.7/rc.8 contracts, P1/P2/P3 architecture gates, native multimodal cold/process restart coverage, Ubuntu/macOS/Windows host-sharp checks, and CodeQL with no new alerts.
+
+## Upgrade
+
+Upgrade to 2.1.2 and restart the DSH Web/Desktop process so the new runtime boundaries are loaded. No settings migration is required.

package/lib/agent-request-route-authority.js

@@ -0,0 +1,94 @@
+import { projectDelegatedCallConfig } from './delegated-call-config.js'
+import { contextWithTwinImageCapabilityFallback } from './twin-image-capability-fallback.js'
+
+const routeAuthorityOptionsByContext = new WeakMap()
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function routeOf(value) {
+  if (!isObject(value)) return undefined
+  const provider = typeof value.provider === 'string' && value.provider !== '' ? value.provider : undefined
+  const model = typeof value.model === 'string' && value.model !== '' ? value.model : undefined
+  return provider !== undefined && model !== undefined ? { provider, model } : undefined
+}
+
+/**
+ * A completed `agent/request` route change is an authority handoff: generation
+ * defaults from the source provider/model must not be mistaken for explicit
+ * target-model config. Payload/lifecycle fields remain untouched.
+ *
+ * Fail closed on incomplete route evidence. If either side lacks an exact
+ * provider+model tuple, preserve the handler result rather than guessing.
+ */
+export function projectAgentRequestRouteHandoff(sourceConfig, resultConfig) {
+  const source = routeOf(sourceConfig)
+  const target = routeOf(resultConfig)
+  if (source === undefined || target === undefined) return resultConfig
+  if (source.provider === target.provider && source.model === target.model) return resultConfig
+  return projectDelegatedCallConfig(resultConfig)
+}
+
+/**
+ * Runtime composition can publish route identities before Core.apply without
+ * changing the mature `contextWithAgentRequestRouteAuthority(backendRuntimeCtx)`
+ * boundary shape. The WeakMap keeps this per-context and garbage-collectable.
+ */
+export function configureAgentRequestRouteAuthority(ctx, options = {}) {
+  if (!isObject(ctx)) return ctx
+  routeAuthorityOptionsByContext.set(ctx, {
+    wrapperRoute: options.wrapperRoute,
+    chainRoute: options.chainRoute,
+    logger: options.logger,
+  })
+  return ctx
+}
+
+/**
+ * Private Core-facing context. It wraps only `agent/request` handlers and only
+ * projects a result when that handler demonstrably changed provider/model.
+ * Ordinary request handlers and direct LLM calls retain caller identity.
+ *
+ * This is also the final Core-facing adapter-registration boundary, so it owns
+ * the generated-twin runtime capability correction: if a `<provider>-vision`
+ * twin trusted image metadata but the live source explicitly rejects raw image
+ * input before producing output, the twin is re-entered once through Core's
+ * existing text bridge instead of leaking that 400 to the user. Keeping the
+ * fallback here means the deeper prepareCall/ownership layers still observe the
+ * final wrapped stream and retain their existing contracts.
+ */
+export function contextWithAgentRequestRouteAuthority(ctx, options) {
+  if (!isObject(ctx)) return ctx
+  const fallbackOptions = isObject(options)
+    ? options
+    : routeAuthorityOptionsByContext.get(ctx) ?? {}
+  const routeAuthorityCtx = new Proxy(ctx, {
+    get(target, property) {
+      if (property !== 'on') {
+        const value = Reflect.get(target, property, target)
+        return typeof value === 'function' ? value.bind(target) : value
+      }
+      const on = Reflect.get(target, property, target)
+      if (typeof on !== 'function') return on
+      return (event, handler, ...rest) => {
+        if (event !== 'agent/request' || typeof handler !== 'function') {
+          return on.call(target, event, handler, ...rest)
+        }
+        return on.call(target, event, async function routeAuthorityAwareRequest(payload, next) {
+          let sourceConfig
+          const captureNext = typeof next === 'function'
+            ? async (...args) => {
+                const value = await next(...args)
+                if (sourceConfig === undefined) sourceConfig = value
+                return value
+              }
+            : next
+          const result = await handler.call(this, payload, captureNext)
+          return projectAgentRequestRouteHandoff(sourceConfig, result)
+        }, ...rest)
+      }
+    },
+  })
+  return contextWithTwinImageCapabilityFallback(routeAuthorityCtx, fallbackOptions)
+}

package/lib/delegated-call-config.js

@@ -0,0 +1,27 @@
+const ROUTE_OWNED_CALL_FIELDS = Object.freeze([
+  'reasoningEffort',
+  'temperature',
+  'maxTokens',
+  'stop',
+])
+
+/**
+ * Project an internal Vision Router delegation onto a different provider/model.
+ *
+ * The delegated route owns its own call defaults and compatibility. Carry the
+ * request payload and lifecycle through, but never leak source-route sampling,
+ * reasoning or output-limit state into the target adapter. DSH will materialize
+ * the target adapter's configured defaults when these fields are absent.
+ *
+ * Direct transports owned by Vision Router do not use this projection; their
+ * wire compatibility remains the Router's responsibility.
+ */
+export function projectDelegatedCallConfig(options) {
+  if (!options || typeof options !== 'object' || Array.isArray(options)) return options
+  if (!ROUTE_OWNED_CALL_FIELDS.some((field) => Object.hasOwn(options, field))) return options
+  const next = { ...options }
+  for (const field of ROUTE_OWNED_CALL_FIELDS) delete next[field]
+  return next
+}
+
+export const delegatedRouteOwnedCallFields = ROUTE_OWNED_CALL_FIELDS

package/lib/grounding-coordinate-runtime.js

@@ -6,6 +6,7 @@ import {
   createGroundingFrame,
   groundingFrameBoxToSource,
 } from './grounding-coordinate-frame.js'
+import { wrapVisionAttachmentHandleDefinition } from './vision-attachment-handle-runtime.js'
 
 const GROUNDING_TOOL_NAMES = new Set(['vision_ground', 'vision_detect'])
 let sharpPromise
@@ -205,9 +206,10 @@ function wrapGroundingDefinition(ctx, options, def) {
  * Give vision_ground / vision_detect one explicit provider-independent
  * coordinate protocol: the model always receives an exact 1000x1000
  * letterboxed raster, while callers always receive Host-canonical source
- * pixels. Core still owns provider selection, fallback, retry and failure
- * semantics; this boundary owns only raster geometry and original-image
- * annotation.
+ * pixels. The same registration seam also canonicalizes DSH text-only image
+ * handles before any Vision Router tool sees them, so short model-facing
+ * sha256 prefixes can never fall through into filesystem-path resolution.
+ * Core still owns provider selection, fallback, retry and failure semantics.
  */
 export function contextWithGroundingCoordinateFrame(ctx, options = {}) {
   if (!ctx || (typeof ctx !== 'object' && typeof ctx !== 'function')) return ctx
@@ -221,11 +223,11 @@ export function contextWithGroundingCoordinateFrame(ctx, options = {}) {
         return typeof value === 'function' ? value.bind(target) : value
       }
       const register = Reflect.get(target, property, target)
-      return (def, ...rest) => register.call(
-        target,
-        wrapGroundingDefinition(ctx, options, def),
-        ...rest,
-      )
+      return (def, ...rest) => {
+        const grounded = wrapGroundingDefinition(ctx, options, def)
+        const attachmentResolved = wrapVisionAttachmentHandleDefinition(grounded, options)
+        return register.call(target, attachmentResolved, ...rest)
+      }
     },
   })
 

package/lib/legacy-core-vision-policy-bridge.js

@@ -1,150 +1,21 @@
-import { currentSessionSurfacePolicy } from './session-surface-policy.js'
-import { knownSessionVisionMemory } from './session-vision-state.js'
-
-function isObject(value) {
-  return value !== null && typeof value === 'object'
-}
-
-function collectAttachmentIds(messages) {
-  const ids = []
-  const seen = new Set()
-  const pending = []
-  for (const message of messages ?? []) {
-    if (message && Array.isArray(message.content)) pending.push(...message.content)
-  }
-  while (pending.length > 0) {
-    const block = pending.pop()
-    if (!block || typeof block !== 'object') continue
-    if (block.type === 'image') {
-      const ref = block.attachment
-      const raw = ref && (ref.attachmentId ?? ref.id)
-      if (raw !== undefined && raw !== null) {
-        const id = String(raw)
-        if (id !== '' && !seen.has(id)) {
-          seen.add(id)
-          ids.push(id)
-        }
-      }
-    }
-    if (Array.isArray(block.content)) pending.push(...block.content)
-  }
-  return ids.reverse()
-}
-
-function appendVisionRouterAttachmentHint(payload, decision, config) {
-  const policy = currentSessionSurfacePolicy(config)
-  if (decision?.kind === 'reject' || policy.ownership !== 'vision-router-owned') {
-    return decision
-  }
-
-  // Vision Router-owned wrappers may deliberately preserve raw pixels when the
-  // delegated source model is itself multimodal. The provider wire carries the
-  // bytes, but not DSH's durable attachmentId, so a model that chooses a
-  // precision Vision Router tool would otherwise have to guess an id. Surface
-  // the exact current-turn ids as read-only model context while leaving the raw
-  // image blocks and the session-scoped lookup fence unchanged.
-  const source = Array.isArray(payload?.messages) ? payload.messages : []
-  const ids = collectAttachmentIds(source)
-  if (ids.length === 0) return decision
-
-  const baseMessages = Array.isArray(decision?.messages)
-    ? decision.messages
-    : source
-  const turn = Number.isInteger(payload?.turn) ? payload.turn : 'current'
-  const step = Number.isInteger(payload?.step) ? payload.step : 'step'
-  const hintId = `vision-router-attachment-refs-${turn}-${step}`
-  if (baseMessages.some((message) => message?.id === hintId)) return decision
-
-  const quoted = ids.map((id) => `"${id}"`).join(', ')
-  const hint = {
-    role: 'user',
-    id: hintId,
-    content: [{
-      type: 'text',
-      text: `Vision Router attachment references for the image(s) in this step: ${quoted}. If a Vision Router tool requires attachmentIds or an attachment-id image argument, use only these exact ids. Never guess or invent an attachment id.`,
-    }],
-    source: { kind: 'plugin', plugin: 'dsh-vision-router' },
-  }
-  const messages = [...baseMessages, hint]
-  return isObject(decision)
-    ? { ...decision, messages }
-    : { kind: 'continue', messages }
-}
-
-function rewriteTextOnlyDecision(payload, decision, rewriteHistoryImages, config) {
-  const policy = currentSessionSurfacePolicy(config)
-  if (
-    decision?.kind === 'reject' ||
-    policy.rewriteCurrentImages !== true ||
-    typeof rewriteHistoryImages !== 'function'
-  ) {
-    return decision
-  }
-
-  const source = Array.isArray(decision?.messages)
-    ? decision.messages
-    : Array.isArray(payload?.messages)
-      ? payload.messages
-      : undefined
-  if (!source) return decision
-
-  // Core registers the exact SessionMemoryView while processing this same
-  // pre-step. Reuse it here so a text-only fallback preserves cached visual
-  // descriptions instead of degrading them back to a generic attachment marker.
-  const memory = knownSessionVisionMemory(payload?.agent?.session)
-  const rewritten = rewriteHistoryImages(source, memory)
-  const messages = rewritten?.messages
-  if (!Array.isArray(messages) || messages === source) return decision
-  if (isObject(decision)) return { ...decision, messages }
-  return { kind: 'continue', messages }
-}
-
 /**
- * Preserve the two remaining pre-step compatibility behaviors without
- * impersonating Settings/config for Core.
+ * Retired pre-step compatibility shell.
+ *
+ * This module remains as a stable internal import while the 2.x composition is
+ * still being collapsed, but it deliberately owns no runtime behavior.
+ *
+ * Historical versions intercepted `agent/pre-step` for two model-only concerns:
+ * rewriting text-only image messages into `[attached image: ...]` markers and
+ * appending a synthetic attachment-id user message for Vision Router wrappers.
+ * DSH persists every admitted pre-step message as `user/message`, so both
+ * transforms crossed the durable transcript boundary and could surface in the
+ * Web conversation. User-owned image messages must instead remain byte-for-byte
+ * Session facts; request-only image projection belongs to the selected adapter.
  *
- * Ownership classification remains native-image-coexistence's responsibility.
- * Core consumes its five policy-derived switches through CoreVisionSurface.
- * This boundary only reuses the exact SessionMemoryView for a text-only image
- * rewrite and surfaces current durable attachment ids for a Vision Router-owned
- * route. Every other context service, Settings object, injected child and config
- * value passes through unchanged.
+ * Keep this function identity-only until runtime-composition removes the import
+ * in a dedicated closure cleanup. No Settings/config/service identity is
+ * impersonated and no `agent/pre-step` listener is installed here.
  */
-export function installLegacyCoreVisionPolicyBridge(
-  ctx,
-  config = {},
-  { rewriteHistoryImages } = {},
-) {
-  if (!isObject(ctx)) return { ctx, config }
-
-  const wrappedCtx = new Proxy(ctx, {
-    get(target, property) {
-      if (property === 'on') {
-        const on = Reflect.get(target, property, target)
-        if (typeof on !== 'function') return on
-        return (event, handler, ...rest) => {
-          if (event !== 'agent/pre-step' || typeof handler !== 'function') {
-            return on.call(target, event, handler, ...rest)
-          }
-          return on.call(target, event, async function legacyCoreVisionPolicyPreStep(payload, next) {
-            const decision = await handler.call(this, payload, next)
-            const rewritten = rewriteTextOnlyDecision(
-              payload,
-              decision,
-              rewriteHistoryImages,
-              config,
-            )
-            return appendVisionRouterAttachmentHint(payload, rewritten, config)
-          }, ...rest)
-        }
-      }
-      const value = Reflect.get(target, property, target)
-      return typeof value === 'function' ? value.bind(target) : value
-    },
-  })
-
-  return {
-    ctx: wrappedCtx,
-    config,
-  }
+export function installLegacyCoreVisionPolicyBridge(ctx, config = {}) {
+  return { ctx, config }
 }

package/lib/runtime-composition.js

@@ -15,6 +15,7 @@ import { createCoreVisionSurfaceRuntime } from './core-vision-surface.js'
 import { installSessionVisionIndexBoundary } from './session-vision-index.js'
 import { createSessionVisionRuntime } from './session-vision-runtime.js'
 import { installLegacyCoreVisionPolicyBridge } from './legacy-core-vision-policy-bridge.js'
+import { installSessionVisionModeBoundary } from './session-vision-mode-boundary.js'
 import { installPiAiBridgeWireCompat } from './pi-ai-bridge-wire-compat.js'
 import { installLiveModelDiscovery } from './live-model-discovery.js'
 import { installVisionModelRegistry } from './vision-model-registry.js'
@@ -28,6 +29,10 @@ import { installTesseractExecFileCompat } from './tesseract-exec-compat.js'
 import { installLocalMutationRouteBoundary } from './web-capability-boundary.js'
 import { installScreenshotSourceBoundary } from './screenshot-source-boundary.js'
 import { installVisionToolRuntimeBoundary } from './vision-tool-runtime-boundary.js'
+import {
+  configureAgentRequestRouteAuthority,
+  contextWithAgentRequestRouteAuthority,
+} from './agent-request-route-authority.js'
 import { contextWithGroundingCoordinateFrame } from './grounding-coordinate-runtime.js'
 import { installVisionRoutingRuntime } from './vision-routing-runtime.js'
 import { createCapabilityProfileStore } from './vision-capability-probe.js'
@@ -187,25 +192,32 @@ export function applyVisionRuntimeComposition(ctx, config = {}, core) {
     runtimeI18nCore,
     { logger: logging.logger, index: sessionVisionRuntime.index },
   )
-  // Only the real pre-step compatibility behaviors remain here. Session policy
-  // is not projected through fake Settings/config views; Core's policy-derived
-  // switches come exclusively from CoreVisionSurfaceRuntime.
+  // The retired bridge stays identity-only. Session mode is a new explicit
+  // boundary because it owns a different concern: per-Agent visibility and
+  // execution authority derived from DSH's modelSelection projection.
   const legacyCoreCompat = installLegacyCoreVisionPolicyBridge(
     sessionIndexCtx,
     nativeImageCompat.config,
     { rewriteHistoryImages: core.rewriteHistoryImages },
   )
+  const sessionVisionModeCompat = installSessionVisionModeBoundary(
+    legacyCoreCompat.ctx,
+    legacyCoreCompat.config,
+  )
 
   // Final structured-flow guard sits closest to core.apply so it sees the
   // actual tool registrations and pre-step listener. The diagnostic observer
   // remains immediately inside it so existing timeout/budget semantics stay
   // unchanged.
   const limitDiagnosticCtx = installVisionLimitDiagnostics(
-    legacyCoreCompat.ctx,
-    legacyCoreCompat.config,
+    sessionVisionModeCompat.ctx,
+    sessionVisionModeCompat.config,
     logging.logger,
   )
-  const structuredCtx = installStructuredFlowHardening(limitDiagnosticCtx, legacyCoreCompat.config)
+  const structuredCtx = installStructuredFlowHardening(
+    limitDiagnosticCtx,
+    sessionVisionModeCompat.config,
+  )
   const backgroundProfiling = installBackgroundCapabilityProfiling(
     structuredCtx,
     runtimeConfig,
@@ -306,6 +318,16 @@ export function applyVisionRuntimeComposition(ctx, config = {}, core) {
   })
   installTesseractExecFileCompat(backendRuntimeCtx)
 
+  // Core owns exactly one agent/request routing hook. Protect the completed
+  // provider/model handoff at that event boundary so future route-switch logic
+  // cannot accidentally carry source-model call defaults into the target.
+  configureAgentRequestRouteAuthority(backendRuntimeCtx, {
+    wrapperRoute: runtimeConfig.wrapperRoute,
+    chainRoute: runtimeConfig.chainRoute,
+    logger: logging.logger,
+  })
+  const coreRequestAuthorityCtx = contextWithAgentRequestRouteAuthority(backendRuntimeCtx)
+
   try {
     const c = hardenedConfig && typeof hardenedConfig === 'object' ? hardenedConfig : {}
     const local = c.localOllama && typeof c.localOllama === 'object' ? c.localOllama : {}
@@ -327,8 +349,8 @@ export function applyVisionRuntimeComposition(ctx, config = {}, core) {
       withVisionCircuitBreakerObserver(
         breakerShadowHealth.capture,
         () => core.apply(
-          backendRuntimeCtx,
-          legacyCoreCompat.config,
+          coreRequestAuthorityCtx,
+          sessionVisionModeCompat.config,
           {
             sessionVision: sessionVisionRuntime,
             coreVisionSurface: coreVisionSurfaceRuntime,

package/lib/session-surface-policy.js

@@ -1,4 +1,5 @@
 import { currentSessionVisionPolicy } from './native-image-coexistence.js'
+import { currentSessionVisionModeAuthority } from './session-vision-mode-authority.js'
 
 const OWNERSHIP = Object.freeze({
   PLUGIN_OWNED: 'vision-router-owned',
@@ -22,62 +23,87 @@ function normalizedOwnership(policy) {
  * Resolve one immutable, read-only snapshot of the Vision Router capability
  * surface for the current session.
  *
- * This layer does not classify model capability and does not grant authority.
- * `visionPolicy` is evidence produced by native-image-coexistence; this module
- * only projects that already-authoritative ownership decision onto the legacy
- * configuration/surface questions that used to be answered in several places.
+ * Image ownership and Vision-mode authority are intentionally distinct. The
+ * native-image policy answers who can consume raw pixels; the mode authority
+ * answers whether this Session explicitly selected a Vision Router-owned
+ * wrapper/twin for the current step. Only the latter can grant plugin tools or
+ * automatic visual work. This prevents a historical image, a native multimodal
+ * source model, or a stale request header from silently turning Vision back on.
+ *
+ * Durable transcript invariant: once a real session policy exists, Core may
+ * observe/index image blocks but may never replace a user-owned image message
+ * before the Agent loop appends it to the Session log. Image projection belongs
+ * at the adapter/request boundary. The historical `rewriteCurrentImages` bit is
+ * therefore intentionally ignored even when an older policy producer still
+ * exposes it; the compatibility field below is permanently false.
  */
 export function resolveSessionSurfacePolicy({
   visionPolicy,
+  visionModeAuthority,
   config = {},
   schemaBootstrapping = false,
 } = {}) {
   const source = isObject(visionPolicy) ? visionPolicy : undefined
+  const authority = isObject(visionModeAuthority) ? visionModeAuthority : undefined
   const value = isObject(config) ? config : {}
   const ownership = normalizedOwnership(source)
-  const native = ownership === OWNERSHIP.NATIVE
   const pluginOwned = ownership === OWNERSHIP.PLUGIN_OWNED
-  const textOnly = ownership === OWNERSHIP.TEXT_ONLY
 
-  // No active session policy means no session-specific rewrite/preservation
-  // authority. This distinction is important: absence is not the same as an
-  // explicit UNKNOWN capability snapshot, whose contract is non-destructive.
-  const preserveRawImages = source?.preserveRawImages === true
-  const rewriteCurrentImages = source?.rewriteCurrentImages === true
-  const allowStructuredBootstrap = source?.allowStructuredBootstrap !== false
-  const allowGenericAutoMount = source?.suppressGenericAutoMount !== true
+  // During schema bootstrap there is no real Session policy, so global Settings
+  // still decide which definitions Core registers. During a real step, an
+  // explicit authority snapshot wins; direct helper callers fall back to the
+  // already-classified plugin ownership instead of inventing an enabled mode.
+  const visionModeEnabled = authority !== undefined
+    ? authority.enabled === true
+    : source === undefined
+      ? true
+      : pluginOwned
+
+  // No active session policy means no session-specific preservation authority.
+  // During a real pre-step, every ownership result — including explicit
+  // text-only and unknown — preserves the durable user message unchanged.
+  const preserveRawImages = source !== undefined
+  const rewriteCurrentImages = false
+  const allowStructuredBootstrap = visionModeEnabled
+  const allowGenericAutoMount = visionModeEnabled
 
   const surface = Object.freeze({
     preserveRawImages,
     rewriteCurrentImages,
-    visionTools: value.tool !== false,
+    visionTools: value.tool !== false && visionModeEnabled,
     structuredBootstrap:
-      value.structuredVisionBootstrap === true && allowStructuredBootstrap,
+      value.structuredVisionBootstrap === true && visionModeEnabled,
     genericAutoMount:
-      value.autoActivateOnImage !== false && allowGenericAutoMount,
+      value.autoActivateOnImage !== false && visionModeEnabled,
     instantDescribe:
-      value.instantDescribe !== false && !native,
+      value.instantDescribe !== false && visionModeEnabled,
   })
 
   const overrides = {}
-  if (schemaBootstrapping === true && value.tool === false) overrides.tool = true
-  if (preserveRawImages && value.rewriteImages !== false) overrides.rewriteImages = false
-  if (native && value.instantDescribe !== false) overrides.instantDescribe = false
-  if (native && value.autoActivateOnImage !== false) overrides.autoActivateOnImage = false
-  if (!allowStructuredBootstrap && value.structuredVisionBootstrap !== false) {
-    overrides.structuredVisionBootstrap = false
+  if (schemaBootstrapping === true && source === undefined && value.tool === false) {
+    overrides.tool = true
+  }
+  // Core's historical rewriteImages switch controls an agent/pre-step message
+  // transform. Disable it for every real session policy so neither current nor
+  // historical user image blocks can be persisted as internal attachment text.
+  // Vision Router-owned adapters still perform their private request projection.
+  if (source !== undefined && value.rewriteImages !== false) overrides.rewriteImages = false
+
+  // The composer/model selection is the Session authority. When it is OFF,
+  // suppress every automatic/plugin-owned visual surface while preserving the
+  // durable image itself. Settings remain unchanged; these are turn-local Core
+  // projections only.
+  if (source !== undefined && !visionModeEnabled) {
+    if (value.tool !== false) overrides.tool = false
+    if (value.instantDescribe !== false) overrides.instantDescribe = false
+    if (value.autoActivateOnImage !== false) overrides.autoActivateOnImage = false
+    if (value.structuredVisionBootstrap !== false) overrides.structuredVisionBootstrap = false
   }
 
   return Object.freeze({
     ownership,
-    participates:
-      source !== undefined && (
-        pluginOwned ||
-        textOnly ||
-        surface.visionTools ||
-        surface.structuredBootstrap ||
-        surface.genericAutoMount
-      ),
+    visionModeEnabled,
+    participates: source !== undefined,
     preserveRawImages,
     rewriteCurrentImages,
     allowStructuredBootstrap,
@@ -87,10 +113,11 @@ export function resolveSessionSurfacePolicy({
   })
 }
 
-/** Read the turn-local ownership snapshot and resolve its capability surface. */
+/** Read the turn-local ownership + mode snapshots and resolve the Core surface. */
 export function currentSessionSurfacePolicy(config = {}, options = {}) {
   return resolveSessionSurfacePolicy({
     visionPolicy: currentSessionVisionPolicy(),
+    visionModeAuthority: currentSessionVisionModeAuthority(),
     config,
     schemaBootstrapping: options?.schemaBootstrapping === true,
   })