refactor agent pre-step inbox lifecycle

2026-07-31 19:21:16 +08:00
parent c2ff9ddec8
commit fcc2b5e282
267 changed files with 2052 additions and 1546 deletions
--- a/packages/context/workspace-context/README.i18n.yaml
+++ b/packages/context/workspace-context/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/context/workspace-context/README.md
-README.md: 2669422ec1fa7a74ba329cd96ee6b7e5e6da7e9d
-README.zh.md: e9fab4c6998f1193068389b41bdd7fa7d8c98dca
+README.md: 954a032e600579dda7f11ce3d11224aff7f7666e
+README.zh.md: ba945cfbf83398466c7888c5e95300dd8570870d
--- a/packages/context/workspace-context/README.md
+++ b/packages/context/workspace-context/README.md
@@ -6,7 +6,7 @@ Per-session workspace instruction loading for `AGENTS.md`-compatible files. The

 ## Lifecycle

-The baseline is injected at the first `agent/step` of each live session. It reads `$DSH_HOME/AGENTS.md` followed by, in each directory from the project root to `agent.session.header.cwd`, every existing base candidate and then every existing local-overlay candidate. Within one directory, candidates whose content is byte-identical after trimming leading and trailing whitespace collapse to the earliest candidate in configured order, so a `CLAUDE.md` that merely duplicates its sibling `AGENTS.md` is rendered once. The durable sourced `user/message` enters the same request as the claimed prompt.
+The first eligible `agent/pre-step` of each live session composes the baseline and prepends it to the agent's `next-step` inbox without changing the current `PreStepDecision`. It reads `$DSH_HOME/AGENTS.md` followed by, in each directory from the project root to `agent.session.header.cwd`, every existing base candidate and then every existing local-overlay candidate. Within one directory, candidates whose content is byte-identical after trimming leading and trailing whitespace collapse to the earliest candidate in configured order, so a `CLAUDE.md` that merely duplicates its sibling `AGENTS.md` is rendered once. Because the loop claims before running pre-step, the new context may enter a later request. If a previously queued workspace context is still pending, the plugin removes and replaces that exact inbox item instead of accumulating duplicates.

 The plugin also listens on `tools/post-execute` for successful first-party `read`, `write`, and `edit` calls. Each touch checks newly reached descendant scopes and every previously loaded scope. Each configured candidate name is an independent scope in its directory: a newly present file is attached through the result's `additionalContexts`; a changed file appends a replacement; a file that disappears or becomes a per-directory duplicate of an earlier candidate appends a removal notice. Native calls and Code Mode sub-dispatches share this path: `run_code` defers each nested context until its outer result, so the loop still appends updates after tool-call/result adjacency is complete. This follows structured filesystem activity rather than shell `cd`, because each local bash call starts a fresh shell and parsing arbitrary shell syntax would be unreliable.

