feat(session): add cross-session references

packages/core/agent-loop/README.md

@@ -48,7 +48,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 plus resolved source once as a detached, deeply frozen lossless-JSON FIFO item. If claimed, it is the sole ordinary message in its turn; a successor waits for the preceding ordinary turn's checkpoint to settle, while cancellation, disposal, or a pre-start failure may drop it without a turn. Running `steer()` enters the steering FIFO: an open turn records it 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 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 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.
 
 ### Loop lifecycle (`loop.ts`)
 

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

@@ -207,9 +207,10 @@ export class ReactLoopAgent implements Agent {
    */
   private acceptMessage(content: ContentBlock[], options?: SendOptions): InboxMessage {
     const source = this.resolveSource(options)
-    const accepted = snapshotJsonValue({ content, source })
+    const contexts = options?.contexts ?? []
+    const accepted = snapshotJsonValue({ content, source, contexts })
     if (accepted === undefined) {
-      throw new TypeError('agent message content and source must be losslessly JSON-serializable')
+      throw new TypeError('agent message content, source, and contexts must be losslessly JSON-serializable')
     }
     return deepFreeze(accepted)
   }
@@ -232,7 +233,7 @@ export class ReactLoopAgent implements Agent {
     this.assertNotDisposed()
     const accepted = this.acceptMessage(content, options)
     this.#inbox.enqueue(accepted)
-    const info = { source: accepted.source, steering: false } as const
+    const info = { source: accepted.source, contexts: accepted.contexts, steering: false } as const
     agentEvents(this.loopCtx, this).emit('agent/queued', accepted.content, info)
   }
 
@@ -241,7 +242,7 @@ export class ReactLoopAgent implements Agent {
     if (this._status !== 'running') { this.send(content, options); return }
     const accepted = this.acceptMessage(content, options)
     this.#inbox.steer(accepted)
-    const info = { source: accepted.source, steering: true } as const
+    const info = { source: accepted.source, contexts: accepted.contexts, steering: true } as const
     agentEvents(this.loopCtx, this).emit('agent/queued', accepted.content, info)
   }
 

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

@@ -7,11 +7,13 @@
  */
 
 import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
+import type { HookContext } from '@deepseek-ai/dsh-agent'
 
 /** One message waiting in an agent's inbox. */
 export interface InboxMessage {
   content: ContentBlock[]
   source: MessageSource
+  contexts: HookContext[]
 }
 
 /**

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

@@ -207,6 +207,9 @@ async function runTurn(
     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' })
+      }
     }
     return messages.length > 0
   }
@@ -263,7 +266,10 @@ async function runTurn(
     // throws) is caught below and the turn still closes.
     const promptDecision = await events.waterfall(
       'agent/prompt-submit', message.content, message.source,
-      () => Promise.resolve<PromptDecision>({ kind: 'allow' }),
+      () => Promise.resolve<PromptDecision>({
+        kind: 'allow',
+        ...message.contexts.length === 0 ? {} : { additionalContexts: message.contexts },
+      }),
     )
     if (promptDecision.kind === 'block') {
       session.append('prompt/blocked', { content: message.content, source: message.source, reason: promptDecision.reason })
@@ -502,7 +508,7 @@ async function runTurn(
 
       // A continuation reason becomes next-step steering.
       if (decision.action === 'continue' && decision.reason) {
-        handle.inbox.steer({ content: decision.reason.content, source: decision.reason.source })
+        handle.inbox.steer({ content: decision.reason.content, source: decision.reason.source, contexts: [] })
       }
       let shouldContinue = decision.action === 'continue'
 

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

@@ -4,7 +4,7 @@ import LlmService, { CallId, ContentBlock, MessageSource, ProviderRequestId, Str
 import SessionStore, { Session, SessionEvent, SessionId, TurnEndReason } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { defineTool, type PostToolDecision } from '@deepseek-ai/dsh-tools'
-import AgentRegistry, { type Agent, type ContinuationDecision } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { type Agent, type ContinuationDecision, type HookContext } from '@deepseek-ai/dsh-agent'
 import AgentLoop, { DEFAULT_MAX_PARALLEL_TOOL_CALLS } from '@deepseek-ai/dsh-agent-loop'
 import { prepareReactLoopAgent } from '../src/agent.ts'
 import * as Invariants from '@deepseek-ai/dsh-invariants'
@@ -781,14 +781,14 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
       },
     }))
 
-    const queuedSources: { source: MessageSource; steering: boolean }[] = []
+    const queuedSources: { source: MessageSource; contexts: HookContext[]; steering: boolean }[] = []
     ctx.on('agent/queued', (_agent, _content, info) => void queuedSources.push(info))
 
     send(agent, 'go') // no explicit source → default {kind:'user'} must be visible
     await waitForIdle(ctx, agent)
 
-    expect(queuedSources[0]).toEqual({ source: { kind: 'user' }, steering: false })
-    expect(queuedSources[1]).toEqual({ source: { kind: 'plugin', plugin: 'goal' }, steering: true })
+    expect(queuedSources[0]).toEqual({ source: { kind: 'user' }, contexts: [], steering: false })
+    expect(queuedSources[1]).toEqual({ source: { kind: 'plugin', plugin: 'goal' }, contexts: [], steering: true })
     // The drain appends the durable steering/message with the caller's source
     // intact — the log, not a transient emit, is where consumers read it.
     const steeringSources = agent.session.events.flatMap(e => e.type === 'steering/message' ? [e.data.source] : [])
@@ -803,24 +803,39 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
     const source = { kind: 'plugin' as const, plugin: 'accepted-source' }
     let notifiedContent: ContentBlock[] | undefined
     let notifiedSource: MessageSource | undefined
+    let notifiedContexts: HookContext[] | undefined
     ctx.on('agent/queued', (subject, acceptedContent, info) => {
       if (subject !== agent || info.steering) return
       // Retain the exact notification references: cloning here would test the
       // listener's copy rather than the event/inbox ownership boundary.
       notifiedContent = acceptedContent
       notifiedSource = info.source
+      notifiedContexts = info.contexts
     })
 
-    agent.send(content, { source })
+    const contexts: HookContext[] = [{
+      content: [{ type: 'text', text: 'accepted-context' }],
+      source: { kind: 'plugin', plugin: 'context-source' },
+      meta: { version: 1 },
+    }]
+    agent.send(content, { source, contexts })
     content[0]!.text = 'caller-mutated-send'
     source.plugin = 'caller-mutated-source'
+    contexts[0]!.content[0] = { type: 'text', text: 'caller-mutated-context' }
     await waitForIdle(ctx, agent)
 
     expect(notifiedContent).toEqual([{ type: 'text', text: 'accepted-send' }])
     expect(notifiedSource).toEqual({ kind: 'plugin', plugin: 'accepted-source' })
+    expect(notifiedContexts).toEqual([{
+      content: [{ type: 'text', text: 'accepted-context' }],
+      source: { kind: 'plugin', plugin: 'context-source' },
+      meta: { version: 1 },
+    }])
     expect(Object.isFrozen(notifiedContent)).toBe(true)
     expect(Object.isFrozen(notifiedContent?.[0])).toBe(true)
     expect(Object.isFrozen(notifiedSource)).toBe(true)
+    expect(Object.isFrozen(notifiedContexts)).toBe(true)
+    expect(Object.isFrozen(notifiedContexts?.[0]?.content)).toBe(true)
     const recorded = agent.session.events.flatMap(event => event.type === 'user/message' ? [event.data] : [])
     expect(recorded).toContainEqual({
       content: [{ type: 'text', text: 'accepted-send' }],
@@ -828,7 +843,9 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
     })
     const request = JSON.stringify(adapter.requests[0]!.messages)
     expect(request).toContain('accepted-send')
+    expect(request).toContain('accepted-context')
     expect(request).not.toContain('caller-mutated-send')
+    expect(request).not.toContain('caller-mutated-context')
   })
 
   it('running steer() owns content and source before notification and delivery', async () => {
@@ -849,10 +866,12 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
     }))
     let notifiedContent: ContentBlock[] | undefined
     let notifiedSource: MessageSource | undefined
+    let notifiedContexts: HookContext[] | undefined
     ctx.on('agent/queued', (subject, acceptedContent, info) => {
       if (subject !== agent || !info.steering) return
       notifiedContent = acceptedContent
       notifiedSource = info.source
+      notifiedContexts = info.contexts
     })
 
     agent.send([{ type: 'text', text: 'start' }])
@@ -860,18 +879,28 @@ 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' }
-    agent.steer(content, { source })
+    const contexts: HookContext[] = [{
+      content: [{ type: 'text', text: 'accepted-steering-context' }],
+      source: { kind: 'plugin', plugin: 'steering-context' },
+    }]
+    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' }
     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(Object.isFrozen(notifiedContent)).toBe(true)
     expect(Object.isFrozen(notifiedContent?.[0])).toBe(true)
     expect(Object.isFrozen(notifiedSource)).toBe(true)
+    expect(Object.isFrozen(notifiedContexts)).toBe(true)
     const recorded = agent.session.events.flatMap(event => event.type === 'steering/message' ? [event.data] : [])
     expect(recorded).toContainEqual({
       turn: 1,
@@ -880,7 +909,15 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
     })
     const request = JSON.stringify(adapter.requests[1]!.messages)
     expect(request).toContain('accepted-steer')
+    expect(request).toContain('accepted-steering-context')
     expect(request).not.toContain('caller-mutated-steer')
+    expect(request).not.toContain('caller-mutated-steering-context')
+
+    const steeringIndex = agent.session.events.findIndex(event => event.type === 'steering/message')
+    const contextIndex = agent.session.events.findIndex(event => event.type === 'context/message'
+      && event.data.source.kind === 'plugin' && event.data.source.plugin === 'steering-context')
+    expect(steeringIndex).toBeGreaterThanOrEqual(0)
+    expect(contextIndex).toBe(steeringIndex + 1)
   })
 })
 

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

@@ -1,6 +1,10 @@
 import { describe, expect, it } from 'vitest'
 import { Inbox } from '../src/inbox.ts'
 
+function message(text: string) {
+  return { content: [{ type: 'text' as const, text }], source: { kind: 'user' as const }, contexts: [] }
+}
+
 function resolverPair() {
   let r!: () => void
   const p = new Promise<void>((resolve) => { r = resolve })
@@ -10,8 +14,8 @@ function resolverPair() {
 describe('Inbox', () => {
   it('dequeues one queued message at a time in FIFO order', () => {
     const inbox = new Inbox()
-    inbox.enqueue({ content: [{ type: 'text', text: 'first' }], source: { kind: 'user' } })
-    inbox.enqueue({ content: [{ type: 'text', text: 'second' }], source: { kind: 'user' } })
+    inbox.enqueue(message('first'))
+    inbox.enqueue(message('second'))
     expect(inbox.hasQueued).toBe(true)
 
     expect(inbox.dequeueQueued()?.content[0]).toMatchObject({ text: 'first' })
@@ -23,7 +27,7 @@ describe('Inbox', () => {
 
   it('pushes and drains steering messages separately from queued', () => {
     const inbox = new Inbox()
-    inbox.steer({ content: [{ type: 'text', text: 'steer' }], source: { kind: 'user' } })
+    inbox.steer(message('steer'))
     expect(inbox.hasQueued).toBe(false)
     expect(inbox.hasSteering).toBe(true)
 
@@ -34,7 +38,7 @@ describe('Inbox', () => {
 
   it('waitForQueued returns immediately when a queued message is already present', async () => {
     const inbox = new Inbox()
-    inbox.enqueue({ content: [{ type: 'text', text: 'ready' }], source: { kind: 'user' } })
+    inbox.enqueue(message('ready'))
 
     const started = Date.now()
     await inbox.waitForQueued(new Promise(() => {})) // never-resolving cancel
@@ -45,7 +49,7 @@ describe('Inbox', () => {
     const inbox = new Inbox()
     const waiter = inbox.waitForQueued(new Promise(() => {})) // never-resolving cancel
     // enqueue after starting the wait
-    setTimeout(() => { inbox.enqueue({ content: [{ type: 'text', text: 'wake' }], source: { kind: 'user' } }) }, 5)
+    setTimeout(() => { inbox.enqueue(message('wake')) }, 5)
     await waiter
   })
 
@@ -69,7 +73,7 @@ describe('Inbox', () => {
     r1()
     await p1
 
-    inbox.enqueue({ content: [{ type: 'text', text: 'hey' }], source: { kind: 'user' } })
+    inbox.enqueue(message('hey'))
   })
 
   it('clears wakeup in finally handler when enqueue resolves', async () => {
@@ -77,7 +81,7 @@ describe('Inbox', () => {
     void inbox.waitForQueued(new Promise(() => {})) // never-resolving cancel
     // The wakeup is set. Now trigger it via enqueue → wakeup() calls resolve,
     // promise resolves, finally clears wakeup because wakeup === resolve.
-    inbox.enqueue({ content: [{ type: 'text', text: 'wake' }], source: { kind: 'user' } })
+    inbox.enqueue(message('wake'))
     // No explicit await needed — enqueue is synchronous, and the microtask
     // (finally) runs. The key coverage hit is finally with wakeup === resolve.
   })
@@ -94,6 +98,6 @@ describe('Inbox', () => {
     await c1
 
     // The replacement remains registered and is resolved by enqueue.
-    inbox.enqueue({ content: [{ type: 'text', text: 'hey' }], source: { kind: 'user' } })
+    inbox.enqueue(message('hey'))
   })
 })

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

@@ -154,7 +154,9 @@ describe('agent/prompt-submit', () => {
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event: SessionEvent) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
 
-    send(agent, 'do something')
+    agent.send([{ type: 'text', text: 'do something' }], {
+      contexts: [{ content: [{ type: 'text', text: 'must be dropped' }], source: { kind: 'plugin', plugin: 'test' } }],
+    })
     await waitForIdle(ctx, agent)
 
     // the model was never called
@@ -164,6 +166,7 @@ describe('agent/prompt-submit', () => {
     expect(log.some(e => e.type === 'turn/start')).toBe(true)
     expect(log.some(e => e.type === 'turn/end')).toBe(true)
     expect(log.some(e => e.type === 'user/message')).toBe(false)
+    expect(log.some(e => e.type === 'context/message')).toBe(false)
     expect(log.some(e => e.type === 'step/start')).toBe(false)
     // the veto is recorded durably as a prompt/blocked in the open turn
     const blocked = log.find(e => e.type === 'prompt/blocked')

packages/core/agent/README.md

@@ -46,7 +46,7 @@ The lifecycle edges have two important local caveats. `agent/created` runs after
 
 Most interception points are cooperative waterfalls returning seam-specific decisions. `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 reason, then clears queues and aborts; notification failures are contained and cannot veto the stop. The full rationale for scoped dispatch and terminal settlement is in 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).
 
-`PromptDecision.additionalContexts` is an array so every injected context keeps its own source and metadata. 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 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.
 
 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).
 
@@ -54,8 +54,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 and resolved source 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 (`agent/prompt-submit` still rewrites by returning replacement content). The [one-send-one-turn Agent Note](../../../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md) owns the rationale.
-- `agent.steer(content, options?)` — submit steering while the agent is `running`. An open turn records it at the next steering checkpoint before a request or continuation decision; 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. The method uses the same synchronous snapshot-and-validation boundary as `send` and delegates to `send` when idle
+- `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.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(reason?)` — cancel ALL pending work: an effective call emits `agent/cancel-requested` before it clears the queued + steering FIFOs, aborts the in-flight step, and drops a turn about to start (the pre-step window). Observers may synchronize their own state but cannot veto cancellation. A UI/ACP `session/cancel` maps to this. The single public stop primitive. Idle with nothing pending → a safe no-op with no notification.
 - `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

@@ -31,6 +31,12 @@ export interface AgentOptions {
  */
 export interface SendOptions {
   source?: MessageSource
+  /**
+   * Model-facing contexts captured with this inbox item. A queued prompt exposes
+   * them through the default `agent/prompt-submit` allow decision, while steering
+   * records them directly at its next checkpoint.
+   */
+  contexts?: HookContext[]
 }
 
 /** Options specific to durable synthetic context injection. */
@@ -47,7 +53,7 @@ export interface InjectOptions extends SendOptions {
  */
 export type AgentStatus = 'idle' | 'running' | 'disposed'
 
-/** Model-facing context injected by a listener; `source` prevents plugin text from being labeled as user input. */
+/** Model-facing context injected by a listener or atomically attached to one inbox message. */
 export interface HookContext {
   content: ContentBlock[]
   source: MessageSource
@@ -59,7 +65,9 @@ export interface HookContext {
  * 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.
+ * 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[] }
@@ -100,7 +108,8 @@ export interface Agent {
    * Queue one detached, frozen lossless-JSON item. If claimed, it is the sole
    * ordinary message in its FIFO-ordered turn; the next claimed item waits for
    * that turn's checkpoint.
-   * Invalid input throws synchronously before notification or enqueue.
+   * Attached contexts share the same snapshot and ownership boundary. Invalid
+   * input throws synchronously before notification or enqueue.
    */
   send(content: ContentBlock[], options?: SendOptions): void
 
@@ -174,11 +183,11 @@ declare module 'cordis' {
      * already been applied, so these are the exact values retained for the log.
      * @param agent - the agent whose inbox received the message.
      * @param content - the accepted content blocks retained by the inbox.
-     * @param info - the accepted source plus whether it entered as steering.
+     * @param info - the accepted source, contexts, and whether it entered as steering.
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode emit
      */
-    'agent/queued'(this: Scoped<Agent>, agent: Agent, content: ContentBlock[], info: { source: MessageSource; steering: boolean }): void
+    'agent/queued'(this: Scoped<Agent>, agent: Agent, content: ContentBlock[], info: { source: MessageSource; contexts: HookContext[]; steering: boolean }): void
     /**
      * Effective broad cancellation was requested, before queued/steering work
      * is cleared or the active step is aborted. This observe-only notification
@@ -220,7 +229,10 @@ declare module 'cordis' {
     'agent/pre-step'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, signal: AbortSignal): Promise<void> | void
     /**
      * Allow, rewrite, or block one claimed prompt before it becomes a user
-     * message. Call `next()` for the unchanged default.
+     * message. Call `next()` for the unchanged default. A listener wrapping a
+     * downstream `allow` must preserve its `content` and `additionalContexts`
+     * unless it intentionally replaces them. Steering messages do not dispatch
+     * this event; they join an open turn at a steering checkpoint.
      * @param agent - the agent whose turn claimed the message.
      * @param content - the claimed message's blocks, as queued.
      * @param source - the message's resolved source.