fix(session-reference): bind snapshots to prompts

packages/core/agent-loop/README.md

@@ -52,7 +52,7 @@ Configured agents start automatically. A model call requires both `provider` and
 
 The concrete `Agent` class, its `Inbox`, `runLoop`, and instance-bound publication/start controls are package-internal. The package root exports only the plugin/service/config contract, and the package exports map exposes no `./src/*` escape hatch; lifecycle owners create agents through `ctx.agents` rather than naming, constructing, or starting driver internals. One prepared session can be claimed by only one concrete driver, and everything observable happens through session events and the `agent/*` event taxonomy.
 
-Each concrete `send()` materializes content, resolved source, and attached contexts once as a detached, deeply frozen lossless-JSON FIFO item. If claimed, it is the sole ordinary message in its turn; its contexts are the prompt waterfall's default additional contexts and therefore append only after admission. The waterfall's returned allow is authoritative, so a listener wrapping `next()` preserves downstream `content` and `additionalContexts` unless it intentionally replaces them. A successor waits for the preceding ordinary turn's checkpoint to settle, while cancellation, disposal, a prompt block, or a pre-start failure may drop its contexts with the message. Running `steer()` enters the same record shape in the steering FIFO without dispatching `agent/prompt-submit`: an open turn records the steering message followed by its contexts at the next steering checkpoint before a request or continuation decision, but policy can still stop before another step; steering left after turn close and its checkpoint becomes later queued input with contexts intact unless terminal turn policy, cancellation, or disposal discards it. Open-turn `inject()` uses the same accepted-value boundary but defers in a FIFO while the current step executes assistant tool calls; successful batches place it after all results, and interrupted batches drain it before turn close. Malformed data throws before enqueue or append.
+Each concrete `send()` materializes content, resolved source, and attached contexts once as a detached, deeply frozen lossless-JSON FIFO item. If claimed, it is the sole ordinary message in its turn; its contexts are the prompt waterfall's default additional contexts and therefore materialize only after admission. Absent or `separate` placement appends an independent `context/message`; `prompt-prefix` placement bakes the context, the stable `## My request:` delimiter, and effective request into one `user/message`, whose model-hidden envelope retains display content and context descriptors. The waterfall's returned allow is authoritative, so a listener wrapping `next()` preserves downstream `content` and `additionalContexts` unless it intentionally replaces them. A successor waits for the preceding ordinary turn's checkpoint to settle, while cancellation, disposal, a prompt block, or a pre-start failure may drop its contexts with the message. Running `steer()` enters the same record shape in the steering FIFO without dispatching `agent/prompt-submit`; its next checkpoint applies the same separate-or-prefix placement to `steering/message`, while policy can still stop before another step. Steering left after turn close and its checkpoint becomes later queued input with contexts intact unless terminal turn policy, cancellation, or disposal discards it. Open-turn `inject()` uses the same accepted-value boundary but defers in a FIFO while the current step executes assistant tool calls; successful batches place it after all results, and interrupted batches drain it before turn close. Malformed data throws before enqueue or append.
 
 ### Loop lifecycle (`loop.ts`)
 

packages/core/agent-loop/src/loop.ts