@@ -48,11 +48,11 @@ The plugin owns the complete `<system-reminder>` framing, and every injected `us

 ## State And Refresh

-Model-visible text contains no hidden state markers. Each baseline or dynamic context event instead carries a typed `workspace-instructions` source with a list of `{ action, scope, path, digest? }` changes; the complete startup or resume baseline also carries `baseline: true`. On every relevant tool touch, the plugin reconstructs loaded state from its visible session events and overlays a short in-memory pending window for context present on the immutable top-level `tools/result` but not yet appended by the loop. A matching durable `user/message` confirms the pending transition. If the owning `step/end` arrives before a matching context reaches the log, the plugin clears the pending transition and its version fast path so the next successful touch can load it again. Nested Code Mode results stage pending changes under the outer execution token for same-run duplicate suppression; the outer result rolls that state back and recommits only contexts that survived outer policy.
+Model-visible text contains no hidden state markers. Each baseline or dynamic context event instead carries a typed `workspace-instructions` source with a list of `{ action, scope, path, digest? }` changes; the complete startup or resume baseline also carries `baseline: true`. A matching durable `user/message` confirms a queued baseline and its candidate versions. If pre-step rejects or rewrites away a claimed workspace message, a later boundary recomposes and queues the current context again. On every relevant tool touch, the plugin reconstructs loaded state from its visible session events and overlays a short in-memory pending window for context present on the immutable top-level `tools/result` but not yet appended by the loop. If the owning `step/end` arrives before a matching dynamic context reaches the log, the plugin clears that pending transition and its version fast path so the next successful touch can load it again. Nested Code Mode results stage pending changes under the outer execution token for same-run duplicate suppression; the outer result rolls that state back and recommits only contexts that survived outer policy.

 An unchanged path and SHA-1 content digest is not injected again. A per-session, per-scope provider cache stores only `{ path, version, digest, trimmedDigest }`: when the provider's opaque `FsVersion` and the effective visible state both match, reconciliation skips the content read; a changed version triggers a bounded read and SHA-1 confirmation before any model-visible update. The `trimmedDigest` — SHA-1 over the whitespace-trimmed content — is the per-directory duplicate key, so an unchanged file can still be removed when an earlier candidate converges on its content. Resume works because SHA-1 state is persisted in the typed source, while an empty in-memory version cache merely causes one confirming read. Compaction re-arms a scope after its context event leaves the visible surface even when the cached version is unchanged. A removal is a tombstone, so a later candidate reappearance is loaded again. Only model-visible changes actually rendered within the byte budget enter the source, pending state, and version cache; an omitted change remains eligible for a later touch, while a same-digest version refresh updates only the provider cache.

-The initial baseline event itself is not rewritten. Its typed changes remain authoritative only while that event is in the visible session surface; the next successful filesystem touch re-adds an unchanged baseline scope after compaction, or appends its replacement or removal. The in-memory scope marker and provider-version cache only select and accelerate probes. A hot plugin remount retains a baseline only when its typed event remains visible, while rebuilding current scope and version tracking; otherwise it injects a current baseline. A resumed loop always recomposes the current baseline and also reconciles still-visible dynamic scopes before its first request. There is no file watcher, so an on-disk change becomes visible at the next successful `read`, `write`, or `edit` touch, or when a resumed loop prepares its baseline.
+The initial baseline event itself is not rewritten. Its typed changes remain authoritative only while that event is in the visible session surface; the next successful filesystem touch re-adds an unchanged baseline scope after compaction, or appends its replacement or removal. The in-memory scope marker and provider-version cache only select and accelerate probes. A hot plugin remount retains a baseline only when its typed event remains visible, while rebuilding current scope and version tracking; otherwise it queues a current baseline. A resumed loop always recomposes the current baseline and also reconciles still-visible dynamic scopes at its first pre-step, but the resulting inbox context need not enter that same request. There is no file watcher, so an on-disk change becomes visible at the next successful `read`, `write`, or `edit` touch, or when a resumed loop prepares its baseline.

 ## Configuration

--- a/packages/context/workspace-context/README.zh.md
+++ b/packages/context/workspace-context/README.zh.md
@@ -6,7 +6,7 @@

 ## 生命周期

-基线会在每个实时会话的第一个 `agent/step` 注入。它先读取 `$DSH_HOME/AGENTS.md`，随后针对项目根目录到 `agent.session.header.cwd` 的每个目录，先读取每个现有基础候选文件，再读取每个现有本地 overlay 候选文件。同一目录中，如果候选文件在去除首尾空白后字节完全一致，就会按已配置顺序折叠到最早候选文件，因此 `CLAUDE.md` 若只是复制同级 `AGENTS.md`，只会渲染一次。这条持久的带来源 `user/message` 与被认领的提示词进入同一个请求。
+每个实时会话第一次符合条件的 `agent/pre-step` 会组合基线，将它 prepend 到 agent 的 `next-step` inbox，但不改变当前 `PreStepDecision`。它先读取 `$DSH_HOME/AGENTS.md`，随后针对项目根目录到 `agent.session.header.cwd` 的每个目录，先读取每个现有基础候选文件，再读取每个现有本地 overlay 候选文件。同一目录中，如果候选文件在去除首尾空白后字节完全一致，就会按已配置顺序折叠到最早候选文件，因此 `CLAUDE.md` 若只是复制同级 `AGENTS.md`，只会渲染一次。因为循环在运行 pre-step 前已经领取消息，新上下文可能要到后续请求才会进入。若之前排队的 workspace 上下文仍在等待，插件会删除并替换该确切 inbox 条目，而不会不断累积副本。

 该插件还会监听 `tools/post-execute` 中成功的第一方 `read`、`write` 和 `edit` 调用。每次 touch 都会检查新达到的后代 scope 以及之前加载的每个 scope。每个已配置候选名称都是所在目录中的独立 scope：新出现的文件通过结果的 `additionalContexts` 附加；已改变文件追加替换；文件消失或成为同一目录中较早候选文件的重复项时，追加移除通知。原生调用与 Code Mode 子分派共享该路径：`run_code` 将每个嵌套上下文延迟到外层结果，因此 loop 仍会在工具调用／结果相邻关系完成后追加更新。这种发现跟随结构化文件系统活动，而不是 shell `cd`，因为每次本地 bash 调用都启动新 shell，解析任意 shell 语法也不可靠。

@@ -48,11 +48,11 @@ These instructions apply to work under `packages/app`. Use them as guidance when

 ## 状态与刷新

-模型可见文本不含隐藏状态标记。每个基线或动态上下文事件改为携带带类型的 `workspace-instructions` 来源，其中包含 `{ action, scope, path, digest? }` 变更列表；完整的启动或恢复基线还会携带 `baseline: true`。每次相关工具 touch 时，插件会从可见会话事件重建已加载状态，并叠加一个短暂内存 pending 窗口，用于不可变顶层 `tools/result` 上存在但 loop 尚未追加的上下文。匹配的持久 `user/message` 会确认 pending 转换。如果所属 `step/end` 在匹配上下文进入日志之前到达，插件会清除 pending 转换及其版本快速路径，使下一次成功 touch 可以重新加载。嵌套 Code Mode 结果会在外层执行 token 下暂存 pending 变更，用于抑制同次运行中的重复项；外层结果会回滚该状态，再只重新提交经过外层策略的上下文。
+模型可见文本不含隐藏状态标记。每个基线或动态上下文事件改为携带带类型的 `workspace-instructions` 来源，其中包含 `{ action, scope, path, digest? }` 变更列表；完整的启动或恢复基线还会携带 `baseline: true`。匹配的持久 `user/message` 会确认已排队基线及其候选版本。若 pre-step reject 或改写掉已领取的 workspace 消息，后续边界会重新组合并排队当前上下文。每次相关工具 touch 时，插件会从可见会话事件重建已加载状态，并叠加一个短暂内存 pending 窗口，用于不可变顶层 `tools/result` 上存在但 loop 尚未追加的上下文。如果所属 `step/end` 在匹配的动态上下文进入日志之前到达，插件会清除该 pending 转换及其版本快速路径，使下一次成功 touch 可以重新加载。嵌套 Code Mode 结果会在外层执行 token 下暂存 pending 变更，用于抑制同次运行中的重复项；外层结果会回滚该状态，再只重新提交经过外层策略的上下文。

 路径与 SHA-1 内容 digest 都未变时，不会重复注入。每会话、每 scope 提供方 cache 只存储 `{ path, version, digest, trimmedDigest }`：当提供方的不透明 `FsVersion` 与有效可见状态都匹配时，对账会跳过内容读取；版本改变会在任何模型可见更新之前触发有界读取与 SHA-1 确认。`trimmedDigest` 是针对去除空白后内容的 SHA-1，也是每目录重复 key，因此较早候选文件与某个未更改文件的内容收敛后，后者仍可被移除。恢复可行，因为 SHA-1 状态持久化在带类型的来源中，而空的内存版本 cache 只会导致一次确认读取。压缩（compaction）会在 scope 的上下文事件离开可见表层后重新启用它，即使缓存版本未变。移除是 tombstone，因此候选文件之后重新出现时会重新加载。只有在字节预算内实际渲染的模型可见变更才会进入来源、pending 状态和版本 cache；已省略变更仍可在后续 touch 处理，而相同 digest 的版本刷新只更新提供方 cache。

-初始基线事件自身不会被改写。其带类型的变更仅在该事件仍位于可见会话表层时才是权威状态；下一次成功的文件系统 touch 会在压缩后重新添加未变的基线 scope，或追加其替换或移除。内存中的 scope 标记和提供方版本 cache 只负责选择探测对象并加速探测。插件热重挂只有在其带类型的事件仍然可见时才保留基线，同时会重建当前 scope 与版本跟踪状态；否则会注入当前基线。恢复的 loop 始终重新组合当前基线，并在第一个请求前对账仍可见的动态 scope。没有文件 watcher，因此磁盘变更会在下一次成功 `read`、`write` 或 `edit` touch 时可见，也会在恢复 loop 准备基线时可见。
+初始基线事件自身不会被改写。其带类型的变更仅在该事件仍位于可见会话表层时才是权威状态；下一次成功的文件系统 touch 会在压缩后重新添加未变的基线 scope，或追加其替换或移除。内存中的 scope 标记和提供方版本 cache 只负责选择探测对象并加速探测。插件热重挂只有在其带类型的事件仍然可见时才保留基线，同时会重建当前 scope 与版本跟踪状态；否则会排队当前基线。恢复的 loop 始终在第一次 pre-step 重新组合当前基线，并对账仍可见的动态 scope，但产生的 inbox 上下文不保证进入同一次请求。没有文件 watcher，因此磁盘变更会在下一次成功 `read`、`write` 或 `edit` touch 时可见，也会在恢复 loop 准备基线时可见。

 ## 配置

--- a/packages/context/workspace-context/src/index.ts
+++ b/packages/context/workspace-context/src/index.ts
@@ -10,8 +10,9 @@
 */

 import type { Context } from 'cordis'
-import type { Agent } from '@deepseek-ai/dsh-agent'
-import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import type { Agent, PreStepDecision } from '@deepseek-ai/dsh-agent'
+import { createUserMessage, type MessageId } from '@deepseek-ai/dsh-llm'
+import type { UserMessage } from '@deepseek-ai/dsh-session'
 import type { PostToolDecision, ToolExecution, ToolExecutionResult, ToolExecutionToken } from '@deepseek-ai/dsh-tools'
 import { Config, resolveConfig, type ResolvedConfig } from './config.ts'
 import { loadBaselineInstructionSet } from './files.ts'
@@ -27,6 +28,7 @@ import {
  rollbackPendingInstructionChanges,
  workspaceContextMessage,
  type InstructionVersionCache,
+  type InstructionVersionState,
  type InstructionVersionUpdate,
  type PendingInstructionChange,
 } from './state.ts'
@@ -60,6 +62,10 @@ export function apply(ctx: Context, config: Config): void {
  const instructionVersions: InstructionVersionCache = new WeakMap()
  const pendingVersionUpdates = new Map<ToolExecutionToken, InstructionVersionUpdate[]>()
  const baselineLoaded = new WeakSet<object>()
+  const pendingBaselineCommits = new WeakMap<object, {
+    messageIds: Set<MessageId>
+    versions: Map<string, InstructionVersionState>
+  }>()
  // Sessions whose lifecycle start this mount witnessed. A startup or resume
  // emits agent/session-start before the first step; a hot remount attaches to
  // an already-live session and never sees it. Resumes always re-compose the
@@ -78,18 +84,43 @@ export function apply(ctx: Context, config: Config): void {

  ctx.on('session/event', (session, event) => {
    observeInstructionSessionEvent(session, event, pendingNestedChanges, instructionVersions)
+    const pending = pendingBaselineCommits.get(session)
+    if (pending === undefined || event.type !== 'user/message'
+      || !pending.messageIds.delete(event.data.id) || pending.messageIds.size > 0) return
+    baselineSessions.add(session)
+    if (pending.versions.size === 0) instructionVersions.delete(session)
+    else instructionVersions.set(session, pending.versions)
+    baselineLoaded.add(session)
+    pendingBaselineCommits.delete(session)
  })

-  ctx.on('agent/step', async (agent: Agent, _turn, _step, signal): Promise<void> => {
-    if (baselineLoaded.has(agent.session)) return
+  ctx.on('agent/pre-step', async (
+    agent: Agent,
+    _messages,
+    { signal },
+    next,
+  ): Promise<PreStepDecision> => {
+    const decision = await next()
+    if (signal.aborted || baselineLoaded.has(agent.session)) return decision
+    const previous = pendingBaselineCommits.get(agent.session)
+    if (decision.kind === 'enter' && previous !== undefined
+      && [...previous.messageIds].every(id => decision.messages.some(message => message.id === id))) {
+      return decision
+    }
+    if (previous !== undefined) {
+      for (const id of previous.messageIds) agent.inbox.remove('next-step', id)
+      pendingBaselineCommits.delete(agent.session)
+    }
    if (resolved.maxBytes <= 0 || !Number.isFinite(resolved.maxBytes)) {
      baselineLoaded.add(agent.session)
-      return
+      pendingBaselineCommits.delete(agent.session)
+      return decision
    }
    const fileSystem = ctx.get('fs')
    if (fileSystem === undefined) {
      baselineLoaded.add(agent.session)
-      return
+      pendingBaselineCommits.delete(agent.session)
+      return decision
    }
    /* v8 ignore next -- normal agents carry an absolute session cwd. */
    const cwd = agent.session.header.cwd ?? process.cwd()
@@ -104,34 +135,52 @@ export function apply(ctx: Context, config: Config): void {
      signal,
    }, fileSystem)
    const baseline = baselineInstructionState(instructions?.included ?? [])
-    baselineSessions.add(agent.session)
-    instructionVersions.set(agent.session, baseline.versions)
+    const candidateVersions: InstructionVersionCache = new WeakMap()
+    candidateVersions.set(agent.session, new Map(baseline.versions))
+    const contexts: UserMessage[] = []

    const update = await reconcileInstructionContext(
      agent,
      resolved,
      pendingNestedChanges,
-      instructionVersions,
+      candidateVersions,
      fileSystem,
      { includeBaselineScopes: false, signal },
    )
    if (update !== undefined) {
-      agent.session.append('user/message', update.context, { surfaceOp: 'append' })
-      applyInstructionVersionUpdates(agent.session, update.versionUpdates, instructionVersions)
+      contexts.push(update.context)
+      applyInstructionVersionUpdates(agent.session, update.versionUpdates, candidateVersions)
    }
    const keepVisibleBaseline = !lifecycleWitnessed.has(agent.session) && hasVisibleBaseline(agent)
    if (!keepVisibleBaseline && instructions !== undefined && instructions.rendered.text.length > 0) {
      const baselineMessage = workspaceContextMessage(instructions.rendered.text)
-      agent.session.append('user/message', createUserMessage({
+      contexts.push(createUserMessage({
        content: baselineMessage.content,
        source: {
          kind: 'workspace-instructions',
          baseline: true,
          changes: [...baseline.changes.values()],
        },
-      }), { surfaceOp: 'append' })
+      }))
    }
-    baselineLoaded.add(agent.session)
+    const versions = candidateVersions.get(agent.session)
+      ?? new Map<string, InstructionVersionState>()
+    if (contexts.length === 0) {
+      baselineSessions.add(agent.session)
+      if (versions.size === 0) instructionVersions.delete(agent.session)
+      else instructionVersions.set(agent.session, versions)
+      baselineLoaded.add(agent.session)
+      pendingBaselineCommits.delete(agent.session)
+      return decision
+    }
+    pendingBaselineCommits.set(agent.session, {
+      messageIds: new Set(contexts.map(context => context.id)),
+      versions,
+    })
+    for (const context of contexts.toReversed()) {
+      agent.inbox.prepend('next-step', context)
+    }
+    return decision
  })

  ctx.on('tools/post-execute', async (
--- a/packages/context/workspace-context/tests/workspace-context.spec.ts
+++ b/packages/context/workspace-context/tests/workspace-context.spec.ts
@@ -176,7 +176,7 @@ function stubAgent(cwd?: string, seed: SessionEvent[] = []): Agent {
    id: SessionId('a1'),
    options: {},
    session,
-    inbox: new Inbox(session),
+    inbox: new Inbox(session, { inserted: () => {}, discarded: () => {} }),
    status: 'idle',
    send: () => {},
    followup: () => {},
@@ -231,7 +231,25 @@ function appendAdditionalContexts(agent: Agent, result: { additionalContexts?: U
 const composedPrefixes = new WeakMap<object, Message[]>()

 async function composeBaselinePrefix(ctx: Context, agent: Agent): Promise<Message[]> {
-  await agentEvents(ctx, agent).serial('agent/step', 1, 1, AbortSignal.timeout(1000))
+  const signal = AbortSignal.timeout(1000)
+  await agentEvents(ctx, agent).waterfall(
+    'agent/pre-step',
+    [],
+    { turn: 1, step: 1, signal },
+    () => Promise.resolve({ kind: 'enter' as const, messages: [] }),
+  )
+  const claimed = agent.inbox.claim('next-step')
+  const decision = await agentEvents(ctx, agent).waterfall(
+    'agent/pre-step',
+    claimed,
+    { turn: 1, step: 2, signal },
+    () => Promise.resolve({ kind: 'enter' as const, messages: claimed }),
+  )
+  const entered = decision.kind === 'enter' ? decision.messages : []
+  for (const message of entered) {
+    const event = agent.session.append('user/message', message, { surfaceOp: 'append' })
+    ctx.emit('session/event', agent.session, event)
+  }
  const prefix = agent.session.deriveMessages()
  composedPrefixes.set(agent, prefix)
  return prefix
@@ -1000,7 +1018,7 @@ describe('workspace context request injection', () => {
    }
  })

-  it('injects one durable baseline contribution on the first step only', async () => {
+  it('queues and later commits one durable baseline contribution', async () => {
    const root = await tempRepo()
    const home = await tempRepo()
    try {
@@ -1022,6 +1040,66 @@ describe('workspace context request injection', () => {
    }
  })

+  it('leaves the current pre-step batch unchanged while queuing the baseline', async () => {
+    const root = await tempRepo()
+    const home = await tempRepo()
+    try {
+      await mkdir(join(root, '.git'), { recursive: true })
+      await write(join(root, 'AGENTS.md'), 'repo rule')
+      const ctx = new Context()
+      await mountWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
+      const agent = stubAgent(root)
+      const prompt = createUserMessage({
+        content: [{ type: 'text', text: 'current prompt' }],
+        source: { kind: 'user' },
+      })
+
+      const decision = await agentEvents(ctx, agent).waterfall(
+        'agent/pre-step',
+        [prompt],
+        { turn: 1, step: 1, signal: AbortSignal.timeout(1000) },
+        () => Promise.resolve({ kind: 'enter' as const, messages: [prompt] }),
+      )
+
+      expect(decision).toEqual({ kind: 'enter', messages: [prompt] })
+      expect(agent.inbox.nextStep).toHaveLength(1)
+      expect(blocksText(agent.inbox.nextStep[0]?.content)).toContain('Instructions from: AGENTS.md')
+    } finally {
+      await rm(root, { recursive: true, force: true })
+      await rm(home, { recursive: true, force: true })
+    }
+  })
+
+  it('retries a baseline contribution removed by an outer pre-step listener', async () => {
+    const root = await tempRepo()
+    const home = await tempRepo()
+    try {
+      await mkdir(join(root, '.git'), { recursive: true })
+      await write(join(root, 'AGENTS.md'), 'repo rule')
+      const ctx = new Context()
+      const removeBaseline = ctx.on('agent/pre-step', async (_agent, _messages, _context, next) => {
+        const decision = await next()
+        return decision.kind === 'reject'
+          ? decision
+          : {
+            ...decision,
+            messages: decision.messages.filter(message =>
+              message.source.kind !== 'workspace-instructions'),
+          }
+      })
+      await mountWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
+      const agent = stubAgent(root)
+
+      expect(await composeBaselinePrefix(ctx, agent)).toEqual([])
+      removeBaseline()
+      expect(blocksText((await composeBaselinePrefix(ctx, agent))[0]?.content))
+        .toContain('Instructions from: AGENTS.md')
+    } finally {
+      await rm(root, { recursive: true, force: true })
+      await rm(home, { recursive: true, force: true })
+    }
+  })
+
  it('retains a visible baseline after a plugin remount', async () => {
    const root = await tempRepo()
    const home = await tempRepo()
@@ -1154,7 +1232,7 @@ describe('workspace context request injection', () => {
    }
  })

-  it('places workspace instructions before later step contributors such as a skills catalog', async () => {
+  it('keeps an independent pre-step contribution after the queued workspace context', async () => {
    const root = await tempRepo()
    const home = await tempRepo()
    try {
@@ -1162,8 +1240,16 @@ describe('workspace context request injection', () => {
      await write(join(root, 'AGENTS.md'), 'repo rule')
      const ctx = new Context()
      await mountWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
-      ctx.on('agent/step', (agent) => {
-        agent.session.append('user/message', createUserMessage({ content: [{ type: 'text', text: '<system-reminder>Available skills</system-reminder>' }], source: { kind: 'plugin', plugin: 'test-skills' } }), { surfaceOp: 'append' })
+      ctx.on('agent/pre-step', async (_agent, _messages, _context, next) => {
+        const decision = await next()
+        if (decision.kind === 'reject') return decision
+        return {
+          ...decision,
+          messages: [
+            ...decision.messages,
+            createUserMessage({ content: [{ type: 'text', text: '<system-reminder>Available skills</system-reminder>' }], source: { kind: 'plugin', plugin: 'test-skills' } }),
+          ],
+        }
      })

      const prefix = await composeBaselinePrefix(ctx, stubAgent(root))
@@ -1420,7 +1506,7 @@ describe('workspace context request injection', () => {
    }
  })

-  it('aborts an in-flight baseline stream with the step signal', async () => {
+  it('aborts an in-flight baseline stream with the prompt signal', async () => {
    const root = join(await tempRepo(), 'virtual-repo')
    const home = join(await tempRepo(), 'virtual-home')
    const ctx = new Context()
@@ -1432,7 +1518,12 @@ describe('workspace context request injection', () => {
      await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 })
      const controller = new AbortController()
      const reason = new Error('cancel prefix')
-      const pending = agentEvents(ctx, stubAgent(root)).serial('agent/step', 1, 1, controller.signal)
+      const pending = agentEvents(ctx, stubAgent(root)).waterfall(
+        'agent/pre-step',
+        [],
+        { turn: 1, step: 1, signal: controller.signal },
+        () => Promise.resolve({ kind: 'enter' as const, messages: [] }),
+      )

      await fs.started.promise
      controller.abort(reason)
@@ -1662,7 +1753,7 @@ describe('workspace context request injection', () => {
    }
  })

-  it('cleans up its agent/step listener when the plugin fiber is disposed', async () => {
+  it('cleans up its pre-step listener when the plugin fiber is disposed', async () => {
    const root = await tempRepo()
    const home = await tempRepo()
    try {