Merge remote-tracking branch 'origin/master' into codex/project-instruction-files

# Conflicts:
#	AGENTS.md
#	docs/config-catalog.md
#	docs/cordis-catalog/events.md
#	docs/cordis-catalog/services.md
#	docs/core-data-structures/core.md
#	docs/event-producer-consumer.md
#	docs/persistence-catalog.md
#	docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md
#	docs/rfc/implemented/feature/2026-06-15-code-mode.md
#	docs/rfc/implemented/feature/2026-06-30-hook-bridges.md
#	docs/rfc/implemented/feature/2026-06-30-interception-seams.md
#	docs/rfc/implemented/feature/2026-07-08-repeat-tool-guard.md
#	docs/rfc/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md
#	examples/AGENTS.md
#	examples/acp-agent/cordis.yml
#	examples/acp-agent/tests/acp.snapshot.ts
#	examples/echo-agent/cordis.yml
#	examples/sandbox-acp-agent/cordis.yml
#	packages/cordis/tool-cordis/src/api-catalog.ts
#	packages/core/agent-core/README.md
#	packages/core/agent-core/src/index.ts
#	packages/core/agent-loop/README.md
#	packages/core/agent-loop/src/loop.ts
#	packages/core/agent-loop/tests/interception.spec.ts
#	packages/core/agent/src/types.ts
#	packages/core/tools/README.md
#	packages/core/tools/src/code-mode.ts
#	packages/core/tools/src/index.ts
#	packages/fs/fs-local/src/index.ts
#	packages/fs/fs/README.md
#	packages/fs/fs/src/index.ts
#	packages/guard/repeat-tool-guard/README.md
#	packages/guard/repeat-tool-guard/src/index.ts
#	packages/hooks/hooks-claude/src/index.ts
#	packages/hooks/hooks-codex/src/index.ts
#	packages/ui/acp-agent/src/index.ts

packages/core/agent/src/dispatch.ts

@@ -1,14 +1,7 @@
 /**
- * Fused scope-carrier dispatch for agent-subject operations, plus the assembly
- * context builder. The sanctioned ordinary spelling is
- * `agentEvents(ctx, agent).waterfall('agent/request', …)`: it builds the scope
- * carrier ({@link scopeTarget} keyed by the agent) AND injects the subject as
- * the first argument in one move, so a site cannot name a different subject.
- * The registry lifecycle pair is the deliberate exception: `enter()` captures
- * one stable carrier before commit and `announce()`/detach dispatch through it
- * directly, so both lifecycle edges use the same routing identity. The dev
- * scoped-dispatch invariant checks both shapes.
- *
+ * Agent-scoped dispatch and prompt assembly helpers. Ordinary events use the
+ * fused dispatcher so subject and scope key cannot diverge; registry lifecycle
+ * code instead captures one stable carrier for both edges.
  * @module @deepseek-ai/dsh-agent/dispatch
  */
 
@@ -74,9 +67,7 @@ export interface AgentEventDispatch {
 }
 
 /**
- * Build the fused dispatcher for `agent`'s events (see the module doc). Cheap
- * (one carrier + one small object) — dispatch sites create it per run/turn
- * rather than caching it on the agent.
+ * Build a dispatcher that couples the agent subject to its scope carrier.
  * @param ctx - the context to dispatch through (any context of the app).
  * @param agent - the subject agent; also the scope-carrier key.
  * @returns the fused dispatcher.
@@ -121,11 +112,8 @@ export function agentEvents(ctx: Context, agent: Agent): AgentEventDispatch {
 }
 
 /**
- * The assembly context for one agent's prompt: the typed `agent` DX field and
- * the `scope` layer selector, set together (setting `agent` without `scope`
- * silently drops the agent's scoped sections/tools from the assembly — the
- * dev invariants flag it). THE way the loop (and any custom driver) builds
- * its per-step `ctx.systemPrompt.assemble(…)` input.
+ * Build the prompt assembly context with agent and scope set together, so
+ * agent-scoped prompt and tool contributions cannot be silently omitted.
  * @param agent - the agent the assembly is for.
  * @returns the context to pass to `assemble()`.
  */

packages/core/agent/src/index.ts

@@ -31,59 +31,23 @@ declare module 'cordis' {
   }
 }
 
-/**
- * Options for programmatically creating an agent through the registry factory
- * ({@link AgentRegistry.create}). The caller supplies the live `sessionId`
- * (e.g. an ACP-generated id) and optional session metadata (the validated
- * `cwd`, fork lineage); the factory creates the session, the agent, and wires
- * them together.
- */
+/** Options for creating an agent and its caller-named session. */
 export interface CreateAgentOptions {
   /** The agent's id (the registry handle). */
   readonly agentId: AgentId
   /** The live session's id (NOT derived from agentId). */
   readonly sessionId: SessionId
-  /**
-   * Session creation metadata: validated absolute `cwd`, `parentSession`
-   * fork lineage, and the `seedLength` seed boundary. Mirrors the
-   * `cwd`/`parentSession`/`seedLength` fields of
-   * {@link CreateSessionOptions.meta} in dsh-session (the internal-only
-   * `createdAt`, used when reconstructing a persisted session, is deliberately
-   * excluded — a factory caller never sets it). This is durable session data,
-   * so the session boundary validates and snapshots it before asynchronous
-   * setup begins.
-   */
+  /** Durable session metadata, validated and detached before setup. */
   readonly meta?: { readonly cwd?: string; readonly parentSession?: SessionId; readonly seedLength?: number }
-  /**
-   * Seed events to reconstruct the child session's log from (the fork lineage
-   * primitive). When present, the factory creates the session with this event
-   * prefix so `deriveMessages()`/`lastTurnNumber` continue from it — used by the
-   * in-process FORK subagent backend to seed a child with a balanced
-   * completed-turn prefix of the parent's log. The prefix MUST be contiguous
-   * from seq 0, carry only lossless-JSON data, and be balanced (no open
-   * turn/step, no dangling tool-call), or the session constructor (and the
-   * dev-mode invariants replay) reject it. The factory passes the raw seed to
-   * the session's durable validator/snapshot boundary. Absent for a fresh
-   * (spawn) child.
-   */
+  /** Balanced contiguous event prefix for a forked session. */
   readonly seed?: readonly SessionEvent[]
   /** Per-agent options (model, …). */
   readonly agentOptions?: AgentOptions
   /** Optional creation-only cancellation signal; detached before the returned handle becomes visible. */
   readonly signal?: AbortSignal
   /**
-   * Creation-time composition of the agent's scoped world. The factory awaits
-   * setup after minting `agentCtx` but BEFORE inserting or announcing either
-   * the session or agent, so observers can never see a partially configured
-   * world. Everything registered through `agentCtx` (scoped tools, prompt
-   * sections/variables, `restrict()`, listeners, awaited child plugins) exists
-   * before `session/created`, `agent/created`, `agent/session-start`, and the
-   * first prompt assembly. A throw/rejection or owner disposal rolls the scope
-   * back without publishing either id.
-   *
-   * **Setup composes, it never drives**: the callback is trusted same-process
-   * code and receives the full scoped context, so this is a contract rather
-   * than a runtime restriction. Drive the agent only after creation resolves.
+   * Compose the unpublished scoped context before lifecycle announcements.
+   * Failure rolls back without publishing either id; setup must not drive the agent.
    */
   readonly setup?: (agentCtx: Context) => Promise<void> | void
 }