@@ -12,7 +12,7 @@ import { BlockAssembler, HarnessError, LlmError, assertNever, deepFreeze, errorC
 import { agentEvents, agentInterruptReasonOf, assembleContextFor } from '@deepseek-ai/dsh-agent'
 import type { AgentEventDispatch, ContinuationDecision, HookContext, PromptDecision, RequestError, RequestErrorDecision } from '@deepseek-ai/dsh-agent'
 import { canonicalHeader } from '@deepseek-ai/dsh-session'
-import type { Session, TurnEndReason, TurnTrigger } from '@deepseek-ai/dsh-session'
+import type { PromptMessageData, Session, TurnEndReason, TurnTrigger } from '@deepseek-ai/dsh-session'
 import { createTransmissionLog, recordRequestHeader } from './request-log.ts'
 import type { TransmissionLog } from './request-log.ts'
 import { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
@@ -92,6 +92,45 @@ function stepFinishReason(finish: FinishReason): TurnEndReason | undefined {
 /** Internal control-flow sentinel; durable classification comes only from the turn signal. */
 const TURN_INTERRUPTED = new Error('turn interrupted')
 
+const PROMPT_PREFIX_REQUEST_DELIMITER: ContentBlock = {
+  type: 'text',
+  text: '\n\n## My request:\n',
+}
+
+interface PreparedPromptMessage {
+  data: PromptMessageData
+  separateContexts: HookContext[]
+}
+
+/** Bake declared prefix contexts into one reconstructable prompt message. */
+function preparePromptMessage(
+  content: ContentBlock[],
+  source: PromptMessageData['source'],
+  contexts: readonly HookContext[],
+): PreparedPromptMessage {
+  const prefixContexts = contexts.filter(context => context.placement === 'prompt-prefix')
+  const separateContexts = contexts.filter(context => context.placement !== 'prompt-prefix')
+  if (prefixContexts.length === 0) return { data: { content, source }, separateContexts }
+  return {
+    data: {
+      content: [
+        ...prefixContexts.flatMap(context => context.content),
+        PROMPT_PREFIX_REQUEST_DELIMITER,
+        ...content,
+      ],
+      source,
+      envelope: {
+        displayContent: content,
+        prefixContexts: prefixContexts.map(context => ({
+          source: context.source,
+          ...context.meta === undefined ? {} : { meta: context.meta },
+        })),
+      },
+    },
+    separateContexts,
+  }
+}
+
 /** Stop at an explicit cooperative boundary without stringifying the runtime reason. */
 function interruptionCheckpoint(signal: AbortSignal): void {
   if (signal.aborted) throw TURN_INTERRUPTED
@@ -240,9 +279,14 @@ async function runTurn(
   const drainSteering = (): boolean => {
     const messages = handle.inbox.drainSteering()
     for (const message of messages) {
-      session.append('steering/message', { turn, content: message.content, source: message.source }, { surfaceOp: 'append' })
-      for (const context of message.contexts) {
-        session.append('context/message', context, { surfaceOp: 'append' })
+      const prepared = preparePromptMessage(message.content, message.source, message.contexts)
+      session.append('steering/message', { turn, ...prepared.data }, { surfaceOp: 'append' })
+      for (const context of prepared.separateContexts) {
+        session.append('context/message', {
+          content: context.content,
+          source: context.source,
+          ...context.meta === undefined ? {} : { meta: context.meta },
+        }, { surfaceOp: 'append' })
       }
     }
     return messages.length > 0
@@ -316,11 +360,12 @@ async function runTurn(
     } else {
       // `allow.content` REPLACES the prompt bytes (a rewrite); absent keeps them.
       const content = promptDecision.content ?? message.content
-      session.append('user/message', { content, source: message.source }, { surfaceOp: 'append' })
-      // Every `allow.additionalContexts` entry is a separate context/message the
-      // next request also sees. The turn is open, so inject() appends each one
-      // into THIS turn without flattening provenance or metadata.
-      for (const context of promptDecision.additionalContexts ?? []) {
+      const prepared = preparePromptMessage(content, message.source, promptDecision.additionalContexts ?? [])
+      session.append('user/message', prepared.data, { surfaceOp: 'append' })
+      // Separate contexts still enter THIS turn through inject(). Prefix
+      // contexts are already baked into the user/message with their durable
+      // display envelope, so appending them again would duplicate model input.
+      for (const context of prepared.separateContexts) {
         agent.inject(context.content, {
           source: context.source,
           ...context.meta !== undefined ? { meta: context.meta } : {},

packages/core/agent-loop/tests/contract-regressions.spec.ts

@@ -875,24 +875,51 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
     expect(agent.status).toBe('running')
     const content = [{ type: 'text' as const, text: 'accepted-steer' }]
     const source = { kind: 'plugin' as const, plugin: 'accepted-source' }
-    const contexts: HookContext[] = [{
-      content: [{ type: 'text', text: 'accepted-steering-context' }],
-      source: { kind: 'plugin', plugin: 'steering-context' },
-    }]
+    const contexts: HookContext[] = [
+      {
+        content: [{ type: 'text', text: 'accepted-steering-prefix' }],
+        source: { kind: 'plugin', plugin: 'steering-prefix' },
+        placement: 'prompt-prefix',
+      },
+      {
+        content: [{ type: 'text', text: 'accepted-steering-context' }],
+        source: { kind: 'plugin', plugin: 'steering-context' },
+        meta: { kind: 'separate-card' },
+      },
+      {
+        content: [{ type: 'text', text: 'accepted-steering-context-without-meta' }],
+        source: { kind: 'plugin', plugin: 'steering-context-without-meta' },
+      },
+    ]
     agent.steer(content, { source, contexts })
     content[0]!.text = 'caller-mutated-steer'
     source.plugin = 'caller-mutated-source'
-    contexts[0]!.content[0] = { type: 'text', text: 'caller-mutated-steering-context' }
+    contexts[0]!.content[0] = { type: 'text', text: 'caller-mutated-steering-prefix' }
+    contexts[0]!.placement = 'separate'
+    contexts[1]!.content[0] = { type: 'text', text: 'caller-mutated-steering-context' }
+    contexts[2]!.content[0] = { type: 'text', text: 'caller-mutated-steering-context-without-meta' }
     const idle = waitForIdle(ctx, agent)
     release.resolve(undefined)
     await idle
 
     expect(notifiedContent).toEqual([{ type: 'text', text: 'accepted-steer' }])
     expect(notifiedSource).toEqual({ kind: 'plugin', plugin: 'accepted-source' })
-    expect(notifiedContexts).toEqual([{
-      content: [{ type: 'text', text: 'accepted-steering-context' }],
-      source: { kind: 'plugin', plugin: 'steering-context' },
-    }])
+    expect(notifiedContexts).toEqual([
+      {
+        content: [{ type: 'text', text: 'accepted-steering-prefix' }],
+        source: { kind: 'plugin', plugin: 'steering-prefix' },
+        placement: 'prompt-prefix',
+      },
+      {
+        content: [{ type: 'text', text: 'accepted-steering-context' }],
+        source: { kind: 'plugin', plugin: 'steering-context' },
+        meta: { kind: 'separate-card' },
+      },
+      {
+        content: [{ type: 'text', text: 'accepted-steering-context-without-meta' }],
+        source: { kind: 'plugin', plugin: 'steering-context-without-meta' },
+      },
+    ])
     expect(Object.isFrozen(notifiedContent)).toBe(true)
     expect(Object.isFrozen(notifiedContent?.[0])).toBe(true)
     expect(Object.isFrozen(notifiedSource)).toBe(true)
@@ -900,14 +927,28 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
     const recorded = agent.session.events.flatMap(event => event.type === 'steering/message' ? [event.data] : [])
     expect(recorded).toContainEqual({
       turn: 1,
-      content: [{ type: 'text', text: 'accepted-steer' }],
+      content: [
+        { type: 'text', text: 'accepted-steering-prefix' },
+        { type: 'text', text: '\n\n## My request:\n' },
+        { type: 'text', text: 'accepted-steer' },
+      ],
       source: { kind: 'plugin', plugin: 'accepted-source' },
+      envelope: {
+        displayContent: [{ type: 'text', text: 'accepted-steer' }],
+        prefixContexts: [{
+          source: { kind: 'plugin', plugin: 'steering-prefix' },
+        }],
+      },
     })
     const request = JSON.stringify(adapter.requests[1]!.messages)
     expect(request).toContain('accepted-steer')
+    expect(request).toContain('accepted-steering-prefix')
     expect(request).toContain('accepted-steering-context')
+    expect(request).toContain('accepted-steering-context-without-meta')
     expect(request).not.toContain('caller-mutated-steer')
+    expect(request).not.toContain('caller-mutated-steering-prefix')
     expect(request).not.toContain('caller-mutated-steering-context')
+    expect(request).not.toContain('caller-mutated-steering-context-without-meta')
 
     const steeringIndex = agent.session.events.findIndex(event => event.type === 'steering/message')
     const contextIndex = agent.session.events.findIndex(event => event.type === 'context/message'

packages/core/agent-loop/tests/interception.spec.ts

@@ -117,6 +117,55 @@ describe('agent/prompt-submit', () => {
     expect(sent).toContain('extra ctx')
   })
 
+  it('bakes prompt-prefix contexts and a request delimiter into one durable user message', async () => {
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('prefixed'), { provider: 'mock', model: 'mock' })
+
+    ctx.on('agent/prompt-submit', async (_agent, _content, _source, _signal, next): Promise<PromptDecision> => {
+      const downstream = await next()
+      return downstream.kind === 'block'
+        ? downstream
+        : { ...downstream, content: [{ type: 'text', text: 'rewritten request' }] }
+    })
+    agent.send([{ type: 'text', text: 'original request' }], {
+      contexts: [{
+        content: [{ type: 'text', text: 'untrusted prefix' }],
+        source: { kind: 'plugin', plugin: 'prefix' },
+        placement: 'prompt-prefix',
+        meta: { kind: 'prefix-card' },
+      }],
+    })
+    await waitForIdle(ctx, agent)
+
+    const log = events(agent)
+    const user = log.find(event => event.type === 'user/message')
+    expect(user?.type === 'user/message' && user.data).toEqual({
+      content: [
+        { type: 'text', text: 'untrusted prefix' },
+        { type: 'text', text: '\n\n## My request:\n' },
+        { type: 'text', text: 'rewritten request' },
+      ],
+      source: { kind: 'user' },
+      envelope: {
+        displayContent: [{ type: 'text', text: 'rewritten request' }],
+        prefixContexts: [{
+          source: { kind: 'plugin', plugin: 'prefix' },
+          meta: { kind: 'prefix-card' },
+        }],
+      },
+    })
+    expect(log.some(event => event.type === 'context/message')).toBe(false)
+    expect(adapter.requests[0]?.messages.at(-1)).toEqual({
+      role: 'user',
+      content: [
+        { type: 'text', text: 'untrusted prefix' },
+        { type: 'text', text: '\n\n## My request:\n' },
+        { type: 'text', text: 'rewritten request' },
+      ],
+    })
+  })
+
   it('runs pre-step after prompt rewrites and injected context become durable', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)

packages/core/agent/README.md

@@ -48,7 +48,7 @@ The lifecycle edges have two important local caveats. `agent/created` runs after
 
 Most interception points are cooperative waterfalls returning seam-specific decisions. Turn-scoped asynchronous seams receive one explicit `AbortSignal`, with `signal` immediately before a waterfall's final `next`; listeners may cooperate but must not retain it as authority over another turn. The signal remains authoritative through terminal policy and is retired immediately before `turn/end` publication, so terminal observers and the following durability flush cannot cancel completed turn work. `agent/pre-step` and `agent/post-step` are serial checkpoints around a step's durable work, while `agent/request-error` is the failed-model-request recovery waterfall: it receives the exact error, normalized failure facts, immutable prior-retried facts, and signal after the failed step closes; a retry opens a new numbered step. `agent/turn-stop` is the terminal serial fold: it runs after ordinary continuation and steering folding, and a returned stop remains in force through turn close and flush so later steering cannot create an extra step or turn. Ordinary queued prompts remain intact. Effective broad cancellation first emits the observe-only `agent/cancel-requested` with its resolved typed cause, then clears queues and aborts; notification failures are contained and cannot veto the stop. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns signal lifetime; the [agent-scope runtime-design Agent Note](../../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way) owns scoped dispatch and terminal settlement.
 
-`PromptDecision.additionalContexts` is an array so every injected context keeps its own source and metadata. `SendOptions.contexts` binds the same shape to one queued message before prompt interception: the default allow decision carries it forward, while a blocked prompt records no context. A listener that wraps a downstream allow preserves its `content` and `additionalContexts` unless it intentionally replaces either field; the returned allow is authoritative. A `ContinuationDecision` reason is narrower: it becomes a `steering/message`, not a `context/message`, and therefore carries only content and source.
+`PromptDecision.additionalContexts` is an array so every context keeps its own source, metadata, and placement. `SendOptions.contexts` binds the same shape to one queued message before prompt interception: the default allow decision carries it forward, while a blocked prompt records no context. Absent or `separate` placement writes an independent `context/message`; `prompt-prefix` writes the context, `## My request:` delimiter, and effective prompt into one `user/message` or `steering/message`, whose model-hidden envelope retains the direct prompt and context descriptors for human replay. A listener that wraps a downstream allow preserves its `content` and `additionalContexts` unless it intentionally replaces either field; the returned allow is authoritative. A `ContinuationDecision` reason is narrower: it becomes a `steering/message` without attached context metadata.
 
 Turn and step boundaries and the model token stream are durable `session/event` facts rather than mirrored `agent/*` notifications. Consumers read `turn/*`, `step/*`, and `assistant/chunk` from the session feed; tool policy and outcome observation belong to the complete pipeline documented by [`dsh-tools`](../tools/README.md).
 
@@ -56,8 +56,8 @@ Turn and step boundaries and the model token stream are durable `session/event`
 
 The handle every plugin programs against:
 
-- `agent.send(content, options?)` — queue one independent FIFO item. If claimed, that item becomes the sole ordinary message in its turn; a claimed FIFO successor waits for that turn's checkpoint to settle. Broad cancellation, disposal, or a pre-start failure may instead drop it without a turn. Omitting `options.source` attests direct human input as `{ kind: 'user' }` and may authorize policy consumers, so plugins, schedulers, and other non-human producers provide their own source. Content, resolved source, and `options.contexts` become one detached, deeply frozen lossless-JSON record before `agent/queued` and enqueue; invalid data throws synchronously, and caller or notification-listener in-place mutation cannot change the log or model input. The contexts become individual `context/message` events after the accepted user message, unless `agent/prompt-submit` blocks or replaces the default additional-context decision. The [one-send-one-turn Agent Note](../../../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md) owns the turn rationale.
-- `agent.steer(content, options?)` — while running, queue steering for the next checkpoint without dispatching `agent/prompt-submit`; when idle, delegate to `send()`. Attached contexts remain in the same frozen record, append immediately after that steering message when drained, survive late-steering conversion to queued input, and disappear with their message on cancellation or terminal discard. Policy can still stop before another step; after turn close and its checkpoint, remaining steering becomes later queued input unless terminal turn policy, cancellation, or disposal discards it.
+- `agent.send(content, options?)` — queue one independent FIFO item. If claimed, that item becomes the sole ordinary message in its turn; a claimed FIFO successor waits for that turn's checkpoint to settle. Broad cancellation, disposal, or a pre-start failure may instead drop it without a turn. Omitting `options.source` attests direct human input as `{ kind: 'user' }` and may authorize policy consumers, so plugins, schedulers, and other non-human producers provide their own source. Content, resolved source, and `options.contexts` become one detached, deeply frozen lossless-JSON record before `agent/queued` and enqueue; invalid data throws synchronously, and caller or notification-listener in-place mutation cannot change the log or model input. After admission, separate contexts become `context/message` events, while prompt-prefix contexts are baked before the effective request in the same `user/message`; a block or replacement of the default additional-context decision can discard them. The [one-send-one-turn Agent Note](../../../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md) owns the turn rationale.
+- `agent.steer(content, options?)` — while running, queue steering for the next checkpoint without dispatching `agent/prompt-submit`; when idle, delegate to `send()`. Attached contexts remain in the same frozen record; separate contexts append immediately after the steering event, while prompt-prefix contexts are baked into that steering event. Both survive late-steering conversion to queued input and disappear with their message on cancellation or terminal discard. Policy can still stop before another step; after turn close and its checkpoint, remaining steering becomes later queued input unless terminal turn policy, cancellation, or disposal discards it.
 - `agent.inject(content, options?)` — accept detached in-session context without running the model; the next request sees its `context/message` with `content` rendered verbatim as a user-role message. `options.meta` persists opaque JSON state without rendering it. While a turn is open it joins that turn, deferring FIFO while the current tool batch executes and draining before turn close if execution is interrupted; while idle it is wrapped in a one-shot `injection` turn and durability checkpoint ([the turn-enclosure invariant](../../../.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.md)).
 - `agent.cancel(cause?)` — cancel ALL pending work: an omitted cause means `{ kind: 'user' }`; TypeScript restricts callers to the `user | parent` union, and an active holder copies its discriminant into a detached frozen signal reason before aborting. An effective call emits `agent/cancel-requested` with the cause before clearing queued and steering work; observers may synchronize state but cannot veto cancellation. The same-process typed seam adds no runtime validation or compatibility fallback for untyped callers. Repeated active-turn cancellation is first-wins for the signal, and idle cancellation is a safe no-op with no notification. ACP maps to `user`, while in-process parent propagation maps to `parent`. The cause is runtime-only; durable `turn/end` stays coarse `aborted`.
 - `agent.whenIdle()` — resolve once the agent reaches quiescence after settling out of `running` (idle → immediately; disposed → awaits the loop exit). A non-owner's quiescence-observation hook: it observes the work settling WITHOUT tearing the agent down. Teardown is separate — a lifecycle owner stops and unregisters via `AgentHandle.dispose()`, which awaits the loop exit directly.

packages/core/agent/src/types.ts

@@ -57,17 +57,24 @@ export type AgentStatus = 'idle' | 'running' | 'disposed'
 export interface HookContext {
   content: ContentBlock[]
   source: MessageSource
+  /**
+   * Model placement. Absent or `separate` records an independent
+   * `context/message`; `prompt-prefix` prepends this context and a stable
+   * request delimiter to the same user-role message as its attached prompt.
+   */
+  placement?: 'separate' | 'prompt-prefix'
   /** Opaque JSON state retained in the session event but hidden from the model. */
   meta?: JsonValue
 }
 
 /**
- * Prompt interception result. `allow.content` replaces the prompt and each
- * `additionalContexts` entry becomes a separate context message. `block`
- * records a durable `prompt/blocked` and ends the claimed prompt's zero-step
- * turn as rejected. An `allow` returned by a listener is authoritative: a
- * listener wrapping `next()` preserves downstream `content` and
- * `additionalContexts` unless it intentionally replaces them.
+ * Prompt interception result. `allow.content` replaces the prompt. Each
+ * `additionalContexts` entry follows its declared placement: separate context
+ * message by default, or a prefix inside the prompt's user-role message.
+ * `block` records a durable `prompt/blocked` and ends the claimed prompt's
+ * zero-step turn as rejected. An `allow` returned by a listener is
+ * authoritative: a listener wrapping `next()` preserves downstream `content`
+ * and `additionalContexts` unless it intentionally replaces them.
  */
 export type PromptDecision =
   | { kind: 'allow'; content?: ContentBlock[]; additionalContexts?: HookContext[] }

packages/core/session/README.md

@@ -60,7 +60,7 @@ Durable values need one accepted representation, not a check followed by a secon
 
 `request/header` records a full canonical snapshot of the non-history request envelope with reason `initial`, `resume`, or `change`. `foldRequestHeader()` selects the latest snapshot; legacy delta events and the removed `fallback` reason are rejected. `messagePrefix` remains separate from derived history. See the [reconstructable-requests Agent Note](../../../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md).
 
-`context/message` renders its `content` verbatim as a user-role message, and may attach JSON `meta` for replayable plugin state; metadata remains durable but is excluded from `deriveMessages()`.
+`context/message` renders its `content` verbatim as a user-role message, and may attach JSON `meta` for replayable plugin state; metadata remains durable but is excluded from `deriveMessages()`. A `user/message` or `steering/message` with prompt-prefix context keeps the exact combined model bytes in `content` and stores a model-hidden `envelope` containing the direct `displayContent` and prefix context source/metadata descriptors. `displayPromptContent()` selects the human-facing prompt without changing derived history.
 
 ### Session event vocabulary (`types.ts`)
 
@@ -93,7 +93,7 @@ Every `SessionEvent` carries two optional top-level fields (structural metadata)
 
 #### What the model sees
 
-The model receives projections of `user/message`, `assistant/message`, `tool/result`, `context/message`, and `steering/message` surface entries verbatim: each is a user- or assistant-role message carrying its content blocks unchanged. Tool calls live inside assistant messages. Chunks, boundaries, usage, hook records, todo records, and other log-only events add no message.
+The model receives projections of `user/message`, `assistant/message`, `tool/result`, `context/message`, and `steering/message` surface entries verbatim: each is a user- or assistant-role message carrying its content blocks unchanged. A prompt envelope changes only human presentation; its prefix context and request delimiter are already present in the event content. Tool calls live inside assistant messages. Chunks, boundaries, usage, hook records, todo records, and other log-only events add no message.
 
 #### Token effect
 

packages/core/session/src/index.ts

@@ -11,9 +11,9 @@ import { isAbsolute } from 'node:path'
 import { deepFreeze } from '@deepseek-ai/dsh-llm'
 import { scopeOf, scopeTarget } from '@deepseek-ai/dsh-scope'
 import type { Scoped } from '@deepseek-ai/dsh-scope'
-import type { Message } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, Message } from '@deepseek-ai/dsh-llm'
 import { SESSION_FORMAT_VERSION, SessionId } from './types.ts'
-import type { CreateSessionOptions, EpochHeader, OutOfBandSessionEventType, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SurfaceIntent, SurfaceEventType, TurnTrigger } from './types.ts'
+import type { CreateSessionOptions, EpochHeader, OutOfBandSessionEventType, PromptMessageData, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SurfaceIntent, SurfaceEventType, TurnTrigger } from './types.ts'
 import { snapshotJsonValue } from './json.ts'
 import { SurfaceManager } from './surface.ts'
 import type { SessionSurface } from './surface.ts'
@@ -27,6 +27,15 @@ export type { SessionSurface, SurfaceFoldReplacement, SurfaceFoldResult } from '
 export { foldSurface, isSurfaceEvent, isSurfaceEligibleType } from './surface.ts'
 export { canonicalHeader, foldRequestHeader, headerEquals } from './request-header.ts'
 
+/**
+ * Return the human-facing prompt blocks from a durable prompt message.
+ * @param data - ordinary or steering prompt event data.
+ * @returns the effective direct prompt, excluding baked prefix context.
+ */
+export function displayPromptContent(data: PromptMessageData): ContentBlock[] {
+  return data.envelope?.displayContent ?? data.content
+}
+
 /**
  * Find the latest closed message-triggered turn, excluding injection and
  * plugin-owned zero-step turns.
@@ -521,9 +530,11 @@ export class Session {
     // trace/replay data.
 
     switch (event.type) {
-      // Injected context and mid-turn steering project identically to a user
-      // prompt: content verbatim, in user role. context's `source`/`meta` and
-      // steering's `turn` are log-only and do not reach the model. Do NOT
+      // Injected context, ordinary prompts, and mid-turn steering project
+      // identically in user role: the event's model-facing content stays
+      // verbatim. A prompt envelope is model-hidden display metadata; its
+      // prefix bytes are already present in content. context's `source`/`meta`
+      // and steering's `turn` are also log-only. Do NOT
       // re-add per-type framing (e.g. `<context>`/`<steering>`) here: framing is
       // caller-owned — a producer bakes it into `content`, as workspace-context
       // does with `<system-reminder>` — or, if reintroduced, must be driven by

packages/core/session/src/types.ts

@@ -180,6 +180,37 @@ export interface EpochHeader {
  */
 export type RequestHeaderReason = 'initial' | 'resume' | 'change'
 
+/** Durable model-hidden annotation for one context baked into a prompt message. */
+export interface PromptPrefixContext {
+  /** Producer provenance retained for transcript presentation and inspection. */
+  source: MessageSource
+  /** Opaque JSON state retained in the session event but hidden from the model. */
+  meta?: JsonValue
+}
+
+/**
+ * Human-facing view of a prompt whose exact model content includes prefixed
+ * context. `content` on the owning event remains the reconstructable model
+ * input; this envelope prevents transcript, title, and re-reference consumers
+ * from treating the baked context as direct human text.
+ */
+export interface PromptMessageEnvelope {
+  /** Effective user prompt after interception rewrites, without baked context. */
+  displayContent: ContentBlock[]
+  /** Ordered descriptors for contexts already baked into the event content. */
+  prefixContexts: PromptPrefixContext[]
+}
+
+/** Shared payload for ordinary and steering prompt messages. */
+export interface PromptMessageData {
+  /** Exact model-facing blocks, including any baked prompt-prefix contexts. */
+  content: ContentBlock[]
+  /** Producer provenance for the direct prompt. */
+  source: MessageSource
+  /** Present only when prompt-prefix contexts were baked into `content`. */
+  envelope?: PromptMessageEnvelope
+}
+
 /**
  * The merge-extensible, append-only source of truth for an agent interaction.
  * Message history is derived from this log. Every event is lossless JSON and
@@ -206,7 +237,7 @@ export interface SessionEventMap {
   /** Closes step `step` of turn `turn`. */
   'step/end': { turn: number; step: number }
   /** A user-visible prompt (the queued message claimed for this turn). */
-  'user/message': { content: ContentBlock[]; source: MessageSource }
+  'user/message': PromptMessageData
   /**
    * Durable record of a prompt veto and its reason. It is log-only: the blocked
    * prompt never enters the model-visible surface, and its turn runs zero steps.
@@ -254,7 +285,7 @@ export interface SessionEventMap {
    */
   'tool/result': { turn: number; step: number; callId: CallId; content: ContentBlock[]; isError: boolean; error?: { name: string; code: string }; meta?: unknown }
   /** Steering content injected between steps of a running turn. */
-  'steering/message': { turn: number; content: ContentBlock[]; source: MessageSource }
+  'steering/message': PromptMessageData & { turn: number }
   /** Whole-list snapshot; latest write wins on replay. Log-only UI state; never derived history. */
   'todo/write': { todos: TodoItem[] }
   /**

packages/core/session/tests/session.spec.ts

@@ -2,6 +2,7 @@ import { describe, expect, expectTypeOf, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import SessionStore, {
+  displayPromptContent,
   findLastMessageTurnEnd,
   SESSION_FORMAT_VERSION,
   Session,
@@ -135,6 +136,35 @@ describe('Session', () => {
     expect(steeringMessage!.content).toEqual([{ type: 'text', text: 'focus on tests' }])
   })
 
+  it('derives baked prompt context while exposing only the direct prompt for display', () => {
+    const session = new Session(SessionId('prompt-envelope'))
+    const event = session.append('user/message', {
+      content: [
+        { type: 'text', text: 'background' },
+        { type: 'text', text: '\n\n## My request:\n' },
+        { type: 'text', text: 'question' },
+      ],
+      source: { kind: 'user' },
+      envelope: {
+        displayContent: [{ type: 'text', text: 'question' }],
+        prefixContexts: [{ source: { kind: 'plugin', plugin: 'reference' }, meta: { kind: 'card' } }],
+      },
+    }, { surfaceOp: 'append' })
+
+    expect(session.deriveMessages()).toEqual([{
+      role: 'user',
+      content: [
+        { type: 'text', text: 'background' },
+        { type: 'text', text: '\n\n## My request:\n' },
+        { type: 'text', text: 'question' },
+      ],
+    }])
+    expect(displayPromptContent(event.data)).toEqual([{ type: 'text', text: 'question' }])
+    expect(Object.isFrozen(event.data.envelope?.displayContent)).toBe(true)
+    expect(new Session(SessionId('prompt-envelope-replay'), session.events).deriveMessages())
+      .toEqual(session.deriveMessages())
+  })
+
   it('keeps context meta durable in the event while hiding it from the projection', () => {
     const session = new Session(SessionId('s2-raw'))
     const meta = {