@@ -101,35 +65,15 @@ export interface ResumeAgentOptions {
   readonly agentOptions?: AgentOptions
   /** Optional creation-only cancellation signal for persistence load/setup; detached before return. */
   readonly signal?: AbortSignal
-  /**
-   * Resume-time composition of the agent's fresh scoped world. Persistence is
-   * loaded first; the factory then mints `agentCtx` and awaits setup while the
-   * reconstructed session and agent remain unpublished. The callback has the
-   * same trusted composition-only contract as
-   * {@link CreateAgentOptions.setup}: all registrations exist before either
-   * creation announcement, and rejection or owner disposal rolls the
-   * transaction back without publishing either id.
-   */
+  /** Compose after persistence load under the same unpublished rollback contract as create. */
   readonly setup?: (agentCtx: Context) => Promise<void> | void
 }
 
 /**
- * An owned agent plus its disposer, returned by {@link AgentRegistry.create} /
- * {@link AgentRegistry.resume}. The disposer is a CAPABILITY: among consumers,
- * only the holder can tear this agent down. The registered factory provider is
- * also a structural owner because the scoped agent depends on that provider's
- * service surface; provider unload stops and drains every live handle it made.
- * `dispose()` stops the loop, awaits its exit and every outstanding
- * idle-injection flush (quiescence — NOT just the `disposed`
- * status flip), unregisters the agent, removes its session from the store, and
- * finally unwinds its scoped world. This order captures every agent-started
- * `session/flush` before the session is detached and keeps scoped listeners
- * alive through those checkpoints.
- *
- * `ctx.agents.get(id)` still returns a bare {@link Agent} — the handle is
- * exposed only to the consumer owner that created it; the structural provider
- * reaches the same teardown internally. Config-created agents (the loop's own
- * startup) are owned by the loop fiber and never need a handle.
+ * Holder-owned agent capability. Disposal stops and drains the loop and idle
+ * flushes before unregistering the agent, detaching its session, and unwinding
+ * its scoped context. Provider unload reaches the same quiescence boundary;
+ * registry observers receive only the bare {@link Agent}.
  */
 export interface AgentHandle {
   agent: Agent
@@ -144,30 +88,16 @@ export interface AgentHandle {
  */
 export interface AgentFactory {
   /**
-   * Create a new agent on a caller-supplied session id. Async because creation
-   * awaits unpublished setup, inserts both session and agent, emits their
-   * creation notifications in order, emits `agent/session-start`, and only
-   * then starts the loop. The sequence is
-   * rollback-covered, but notifications delivered before a later listener
-   * failure remain observable; every agent or session creation announcement
-   * that began is paired by `agent/disposed` or `session/disposed` during
-   * rollback. The owner disposes the resolved handle to stop/drain,
-   * unregister, remove the session, and unwind the scope.
-   * The registry passes a context carrying the `create()` caller's fiber and
-   * scope as `ownerCtx`. The implementation attaches the unpublished
-   * transaction and resulting lifecycle to that owner; it must not infer
-   * ownership from the factory object's registration context.
+   * Create and compose under caller ownership, publish and announce session then
+   * agent, emit session-start, and start the driver. Rollback pairs any creation
+   * announcement that began.
    * @param ownerCtx - caller-bound context that owns the transaction and live handle.
    * @param options - agent/session identity, configuration, and optional setup.
    * @returns the owned handle after setup, both announcements, and loop start complete.
    */
   createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>
   /**
-   * Load a persisted session and resume an agent on it. Async because it awaits
-   * both `ctx.sessionPersistence.load` and the optional unpublished setup
-   * transaction; must be called after that service exists (consumers inject
-   * `sessionPersistence`). Publication follows the same ordered boundary as
-   * {@link createAgent}.
+   * Load, compose, publish, announce, and resume an agent under caller ownership.
    * @param ownerCtx - caller-bound context that owns load, setup, and the live handle.
    * @param options - persisted identity, configuration, and optional setup.
    * @returns the owned handle after setup, both announcements, and loop start complete.
@@ -202,46 +132,32 @@ interface FactorySlot {
  */
 export class AgentRegistry extends Service {
   private store = new Map<AgentId, AgentEntry>()
+  // TODO(agent-entry-mirror): derive exact-object checks from store.get(agent.id)
+  // plus entry.agent identity; this WeakMap mirrors the authoritative id map.
   private entries = new WeakMap<Agent, AgentEntry>()
   private factory: FactorySlot | undefined
 
   constructor(ctx: Context) {
     super(ctx, 'agents')
-    // The `ctx.agent` DX accessor: default `undefined` on every context, so a
-    // plain plugin context reads cleanly instead of hitting the Cordis
-    // unknown-property throw. Each Agent.ctx shadows it with an own property
-    // (own properties resolve before the context proxy is consulted), so the
-    // accessor body never needs to resolve a scope itself. Effect-scoped:
-    // unwinds with this service's fiber.
+    // Agent contexts shadow this plain-context default with an own property.
     ctx.accessor('agent', { get: () => undefined })
   }
 
   /**
-   * Register the agent-creation factory (the loop calls this on construction,
-   * effect-scoped). A traced Cordis service is canonicalized to its concrete
-   * target; each create/resume call is then traced through that caller's
-   * context so ownership follows the caller without stacking proxy layers.
-   * Throws if a factory is already registered. Returns the disposer; on
-   * dispose the factory slot is cleared.
+   * Register the effect-scoped creation factory, rejecting a duplicate. Service
+   * factories are retraced through each create/resume caller for ownership.
    * @param factory - the loop-owned factory {@link create}/{@link resume} delegate to.
-   * @returns the disposer that clears the factory slot. The exact
-   *   Cordis effect disposer (single-shot): composite (generator) effects may
-   *   yield it directly — exact identity nests the teardown in order.
+   * @returns the exact Cordis effect disposer.
    */
   setFactory(factory: AgentFactory): () => void {
     const dispose = this.ctx.effect(() => {
       if (this.factory !== undefined) throw new Error('an agent factory is already registered')
-      // Avoid stacking two Cordis shadow layers when a caller passes a Service
-      // already read through a context. Calls are re-traced through their
-      // actual owner context below.
+      // Store the concrete service; calls are retraced through their owner.
       const target = (factory as AgentFactory & { [symbols.original]?: AgentFactory })[symbols.original] ?? factory
       this.factory = { target }
       return () => { this.factory = undefined }
     }, 'agents.setFactory()')
-    // The exact cordis effect disposer (the agents.register() convention): a
-    // caller's composite effect can yield it for in-order teardown; the
-    // loop's constructor effect returns it directly, identity-nesting the
-    // registration under that effect.
+    // Return the exact disposer so composite effects preserve teardown order.
     // eslint-disable-next-line @typescript-eslint/no-misused-promises -- synchronous cleanup; direct return preserves disposer identity
     return dispose
   }
@@ -253,20 +169,14 @@ export class AgentRegistry extends Service {
   }
 
   /**
-   * Create and publish a new agent through the registered factory.
-   * Distinct from {@link register} (which records an already-constructed
-   * agent): this constructs the agent and its session. Rejects if no factory is
-   * registered or creation/setup fails. The resolved {@link AgentHandle} lets
-   * the owner tear down exactly this agent.
+   * Create and publish an owned agent and session through the active factory.
+   * Rejects if no factory is registered or creation, setup, or publication fails.
    * @param options - agent id, session id/seed/metadata, and agent options.
    * @returns the handle after setup, rollback-covered publication, and loop start complete.
    */
   async create(options: CreateAgentOptions): Promise<AgentHandle> {
     const ownerCtx = this.ctx
-    // Re-trace a Service-backed factory through the accessing context
-    // explicitly. This preserves AgentLoop's dependency origin while binding
-    // its effects to ownerCtx; plain factories receive ownerCtx as an explicit
-    // capability and need no Cordis tracker magic.
+    // Bind service effects to this caller while preserving factory dependencies.
     const { target } = this.requireFactory()
     const receiver = getTraceable(ownerCtx, target)
     // eslint-disable-next-line @typescript-eslint/unbound-method -- Reflect.apply intentionally supplies the caller-traced receiver
@@ -289,22 +199,10 @@ export class AgentRegistry extends Service {
   }
 
   /**
-   * Register a live agent. Throws if an agent with the same id is already
-   * registered. Emits `agent/created` on registration and `agent/disposed`
-   * when the calling fiber is disposed — both with the agent's scope carrier
-   * (`scopeTarget(agent, agent)`): the subject is the agent in hand, so the
-   * emits are scope-filtered regardless of which context invoked `register`
-   * (calling through `agent.ctx` scopes EFFECTS; dispatch scoping always
-   * requires passing the carrier). Returns the disposer.
+   * Register a live agent in the calling effect scope, with scope-filtered
+   * creation and disposal events. Duplicate ids throw.
    * @param agent - the already-constructed agent to record in the store.
-   * @returns the EXACT Cordis effect disposer (single-shot; a repeat call
-   *   returns undefined without awaiting an in-flight teardown). Exact
-   *   identity is load-bearing: a composite (generator) effect that owns a
-   *   teardown ORDER — the agent factory's lifecycle chain — must yield THIS
-   *   function so Cordis nests the unregistration at that yield position;
-   *   yielding a wrapper would leave it disposing as a concurrent sibling on
-   *   owner unload, unregistering the agent (and emitting `agent/disposed`)
-   *   while its final turn is still draining.
+   * @returns the exact Cordis effect disposer for nested teardown ordering.
    */
   register(agent: Agent): () => void {
     const dispose = this.ctx.effect(function* (this: AgentRegistry) {
@@ -316,22 +214,15 @@ export class AgentRegistry extends Service {
   }
 
   /**
-   * Insert an already-constructed agent without announcing it. This is the
-   * advanced ordered-lifecycle primitive used by the async agent factory: it
-   * first completes setup while the agent is unpublished, then assigns the
-   * returned detach closure into its pre-installed composite teardown before
-   * calling {@link announce}. Ordinary callers use {@link register}.
+   * Insert an unpublished agent for an ordered factory transaction.
    * @param agent - the prepared, unpublished agent.
-   * @returns an idempotent closure that removes this exact entry and emits
-   *   `agent/disposed` with listener failures contained. When called from a
-   *   synchronous `agent/created` listener, removal and disposal wait until
-   *   that creation dispatch unwinds.
+   * @returns an idempotent closure that removes this exact entry and emits the
+   * paired disposal edge; detachment during creation dispatch is deferred.
    */
   enter(agent: Agent): () => void {
     const id = agent.id
     const carrier = scopeTarget(agent, agent)
-    // This is the authoritative collision boundary. Concurrent create/resume
-    // operations may both prepare, but only one exact entry can publish.
+    // Prepared transactions arbitrate identity at this publication boundary.
     if (this.entries.has(agent) || this.store.has(id)) throw new Error(`agent "${id}" is already registered`)
     const entry: AgentEntry = {
       id,
@@ -347,11 +238,7 @@ export class AgentRegistry extends Service {
     const detach = (): void => {
       if (!entered) return
       entered = false
-      // Every callback reached by this creation dispatch must observe the same
-      // live entry, and disposal must follow creation. A listener may own
-      // the advanced detach capability, so make that ordering structural:
-      // visibility and the paired disposal are deferred until announce()'s
-      // synchronous dispatch has unwound.
+      // Creation listeners observe one stable entry before paired disposal.
       if (entry.announcing) {
         entry.detachRequested = true
         return

packages/core/agent/src/types.ts

@@ -1,46 +1,6 @@
 /**
- * Agent interface and event taxonomy. Every plugin programs against the
- * `Agent` handle defined here; the concrete implementation lives in
- * `@deepseek-ai/dsh-agent-loop`.
- *
- * Merge-extensible: `AgentOptions` supports declaration merging for
- * plugin-specific creation options.
- *
- * ## Event-domain semantics (the boundary rule)
- *
- * The harness has three event domains, each with one job:
- *
- * - **`session/*`** (`@deepseek-ai/dsh-session`) — the DURABLE, replayable FACT
- *   log. Owns `SessionEventMap`; every entry is JSON-only (no live objects).
- *   One `session/event` emit per append, plus the `session/flush` parallel
- *   durability checkpoint. Answers "what happened, durably/replayably." A
- *   consumer that wants the live transcript subscribes here.
- * - **`agent/*`** (this module) — the LIVE runtime surface. Always carries the
- *   live `Agent`. Two shapes: INTERCEPTION seams (the `agent/prompt-submit`/
- *   `agent/request`/`agent/session-prefix`/`agent/step-result`/
- *   `agent/turn-continuation` waterfalls and the serial `agent/pre-step` /
- *   `agent/turn-stop` checkpoints) that mutate/veto, and TRANSIENT emits
- *   (`agent/status`, `agent/error`, `agent/created`/
- *   `agent/disposed`, `agent/queued`, `agent/session-start`)
- *   that notify with the `Agent` in hand. Turn/step boundaries are NOT here —
- *   they are durable `session/event` records. Answers "right now, with the agent
- *   object — intercept or observe."
- * - **`tools/*`** (`@deepseek-ai/dsh-tools`) — the tool registry + execution.
- *
- * **The rule:** a durable, replayable fact is a SessionEvent; a live
- * interception or a transient/live-object signal is an `agent`/`tools` Cordis
- * event. A turn/step boundary is a durable fact: it lives in the session log
- * and is read off the `session/event` feed — it is NOT mirrored as an `agent/*`
- * emit. A consumer that needs the `Agent` handle (or its short id) at a boundary
- * keeps a session-id→agent map from `agent/created`/`agent/disposed`.
- * See `docs/rfc/implemented/architecture/2026-06-11-microkernel-event-taxonomy.md`
- * and `docs/rfc/implemented/simplification/2026-06-20-remove-agent-boundary-mirror-events.md`.
- *
- * The interception waterfalls here (`agent/prompt-submit`, `agent/request`,
- * `agent/step-result`, `agent/turn-continuation`) each return a typed Decision;
- * the terminal serial `agent/turn-stop` returns the stop-only subset. The
- * convention is pinned by
- * `docs/rfc/implemented/feature/2026-06-30-interception-seams.md`.
+ * Public agent types and live-runtime events. Durable transcript facts and
+ * turn/step boundaries remain `@deepseek-ai/dsh-session` events.
  *
  * @module @deepseek-ai/dsh-agent/types
  */
@@ -66,38 +26,18 @@ import type { ContextEnvelope, JsonValue, Session } from '@deepseek-ai/dsh-sessi
 
 declare module '@deepseek-ai/dsh-system-prompt' {
   interface AssembleContext {
-    /**
-     * The agent this assembly is for. The agent loop passes it on every
-     * per-step assembly (via its `assembleContextFor(agent)` helper, which
-     * also sets the `scope` field to the same agent — the layer selector
-     * `dsh-system-prompt` reads); variable providers project per-agent facts
-     * from it (`options.model` → `{{model}}`, `session.header.cwd` →
-     * `{{cwd}}`). Optional because a bare `assemble()` (tests, diagnostics)
-     * has no agent — providers must tolerate its absence. Never set `agent`
-     * without `scope`: the assembly would silently miss the agent's scoped
-     * sections/tools (the dev invariants flag it).
-     */
+    /** Agent for this assembly; absent on diagnostics. When present, `scope` must identify the same agent. */
     agent?: Agent
   }
 }
 
-/**
- * Options an agent is created with. The persona is NOT here: the
- * dsh-system-prompt config supplies the global default, and a scoped
- * `deployment:persona` section may override it for one agent.
- * Merge-extensible: plugins declare extra fields via declaration merging.
- */
+/** Merge-extensible agent creation options. Persona belongs to system-prompt sections. */
 export interface AgentOptions {
   /** Model name (must have a registered adapter at call time). */
   model?: string
 }
 
-/**
- * Options for {@link Agent.send}/{@link Agent.steer}/{@link Agent.inject}. An
- * absent `source` resolves to `{ kind: 'user' }`, so a plugin supplying content
- * must label itself here or its message is recorded as a user prompt (see
- * {@link HookContext} on why that label is load-bearing).
- */
+/** Message options; an omitted source resolves to `{ kind: 'user' }`, so plugins must label their own content. */
 export interface SendOptions {
   source?: MessageSource
 }
@@ -118,17 +58,7 @@ export interface InjectOptions extends SendOptions {
  */
 export type AgentStatus = 'idle' | 'running' | 'disposed'
 
-/**
- * Model-facing context an interception listener wants the agent to SEE on the
- * next request — the canonical shape behind every "inject extra context"
- * decision ({@link PromptDecision}, {@link PostToolDecision}). It is
- * `agent.inject()`ed as a
- * `context/message`, so it carries a REQUIRED {@link MessageSource}: `inject()`
- * defaults a missing source to `{kind:'user'}`, which would MISLABEL plugin
- * context as a user prompt and corrupt derived history. A bridge sets
- * `{kind:'plugin', plugin:'…'}`; a native plugin names itself. Required, not
- * optional — the label is load-bearing, never defaulted here.
- */
+/** Model-facing context injected by a listener; `source` prevents plugin text from being labeled as user input. */
 export interface HookContext {
   content: ContentBlock[]
   source: MessageSource
@@ -139,39 +69,15 @@ export interface HookContext {
 }
 
 /**
- * The decision an {@link Agent} `agent/prompt-submit` waterfall listener returns
- * for ONE drained queued message, before it becomes a `user/message`. Maps onto
- * the Claude Code `UserPromptSubmit` hook's allow/block + `additionalContext`.
- *
- * - `allow` proceeds with the prompt; optional `content` REPLACES the prompt
- *   bytes (a rewrite), and optional `additionalContexts` are each `inject()`ed
- *   as separate `context/message` events the next request also sees.
- * - `block` drops the prompt (it never becomes a `user/message`); `reason` is
- *   the durable record of why. The loop appends a `prompt/blocked` session event
- *   (carrying the original content, source, and `reason`) in place of the
- *   dropped `user/message`, so the veto survives replay even in a MIXED batch
- *   where a sibling prompt is allowed. A batch whose EVERY prompt is blocked
- *   additionally opens a zero-step turn that ends with {@link TurnEndReason}
- *   `rejected` (so the boundary stays balanced and a UI can render "blocked by
- *   hook").
+ * Prompt interception result. `allow.content` replaces the prompt and each
+ * `additionalContexts` entry becomes a separate context message. `block` records a
+ * durable `prompt/blocked`; an all-blocked batch ends a zero-step rejected turn.
  */
 export type PromptDecision =
   | { kind: 'allow'; content?: ContentBlock[]; additionalContexts?: HookContext[] }
   | { kind: 'block'; reason: string }
 
-/**
- * The decision an {@link Agent} `agent/turn-continuation` waterfall listener
- * returns. The loop computes the default (`continue` when the step had tool
- * calls or steering was injected, else `stop`); listeners override it to
- * force-continue (`/goal`, `/loop`) or force-stop (budget guards).
- *
- * A `continue` may carry a `reason`: model-facing content recorded as next-STEP
- * steering within the SAME turn (the loop enqueues it through the steering
- * channel, so the continued turn's next step sees it). Steering is not a
- * `context/message`, so raw context envelopes and durable context metadata are
- * deliberately absent. This is the typed twin of the existing "steer from a
- * step/end listener" `/goal` pattern.
- */
+/** Turn continuation override; a continue reason is recorded as next-step steering in the same turn. */
 export type ContinuationDecision =
   | { action: 'stop' }
   | { action: 'continue'; reason?: { content: ContentBlock[]; source: MessageSource } }
@@ -183,47 +89,21 @@ export type ContinuationDecision =
  */
 export type ContinuationStop = Extract<ContinuationDecision, { action: 'stop' }>
 
-/**
- * Why an agent's session lifecycle began, carried by `agent/session-start`. A
- * bridge keys its SessionStart hook's matcher on this (Claude Code's
- * `startup`/`resume`/`clear`/`compact` source set). `startup` = a fresh create
- * (including a seeded/forked create — a seed is NOT a resume); `resume` = a
- * persisted session reloaded via `ctx.agents.resume()`. `clear`/`compact` are
- * driven by those subsystems (compact = `TODO(compaction)`).
- */
+/** Why a session lifecycle began; seeded creates are `startup`, while persisted loads are `resume`. */
 export type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
 
-/**
- * The agent handle — the surface every plugin (UI, hooks, orchestrators)
- * programs against. The concrete implementation lives in
- * `@deepseek-ai/dsh-agent-loop` (class `ReactLoopAgent`); nothing outside the loop
- * package should depend on the implementation.
- */
+/** Public agent handle; the concrete driver belongs to `@deepseek-ai/dsh-agent-loop`. */
 export interface Agent {
   readonly id: AgentId
   readonly options: AgentOptions
   readonly session: Session
   readonly status: AgentStatus
-  /**
-   * The agent's scope context (`@deepseek-ai/dsh-scope`, key = this agent).
-   * Registrations through it — tools, prompt sections/variables, event
-   * listeners, restrictions — are visible to THIS agent only and unwind when
-   * the agent is disposed; `agent.ctx.on('agent/…')` listeners fire only for
-   * this agent's dispatches (zero self-filtering). Service resolution through
-   * it flows through the loop plugin's dependency surface — handing out
-   * `agent.ctx` hands out that capability. Live for exactly the agent's
-   * lifetime: registrations after disposal throw Cordis's INACTIVE_EFFECT.
-   */
+  /** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */
   readonly ctx: Context
 
   /**
-   * Queue a user message. Starts a turn when idle; otherwise waits for the next
-   * turn. Content and the resolved source are accepted as one detached,
-   * deeply-frozen lossless-JSON record before notification or enqueue, so
-   * caller or `agent/queued` listener in-place mutation cannot change later
-   * log/model input. Throws synchronously when either value is not losslessly
-   * JSON-serializable; `agent/prompt-submit` may still return an explicit
-   * replacement.
+   * Queue detached, frozen lossless-JSON input; starts a turn when idle.
+   * Invalid input throws synchronously before notification or enqueue.
    */
   send(content: ContentBlock[], options?: SendOptions): void
 
@@ -235,319 +115,137 @@ export interface Agent {
   steer(content: ContentBlock[], options?: SendOptions): void
 
   /**
-   * Inject in-session context (file-change notices, skill content, cron
-   * notifications, …): appends a `context/message` session event the next model
-   * request sees at its chronological position, rendered as synthetic context
-   * rather than a user prompt. The default uses the canonical context tag;
-   * `options.envelope: 'raw'` preserves caller-owned framing. Does not run the
-   * model.
-   *
-   * Turn-enclosure (the turn-enclosure RFC): an inject while a turn is open joins that turn;
-   * an inject while idle wraps its `context/message` in a one-shot `injection`
-   * turn (`turn/start` → `context/message` → `turn/end`) and checkpoints it for
-   * durability, so every event stays inside a turn and a persistence backend
-   * never loses a between-turn notice. The idle checkpoint is fire-and-forget
-   * from this synchronous method, but lifecycle disposal awaits it before
-   * unregistering the agent or detaching its session. A failing flush is
-   * reported via `agent/error` (step `0`) and the logger, never thrown into the
-   * caller.
-   *
-   * Live-adapter review has validated the canonical tagged-envelope rendering
-   * against current DeepSeek behavior; provider-specific mismatches belong in
-   * that adapter, not in the canonical session vocabulary.
+   * Append model-facing context without running the model. Idle injection uses
+   * a one-shot turn and durability checkpoint, while injection during an open
+   * turn joins it at the current log position. Disposal awaits idle checkpoints;
+   * flush failures are reported through `agent/error`, not thrown to the caller.
    */
   inject(content: ContentBlock[], options?: InjectOptions): void
 
   /**
-   * Cancel ALL pending work for the agent. `cancel()`:
-   *
-   * - clears the queued FIFO (un-started prompts never run) and the steering
-   *   FIFO (steering for the cancelled turn is dropped, not re-enqueued);
-   * - aborts the in-flight step if one is running (the turn ends `aborted`);
-   * - drops a turn that is about to start (a `cancel()` landing in the
-   *   pre-step window — after a `send()` queued but before the loop flips to
-   *   `running`, or after `running` is emitted but before the first step) so
-   *   that queued prompt does not run and cannot be batched into the cancelled
-   *   turn.
-   *
-   * After `cancel()`, `whenIdle()` resolves on the post-cancel quiescent state.
-   * `cancel()` on an idle agent with nothing queued or running is a safe no-op
-   * — it does NOT arm anything that would drop a later legitimate prompt.
+   * Clear queued and steering work, including work waiting to start, and abort
+   * the active step. The supplied reason is preserved across pre-step and active
+   * cancellation windows, and `whenIdle()` resolves after cancellation reaches
+   * quiescence. Idle cancellation is a no-op and does not arm a later cancel.
    */
   cancel(reason?: string): void
 
-  /**
-   * Resolve once the agent has reached quiescence after settling out of
-   * `running`, or immediately if it is already idle with no queued work. A
-   * non-owner's quiescence-observation hook: a consumer that does NOT own the
-   * agent's lifecycle awaits this to proceed only after queued/running work has
-   * fully stopped, rather than returning while the driver is still streaming or
-   * about to start a queued turn — without itself tearing the agent down. (A
-   * lifecycle OWNER does not need it: `AgentHandle.dispose()` already awaits the
-   * loop-exit promise directly as part of stopping and unregistering. So this is
-   * for a non-owning observer — e.g. a test awaiting a turn to settle, or a
-   * monitor — that wants the settle signal but must not dispose the agent.)
-   *
-   * "Quiescence", not merely "status changed": a disposed agent emits
-   * `agent/status('disposed')` from inside its disposer, BEFORE the driver loop
-   * has unwound — so `whenIdle()` resolving on `disposed` must wait for the loop
-   * to actually exit (the implementation chains the loop-exit promise), not just
-   * observe the status flip. A mid-step disposal that never reaches `idle` still
-   * unblocks the await this way.
-   */
+  /** Resolve at idle quiescence; disposal waits for driver exit rather than only the status transition. */
   whenIdle(): Promise<void>
 
-  // Subagent delegation is realized on top of this interface by the
-  // `@deepseek-ai/dsh-subagent` seam, not by a method here: a backend creates
-  // the child through `ctx.agents.create` (fork seeds the child Session with a
-  // balanced prefix of the parent's log via `CreateAgentOptions.seed`; spawn
-  // starts fresh) and drives it as an ordinary Agent handle, so steer() and
-  // event subscription work uniformly. See docs/core-data-structures/subagent.md.
 }
 
 declare module 'cordis' {
   interface Events {
     // ---- lifecycle (emit) ----
     /**
-     * An agent's fully composed scoped world was published in the
-     * {@link AgentRegistry}. Its session is already live in the session store.
-     * Setup is composition-only by contract; the subsequent
-     * `agent/session-start` boundary is the first supported place to inject or
-     * queue startup work. A synchronous listener throw
-     * vetoes publication and rollback emits the matching disposal edges;
-     * returned-promise rejection is observed and logged but cannot
-     * retroactively veto this synchronous boundary. A synchronous listener
-     * that requests the advanced registry detach does not remove the entry
-     * immediately: removal and the paired `agent/disposed` edge wait until the
-     * creation dispatch unwinds, so no later creation listener observes a
-     * disposal that preceded its own creation callback.
+     * A fully configured agent and live session were published. Setup is
+     * composition-only; `agent/session-start` is the first startup-driving seam.
+     * Synchronous listener failure vetoes publication, while returned-promise
+     * rejection is reported. Detach requested during dispatch waits until every
+     * creation listener has observed the stable entry.
      * @param agent - the newly registered agent with its live session and completed setup.
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
-     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
-     * plain plugin context fires for every agent. The dispatch `this` is the
-     * scope carrier (`Scoped<Agent>`), built by the emitting side via
-     * `scopeTarget`/`agentEvents`.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode emit
      */
     'agent/created'(this: Scoped<Agent>, agent: Agent): void
     /**
-     * An agent was removed from the registry. The concrete AgentLoop lifecycle
-     * emits this only after its driver and any in-flight turn reach quiescence;
-     * a custom agent registered through the public registry owns its own driver
-     * contract, which the registry cannot infer. Ordered teardown may still be
-     * detaching the session and unwinding scoped registrations when this runs.
+     * An agent left the registry; AgentLoop emits this after driver quiescence
+     * but before session detachment and scoped-registration unwind. Custom
+     * registry users own their driver-ordering contract.
      * @param agent - the exact agent removed from the registry.
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
-     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
-     * plain plugin context fires for every agent. The dispatch `this` is the
-     * scope carrier (`Scoped<Agent>`), built by the emitting side via
-     * `scopeTarget`/`agentEvents`.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode emit
      */
     'agent/disposed'(this: Scoped<Agent>, agent: Agent): void
     /**
-     * Agent status changed (`idle` ⇄ `running`, or → `disposed`). Drive
-     * lifecycle off this transition, never off a status you just requested —
-     * `send()` does not flip status to `running` before it returns.
+     * Agent status changed (`idle` ⇄ `running`, or → `disposed`). `send()` does
+     * not enter `running` synchronously; drive lifecycle from this event.
      * @param agent - the agent whose status flipped.
      * @param status - the status just entered (the transition's destination).
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
-     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
-     * plain plugin context fires for every agent. The dispatch `this` is the
-     * scope carrier (`Scoped<Agent>`), built by the emitting side via
-     * `scopeTarget`/`agentEvents`.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode emit
      */
     'agent/status'(this: Scoped<Agent>, agent: Agent, status: AgentStatus): void
     /**
-     * A message entered the agent's inbox (queued or steering). Content and the
-     * resolved source are the detached, deeply-frozen values retained by the
-     * inbox. `source` has defaults applied and is not the caller's raw options.
+     * Detached, frozen content entered the agent's inbox. Source defaults have
+     * 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.
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
-     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
-     * plain plugin context fires for every agent. The dispatch `this` is the
-     * scope carrier (`Scoped<Agent>`), built by the emitting side via
-     * `scopeTarget`/`agentEvents`.
+     * 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
 
     // ---- session lifecycle (emit) ----
     /**
-     * The agent's session lifecycle began, fired once before its first turn.
-     * `source` says why ({@link SessionStartSource}: fresh startup, a resumed
-     * persisted session, …). A pure NOTIFICATION (emit, not waterfall): a
-     * listener cannot veto by returning a decision or throwing. A listener that
-     * wants to seed context does so via `agent.inject()` (a `context/message` the
-     * first request sees). A lifecycle owner can still dispose its structural
-     * ownership edge during this notification; publication rechecks liveness and
-     * then aborts before the driver starts.
+     * The session lifecycle began, once before the first turn. Use
+     * `agent.inject()` to seed model-facing context. This is a notification, not
+     * a veto; disposal requested by a lifecycle owner is rechecked before the
+     * driver starts.
      * @param agent - the agent whose session lifecycle began.
      * @param source - why the session started (fresh startup, resume, …).
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
-     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
-     * plain plugin context fires for every agent. The dispatch `this` is the
-     * scope carrier (`Scoped<Agent>`), built by the emitting side via
-     * `scopeTarget`/`agentEvents`.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode emit
      */
     'agent/session-start'(this: Scoped<Agent>, agent: Agent, source: SessionStartSource): void
 
-    // Turn and step boundaries are NOT mirrored as agent/* emits: a consumer
-    // that needs them reads the durable `turn/start`/`turn/end`/`step/start`/
-    // `step/end` session events off the `session/event` feed (the session log is
-    // the live transcript feed). See the module doc's three-domain rule and the
-    // "remove agent boundary mirror events" RFC.
+    // Turn and step boundaries are durable session events, not agent events.
 
     // ---- step/request extension seams (serial + waterfall) ----
     /**
-     * Awaited pre-step surface-mutation checkpoint, fired once per step AFTER
-     * `turn/start` (and after the prior step closed) but BEFORE this step's
-     * `step/start` — so anything a listener appends lands OUTSIDE the step,
-     * between `turn/start`/`step/end` and the upcoming `step/start`. `step` is
-     * the number of the step about to start. The loop awaits
-     * `ctx.serial('agent/pre-step', …)` after assembling the system prompt, then
-     * opens the step and derives the request history ONCE from whatever the
-     * surface now holds. This is where compaction belongs: it mutates the session
-     * surface in place (shadowing an older range with a summary node) with its
-     * log-only `compact/*` records cleanly outside any step, and the single
-     * subsequent derive reflects the mutation — so there is no double-derive and
-     * no listener can see (or be expected to act on) an assembled `messages`
-     * array that does not exist yet.
-     *
-     * Serial (awaited in registration order), not a waterfall: a listener
-     * mutates the surface as a side effect; there is nothing to transform, but
-     * the loop must wait for the mutation to complete before opening the step
-     * and deriving. Cordis `serial` bails early if a listener returns a bail
-     * value; this event is typed and documented as `void`, so listeners must not
-     * return a semantic veto value. `fullSystemPrompt` is the assembled prompt a
-     * listener needs to measure pressure (the system prompt counts toward the
-     * budget), and `sessionPrefix` is the instance's composed
-     * {@link agent/session-prefix} product for the same reason — every request
-     * carries it in front of the derived history, and it is composed BEFORE
-     * this seam fires precisely so a pressure gate counts the prefix the
-     * request will actually send (never a stale logged one). `signal` cancels
-     * any in-flight work a listener starts (e.g. a
-     * summarization model call).
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
-     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
-     * plain plugin context fires for every agent. The dispatch `this` is the
-     * scope carrier (`Scoped<Agent>`), built by the emitting side via
-     * `scopeTarget`/`agentEvents`.
-     * @param agent - the agent about to open the step.
-     * @param turn - the already-open turn this step belongs to.
-     * @param step - the number of the step about to start.
-     * @param fullSystemPrompt - the assembled prompt, for measuring token pressure.
-     * @param sessionPrefix - the instance's frozen session prefix, for the same measurement.
-     * @param signal - aborts in-flight listener work when the turn is torn down.
+     * Awaited serial checkpoint for session-surface mutation after prompt
+     * assembly and before `step/start`; appends land outside the pending step.
+     * The loop derives history once afterward, so compaction records and
+     * replacements are included without rewriting an assembled request. The
+     * prompt and prefix are the exact pressure inputs for that request, and
+     * `signal` cancels listener work.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+     * @param agent - the agent opening the step.
+     * @param turn - the open turn number.
+     * @param step - the pending step number.
+     * @param fullSystemPrompt - the assembled prompt.
+     * @param sessionPrefix - the frozen request prefix.
+     * @param signal - the turn abort signal.
      * @mode serial
      */
-    // TODO: `fullSystemPrompt`/`sessionPrefix` are a smell on a generic
-    // per-step seam — compaction
-    // is their only consumer, so a wide event carries payloads just one listener
-    // reads. Revisit if no second consumer appears: e.g. hand listeners a lazy
-    // prompt provider, or move token-pressure measurement behind a
-    // compaction-specific seam instead of the shared pre-step checkpoint.
+    // TODO: Move prompt-pressure inputs behind a compaction-specific seam if no second consumer appears.
     'agent/pre-step'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal): Promise<void> | void
     /**
-     * Waterfall: decide what happens to ONE drained queued message before it
-     * becomes a `user/message` — allow (optionally rewriting the prompt bytes or
-     * attaching `additionalContexts`) or block it. Fires inside the already-open
-     * turn, per drained message. Maps onto Claude Code's `UserPromptSubmit` hook.
-     * Call `next()` to delegate to the default (allow unchanged), or return a
-     * {@link PromptDecision} without calling `next()` to short-circuit.
+     * Allow, rewrite, or block one drained prompt before it becomes a user
+     * message. Call `next()` for the unchanged default.
      * @param agent - the agent draining its inbox.
      * @param content - the drained message's blocks, as queued.
      * @param source - the message's resolved source.
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
-     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
-     * plain plugin context fires for every agent. The dispatch `this` is the
-     * scope carrier (`Scoped<Agent>`), built by the emitting side via
-     * `scopeTarget`/`agentEvents`.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode waterfall
      */
     'agent/prompt-submit'(this: Scoped<Agent>, agent: Agent, content: ContentBlock[], source: MessageSource, next: () => Promise<PromptDecision>): Promise<PromptDecision>
     /**
-     * Waterfall: shape the step's call configuration — model switching,
-     * sampling overrides — by returning a replacement {@link LlmCallConfig}
-     * (the frozen seed is the config the loop would otherwise use). Config is
-     * ALL a listener shapes here: every request is a pure function of the
-     * session log (the reconstructability RFC), so model-visible content
-     * flows through the log channels — `inject()`, steering, prompt-submit
-     * `additionalContexts`, prompt sections via `system-prompt/assemble`, or
-     * the header-logged session prefix via {@link agent/session-prefix}
-     * — never through request mutation, and the loop records whatever config
-     * the request actually uses as a `request/header*` event before dispatch.
-     * The step's messages are already snapshotted when this fires (the
-     * `step/start` boundary): an `inject()` from a listener here lands in the
-     * log but joins the NEXT request. For surface mutation that must precede
-     * the snapshot (compaction), use {@link agent/pre-step}. Call `next()` to
-     * delegate, or return an {@link LlmCallConfig} without it to
-     * short-circuit.
+     * Replace the frozen call configuration. Model-visible content must use
+     * logged channels; this seam cannot mutate messages. Injection here joins
+     * the next request because the current step boundary is already fixed.
      * @param agent - the agent making the model call.
      * @param turn - the open turn number.
      * @param step - the step whose request this is.
      * @param config - the config the loop would use (frozen); return a replacement to switch.
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
-     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
-     * plain plugin context fires for every agent. The dispatch `this` is the
-     * scope carrier (`Scoped<Agent>`), built by the emitting side via
-     * `scopeTarget`/`agentEvents`.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode waterfall
      */
     'agent/request'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, config: LlmCallConfig, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
     /**
-     * Waterfall: compose the SESSION PREFIX — request-only messages placed in
-     * front of the ENTIRE derived history (directly after the provider's
-     * system slot) on every request this loop instance sends. Fired ONCE per
-     * loop instance, lazily before its first step's {@link agent/pre-step}
-     * seam — BEFORE the pre-step so a token-pressure gate (compaction) counts
-     * the prefix this instance will actually send, never a previous
-     * instance's logged one. The composed
-     * result is deep-frozen, recorded as `EpochHeader.messagePrefix` on the
-     * instance's anchoring `'initial'`/`'resume'` header snapshot, and reused
-     * verbatim for every subsequent request — never recomputed mid-session,
-     * so the provider prefix cache holds by construction (a process restart
-     * or `ctx.agents.resume()` is a new instance: it recomposes, and any
-     * drift lands attributably on the `'resume'` snapshot). Composition runs
-     * outside the step, before the boundary snapshot: a composing listener's
-     * session append joins the CURRENT request's derived history. A
-     * composition interrupted by a cancel/dispose landing inside the
-     * waterfall is discarded — never cached, logged, or sent — and the next
-     * turn recomposes under a live signal, so an abort-aware listener's
-     * degraded fallback cannot leak into later requests.
-     *
-     * This is the home for session-stable openers the model must always see
-     * but that must NOT become durable history — a skills catalog, an
-     * AGENTS.md digest, a workspace baseline: `Session.deriveMessages()`
-     * never returns the prefix, and the header events are its only durable
-     * record, so the request stays reconstructable from the log. Content
-     * that CHANGES mid-session belongs in the append-only history channels
-     * instead — `agent.inject()`, a `tools/post-execute` decision's
-     * `additionalContexts`, prompt-submit `additionalContexts` — each a
-     * durable `context/message` paid once and prefix-cached thereafter.
-     *
-     * The seed is a frozen empty list; a contributing listener returns a NEW
-     * array — never an in-place push. The canonical contribution is a
-     * PREPEND, `[mine, ...await next()]`: the waterfall unwinds
-     * innermost-first (the LAST-registered listener's `next()` resolves
-     * first), so prepending yields registration order on the wire, and every
-     * plugin using it composes deterministically. The append form
-     * `[...await next(), mine]` is legal but places a contribution AFTER
-     * every later-registered plugin's — reverse registration order when all
-     * contributors append. Call `next()` to
-     * delegate, or return a list without it to short-circuit.
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
-     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
-     * plain plugin context fires for every agent. The dispatch `this` is the
-     * scope carrier (`Scoped<Agent>`), built by the emitting side via
-     * `scopeTarget`/`agentEvents`.
+     * Compose request-only messages placed before derived history. The frozen
+     * result is computed once per loop instance, logged on its anchoring request
+     * header, and reused so the provider prefix remains stable. Interrupted
+     * composition is discarded. Composition precedes the first `agent/pre-step`
+     * and request boundary, so listener appends join the current request and
+     * pressure accounting sees the composed prefix. Changing context belongs in
+     * history; contributors should prepend to `await next()` to preserve registration order.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @param agent - the agent whose session prefix is being composed.
-     * @param prefix - the frozen empty seed; return an extended replacement to contribute.
-     * @param signal - aborts in-flight listener work (e.g. a discovery scan) when the step is torn down.
+     * @param prefix - the frozen seed; return an extended replacement.
+     * @param signal - aborts composition when the step is torn down.
      * @mode waterfall
      */
     'agent/session-prefix'(this: Scoped<Agent>, agent: Agent, prefix: Message[], signal: AbortSignal, next: () => Promise<Message[]>): Promise<Message[]>
@@ -558,47 +256,27 @@ declare module 'cordis' {
      * @param turn - the open turn number.
      * @param step - the step that produced the message.
      * @param message - the assistant message as assembled from the stream.
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
-     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
-     * plain plugin context fires for every agent. The dispatch `this` is the
-     * scope carrier (`Scoped<Agent>`), built by the emitting side via
-     * `scopeTarget`/`agentEvents`.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode waterfall
      */
     'agent/step-result'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, message: Message, next: () => Promise<Message>): Promise<Message>
     /**
-     * Waterfall: override the turn-continuation decision via a typed
-     * {@link ContinuationDecision}. The loop's `defaultDecision` is `continue`
-     * when the step had tool calls or steering was injected, else `stop`.
-     * Listeners force-continue (`/goal`, `/loop` — optionally attaching a
-     * `reason` recorded as next-step steering) or force-stop (budget guards).
-     * Call `next()` to delegate to the default, or return a decision to override.
+     * Override whether the turn continues. The default continues after tool
+     * calls or steering and stops otherwise; a continue reason becomes steering.
      * @param agent - the agent deciding whether to run another step.
      * @param turn - the turn being continued or stopped.
      * @param defaultDecision - what the loop would do absent an override.
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
-     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
-     * plain plugin context fires for every agent. The dispatch `this` is the
-     * scope carrier (`Scoped<Agent>`), built by the emitting side via
-     * `scopeTarget`/`agentEvents`.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode waterfall
      */
     'agent/turn-continuation'(this: Scoped<Agent>, agent: Agent, turn: number, defaultDecision: ContinuationDecision, next: () => Promise<ContinuationDecision>): Promise<ContinuationDecision>
     /**
-     * Serial terminal-stop checkpoint after the ordinary
-     * `agent/turn-continuation` waterfall, any `continue.reason`, and the
-     * pending-steering continuation override have been folded. A listener
-     * returns `{ action: 'stop' }` to make this turn terminal, or `undefined`
-     * to abstain. Terminal stop is monotonic: listener order and steering
-     * cannot resume the turn, and pending steering is discarded rather than
-     * becoming another step or turn.
+     * Monotonic terminal-stop checkpoint after continuation and steering are
+     * folded; a stop remains authoritative through turn close and flush:
+     * steering queued in that window is discarded, while ordinary sends survive.
      * @param agent - the agent whose composed continuation outcome may be stopped.
      * @param turn - the turn at its terminal-stop checkpoint.
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
-     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
-     * plain plugin context fires for every agent. The dispatch `this` is the
-     * scope carrier (`Scoped<Agent>`), built by the emitting side via
-     * `scopeTarget`/`agentEvents`.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode serial
      */
     'agent/turn-stop'(this: Scoped<Agent>, agent: Agent, turn: number): ContinuationStop | undefined
@@ -611,11 +289,7 @@ declare module 'cordis' {
      * @param turn - the turn in which the failure surfaced.
      * @param step - the step at which the failure surfaced.
      * @param error - the failure, verbatim.
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): a listener registered
-     * through `agent.ctx` fires only for that agent's dispatches; a listener on a
-     * plain plugin context fires for every agent. The dispatch `this` is the
-     * scope carrier (`Scoped<Agent>`), built by the emitting side via
-     * `scopeTarget`/`agentEvents`.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @mode emit
      */
     'agent/error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: Error): void