feat(skill): hot-refresh skill catalogs

packages/skill/tool-skill/README.i18n.yaml

@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # 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
-README.md: 50a0e06ac06ca8a3b89c3d5ac604dcf2dc423533
-README.zh.md: 56fb2b87adcf072cf2b8b6670864fa274ed5f66f
+#   pnpm run verify-translation-pairing --write packages/skill/tool-skill/README.md
+README.md: 7cbb2bef77bd32f188a4d3068a287fbee31b9371
+README.zh.md: fe17e2e7080151e9bd41d4e0b96764719b27baa5

packages/skill/tool-skill/README.md

@@ -4,13 +4,17 @@ English | [中文](README.zh.md)
 
 The model-facing skill catalog and `skill` tool.
 
-Requires `ctx.tools` and `ctx.skills` (`inject: ['tools', 'skills']`).
+Requires `ctx.agents`, `ctx.tools`, and `ctx.skills` (`inject: ['agents', 'tools', 'skills']`).
 
-## Session-prefix catalog
+## Catalog lifecycle
 
-The plugin contributes one user-role `<system-reminder>` catalog through `agent/session-prefix`. It resolves skills for the calling session's cwd, forwards the prefix abort signal to discovery, and lists only sorted `name` and `description` entries; skill bodies, paths, sources, providers, and `whenToUse` hints remain outside the catalog. The catalog is omitted when no model-invocable skills are available, and also when that agent's tool view restricts away the shipped `skill` tool or resolves a same-name scoped shadow instead. This exact-definition check keeps prompt guidance, the model-visible schema, and executable dispatch aligned.
+The plugin contributes the initial user-role `<system-reminder>` catalog through `agent/session-prefix`. Before every later model step it observes `ctx.skills.snapshot()` and computes a digest over exact `skill` tool visibility plus the ordered rendered `name` and `description` entries. It resolves skills for the calling session's cwd and lists only those summaries; skill bodies, paths, sources, providers, and `whenToUse` hints remain outside the catalog.
 
-`catalogDescriptionMaxLength` controls normalized, XML-escaped catalog descriptions. Its default is `500` and values must be integers of at least `3`, which reserves room for a truncation ellipsis. The [session-prefix Agent Note](../../../.agents/notes/implemented/feature/2026-07-07-session-prefix.md) defines the request-only, header-logged lifecycle of this message.
+When that digest changes, `agent.inject()` records a durable user-role message containing the complete replacement catalog and metadata `{ kind: 'skill-catalog', version: 1, digest }`. An empty replacement explicitly retires names from earlier catalogs. The latest still-visible metadata supplies the comparison baseline across replay or plugin reload. If compaction shadows that replacement, the next pre-step falls back to the loop's initial-prefix baseline and re-establishes the current catalog when needed. An incomplete provider snapshot emits nothing and preserves the last-good model view for retry on the next step. If no prior catalog exists and the current view is empty, no tombstone is necessary.
+
+The catalog is omitted when no model-invocable skills are initially available, and also when that agent's tool view restricts away the shipped `skill` tool or resolves a same-name scoped shadow instead. Visibility changes participate in the digest, keeping prompt guidance, model-visible schema, and executable dispatch aligned.
+
+`catalogDescriptionMaxLength` controls normalized, XML-escaped catalog descriptions. Its default is `500` and values must be integers of at least `3`, which reserves room for a truncation ellipsis. The [session-prefix Agent Note](../../../.agents/notes/implemented/feature/2026-07-07-session-prefix.md) defines the request-only, header-logged lifecycle of the initial message; the [skill catalog hot-refresh Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.md) owns durable replacements.
 
 ## Tool: `skill`
 
@@ -24,7 +28,7 @@ Resource guidance resolves only paths or URLs explicitly referenced by the instr
 
 An unresolved name reports that the skill is unknown or no longer available. Invalid names and `disableModelInvocation: true` skills produce distinct error results.
 
-The tool does not call `agent.inject()` in v1. Its result is already recorded as the tool result and becomes available to the next model step without duplicating the content as synthetic context.
+Tool execution does not call `agent.inject()`. Its freshly loaded result is already recorded as the tool result and becomes available to the next model step without duplicating the body as synthetic context. Only the catalog projection injects replacement summaries.
 
 ## Model Experience
 
@@ -32,7 +36,7 @@ The tool does not call `agent.inject()` in v1. Its result is already recorded as
 
 #### What the model sees
 
-If model-invocable skills exist and this exact `skill` tool is visible, the agent receives the catalog template below, with one data-dependent entry per sorted skill. The catalog is a frozen user-role session prefix.
+If model-invocable skills exist and this exact `skill` tool is visible, the agent receives the catalog template below, with one data-dependent entry per sorted skill. The initial catalog is a user-role session prefix. Later membership, description, or visibility changes append a complete replacement using the same `<available_skills>` envelope; deleting every skill appends an empty envelope with an explicit instruction not to use older names.
 
 ##### Skill catalog template
 
@@ -50,11 +54,11 @@ If the user names a skill, or the task clearly matches a skill's description, ca
 
 #### Token effect
 
-Repeated input cost scales with skill count and `catalogDescriptionMaxLength`; no catalog tokens are sent when the list is empty or the tool is hidden or shadowed.
+Repeated input cost scales with skill count and `catalogDescriptionMaxLength`; no initial catalog tokens are sent when the list is empty or the tool is hidden or shadowed. Each actual catalog change adds one retained complete replacement message.
 
 #### KV Cache effect
 
-Prefix-stable within a loop instance once the session prefix is composed. A new or resumed instance with different providers, skills, descriptions, visibility, or catalog limits may invalidate reuse from the first changed catalog token.
+The initial catalog remains prefix-stable. Dynamic changes are append-only history after that prefix, so existing reusable tokens stay intact while the replacement and later turns form a new suffix.
 
 ### Tool schema
 
@@ -146,3 +150,5 @@ Append-only; newly visible content follows the reusable request prefix and does
 - **Loaded instruction bodies have no size cap** — a provider can return a skill large enough to consume substantial next-step context; only catalog descriptions are truncated.
 - **Resources are guidance, not attachments** — the tool reports a base directory/URL/opaque hint but neither enumerates nor fetches referenced files for the model.
 - **Loading is one-shot text** — there is no partial, streaming, or cached-content handle when a remote provider is slow or a skill body is large.
+- **Catalog replacement is whole-list** — one changed name or description appends every currently visible summary; this keeps stale-name retirement explicit but costs tokens proportional to the catalog.
+- **Bodies are not versioned** — body-only edits do not change the catalog digest or notify the model; a later tool call reads the current provider content while earlier tool results remain historical facts.

packages/skill/tool-skill/README.zh.md

@@ -4,13 +4,17 @@
 
 面向模型的 skill 目录和 `skill` 工具。
 
-需要 `ctx.tools` 和 `ctx.skills` （`inject: ['tools', 'skills']`）。
+需要 `ctx.agents`、`ctx.tools` 和 `ctx.skills`（`inject: ['agents', 'tools', 'skills']`）。
 
-## 会话前缀目录
+## 目录生命周期
 
-该插件贡献一个用户角色 `<system-reminder>` 目录，并通过 `agent/session-prefix` 提供它。它为调用会话的 cwd 解析 skill，将前缀中止信号转发到发现，并只列出已排序的 `name` 和 `description` 条目；skill 正文、路径、来源、提供方和 `whenToUse` 提示仍位于目录之外。如果没有模型可调用 skill，则省略目录；如果该 agent 的工具视图排除已发布的 `skill` 工具，或解析出一个同名作用域遮蔽，也会省略目录。这项精确定义检查使提示词指引、模型可见 schema 和可执行分派保持对齐。
+该插件通过 `agent/session-prefix` 提供初始的用户角色 `<system-reminder>` 目录。之后每个模型步骤开始前，它都会观察 `ctx.skills.snapshot()`，并针对 `skill` 工具的精确可见性，以及按顺序渲染的 `name` 和 `description` 条目计算 digest。它根据调用会话的 cwd 解析 skill，且只列出这些摘要；skill 正文、路径、来源、提供方和 `whenToUse` 提示仍位于目录之外。
 
-`catalogDescriptionMaxLength` 控制规范化且经 XML 转义的目录描述。其默认值是 `500`，且必须是不小于 `3` 的整数，以便为截断省略号保留空间。[会话前缀 Agent Note](../../../.agents/notes/implemented/feature/2026-07-07-session-prefix.md) 定义了该消息仅存在于请求中、记录于 header 的生命周期。
+该 digest 变化时，`agent.inject()` 会记录一条持久的用户角色消息，其中包含完整替换目录和元数据 `{ kind: 'skill-catalog', version: 1, digest }`。空替换会显式停用较早目录中的名称。恢复后，最新且仍可见的元数据充当比较基线；若压缩（compaction）遮蔽了替换消息，模型步骤前的观察会改以会话前缀为基线，并在必要时重新发布当前完整目录。提供方快照不完整时，插件不会发送任何内容，并会保留最后一次完整的模型视图，以便在下一步骤重试。若不存在先前目录且当前视图为空，则不需要 tombstone。
+
+如果最初没有模型可调用 skill，则省略目录；如果该 agent 的工具视图排除已发布的 `skill` 工具，或解析出一个同名作用域遮蔽，也会省略目录。可见性变更参与 digest 计算，使提示词指引、模型可见 schema 和可执行分派保持对齐。
+
+`catalogDescriptionMaxLength` 控制规范化且经 XML 转义的目录描述。其默认值是 `500`，且必须是不小于 `3` 的整数，以便为截断省略号保留空间。[会话前缀 Agent Note](../../../.agents/notes/implemented/feature/2026-07-07-session-prefix.md) 定义了初始消息仅存在于请求中、记录于 header 的生命周期；[skill 目录热刷新 Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.md) 负责定义持久替换。
 
 ## 工具：`skill`
 
@@ -24,7 +28,7 @@
 
 无法解析的名称会报告 skill 未知或已不可用。无效名称和 `disableModelInvocation: true` skill 产生不同的错误结果。
 
-该工具在 v1 中不调用 `agent.inject()`。其结果已作为工具结果记录，并在下一个模型步骤可用，无需将内容重复为合成上下文。
+工具执行不调用 `agent.inject()`。新加载的结果已作为工具结果记录，并在下一个模型步骤可用，无需将正文重复为合成上下文。只有目录投影会注入替换摘要。
 
 ## 模型体验
 
@@ -32,7 +36,7 @@
 
 #### 模型所见
 
-如果存在模型可调用 skill，且该精确 `skill` 工具可见，agent 会收到下方目录模板，其中包含每个已排序 skill 的一条数据依赖条目。该目录是冻结的用户角色会话前缀。
+如果存在模型可调用 skill，且该精确 `skill` 工具可见，agent 会收到下方目录模板，其中包含每个已排序 skill 的一条数据依赖条目。初始目录是用户角色会话前缀。后续成员关系、描述或可见性的变化会使用同一个 `<available_skills>` 信封追加完整替换；删除所有 skill 时，会追加一个空信封，并明确指示不得使用旧名称。
 
 ##### Skill 目录模板
 
@@ -50,11 +54,11 @@ If the user names a skill, or the task clearly matches a skill's description, ca
 
 #### Token 影响
 
-重复输入成本随 skill 数量和 `catalogDescriptionMaxLength` 增长；当列表为空或工具被隐藏或遮蔽时，不会发送目录 token。
+重复输入成本随 skill 数量和 `catalogDescriptionMaxLength` 增长；当列表为空或工具被隐藏或遮蔽时，不会发送初始目录 token。每次实际目录变更都会添加一条保留的完整替换消息。
 
 #### KV 缓存影响
 
-会话前缀组合完成后，在一个循环实例内前缀稳定。如果新建或恢复的实例具有不同提供方、skill、描述、可见性或目录上限，则可能从第一个变更目录 token 起使重用失效。
+初始目录保持前缀稳定。动态变更作为该前缀之后的仅追加历史，因此现有可重用 token 保持不变，替换消息和后续轮次则形成新的后缀。
 
 ### 工具 schema
 
@@ -146,3 +150,5 @@ Load referenced resources only as needed.
 - **已加载指令正文没有大小上限**：提供方可返回足以占用大量下一步上下文的 skill；只有目录描述会被截断。
 - **资源是指引，而非附件**：工具报告基础目录/URL/不透明提示，但既不列举也不为模型获取引用文件。
 - **加载是一次性文本**：远程提供方缓慢或 skill 正文很大时，不提供部分、流式或缓存内容句柄。
+- **目录替换采用全量列表**：一个名称或描述发生变化，就会追加当前所有可见摘要；这样能显式停用陈旧名称，但 token 成本与目录大小成正比。
+- **正文不做版本化**：仅修改正文不会改变目录 digest，也不会通知模型；后续工具调用会读取提供方的当前内容，而先前工具结果仍是历史事实。

packages/skill/tool-skill/package.json

@@ -42,6 +42,7 @@
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-scope": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-skill": "workspace:^",
     "@deepseek-ai/dsh-skill-local": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",

packages/skill/tool-skill/src/index.ts

@@ -4,16 +4,21 @@
  * @module @deepseek-ai/dsh-tool-skill
  */
 
+import { createHash } from 'node:crypto'
 import type { Context } from 'cordis'
 import z from 'schemastery'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { assertNever, type Message } from '@deepseek-ai/dsh-llm'
+import type { Agent } from '@deepseek-ai/dsh-agent'
 import { isSkillName, type SkillDefinition, type SkillSummary } from '@deepseek-ai/dsh-skill'
 
 export const name = 'tool-skill'
-export const inject = ['tools', 'skills']
+export const inject = ['agents', 'tools', 'skills']
 
 const DEFAULT_CATALOG_DESCRIPTION_MAX_LENGTH = 500
+const CATALOG_META_KIND = 'skill-catalog'
+const CATALOG_META_VERSION = 1
+const PLUGIN_SOURCE = { kind: 'plugin', plugin: name } as const
 
 /** Model-facing skill catalog configuration. */
 export interface Config {
@@ -35,6 +40,7 @@ export const Config: z<Config> = z.object({
 export function apply(ctx: Context, config: Config = {}): void {
   const catalogDescriptionMaxLength = config.catalogDescriptionMaxLength ?? DEFAULT_CATALOG_DESCRIPTION_MAX_LENGTH
   assertPositiveInteger('catalogDescriptionMaxLength', catalogDescriptionMaxLength, 3)
+  const baselineBySession = new WeakMap<object, string>()
 
   const skillTool = defineTool({
     name: 'skill',
@@ -116,11 +122,40 @@ export function apply(ctx: Context, config: Config = {}): void {
   // Register after the tool so reverse teardown removes guidance first. Exact definition
   // identity prevents a scoped shadow merely named `skill` from inheriting this catalog.
   ctx.on('agent/session-prefix', async (agent, _prefix, signal, next): Promise<Message[]> => {
-    if (ctx.tools.get(skillTool.name, agent) !== registeredSkillTool) return await next()
-    const skills = await ctx.skills.list({ cwd: agent.session.header.cwd, signal })
+    const toolVisible = ctx.tools.get(skillTool.name, agent) === registeredSkillTool
+    const snapshot = toolVisible
+      ? await ctx.skills.snapshot({ cwd: agent.session.header.cwd, signal })
+      : { skills: [], complete: true }
     const rest = await next()
-    if (skills.length === 0) return rest
-    return [renderCatalogMessage(skills, catalogDescriptionMaxLength), ...rest]
+    signal.throwIfAborted()
+    if (!snapshot.complete) return rest
+    const digest = catalogDigest(toolVisible, snapshot.skills, catalogDescriptionMaxLength)
+    baselineBySession.set(agent.session, digest)
+    if (!toolVisible || snapshot.skills.length === 0) return rest
+    return [renderCatalogMessage(snapshot.skills, catalogDescriptionMaxLength), ...rest]
+  })
+
+  ctx.on('agent/pre-step', async (agent, _turn, _step, signal) => {
+    const toolVisible = ctx.tools.get(skillTool.name, agent) === registeredSkillTool
+    const snapshot = toolVisible
+      ? await ctx.skills.snapshot({ cwd: agent.session.header.cwd, signal })
+      : { skills: [], complete: true }
+    signal.throwIfAborted()
+    if (!snapshot.complete) return
+    const digest = catalogDigest(toolVisible, snapshot.skills, catalogDescriptionMaxLength)
+    const effective = latestVisibleCatalogDigest(agent) ?? baselineBySession.get(agent.session)
+    if (effective === digest) return
+    if (effective === undefined && snapshot.skills.length === 0) {
+      baselineBySession.set(agent.session, digest)
+      return
+    }
+    agent.inject(
+      renderCatalogUpdate(snapshot.skills, catalogDescriptionMaxLength).content,
+      {
+        source: PLUGIN_SOURCE,
+        meta: { kind: CATALOG_META_KIND, version: CATALOG_META_VERSION, digest },
+      },
+    )
   })
 }
 
@@ -171,7 +206,7 @@ function renderResourceHint(skill: Pick<SkillDefinition, 'provider' | 'resourceB
 }
 
 function renderCatalogMessage(skills: SkillSummary[], descriptionMaxLength: number): Message {
-  const entries = skills.map(skill => `- \`${skill.name}\`: ${catalogDescription(skill.description, descriptionMaxLength)}`)
+  const entries = renderCatalogEntries(skills, descriptionMaxLength)
   return {
     role: 'user',
     content: [{
@@ -191,6 +226,68 @@ function renderCatalogMessage(skills: SkillSummary[], descriptionMaxLength: numb
   }
 }
 
+function renderCatalogUpdate(skills: SkillSummary[], descriptionMaxLength: number): Message {
+  const entries = renderCatalogEntries(skills, descriptionMaxLength)
+  const availability = skills.length === 0
+    ? [
+      'No skills are currently available through the `skill` tool. Do not use names from earlier skill catalogs.',
+    ]
+    : [
+      'Use only names in this replacement catalog. If the user names a listed skill, or the task clearly matches its description, call the `skill` tool with the exact name before acting.',
+    ]
+  return {
+    role: 'user',
+    content: [{
+      type: 'text',
+      text: [
+        '<system-reminder>',
+        'The available skill catalog changed. This complete catalog replaces every earlier available-skills list in this session:',
+        '',
+        '<available_skills>',
+        ...entries,
+        '</available_skills>',
+        '',
+        ...availability,
+        '</system-reminder>',
+      ].join('\n'),
+    }],
+  }
+}
+
+function renderCatalogEntries(skills: SkillSummary[], descriptionMaxLength: number): string[] {
+  return skills.map(skill => `- \`${skill.name}\`: ${catalogDescription(skill.description, descriptionMaxLength)}`)
+}
+
+function catalogDigest(toolVisible: boolean, skills: SkillSummary[], descriptionMaxLength: number): string {
+  return createHash('sha256')
+    .update(JSON.stringify({
+      toolVisible,
+      entries: renderCatalogEntries(skills, descriptionMaxLength),
+    }))
+    .digest('hex')
+}
+
+function latestVisibleCatalogDigest(agent: Agent): string | undefined {
+  const visible = new Set(agent.session.surface.nodes)
+  for (const event of [...agent.session.events].reverse()) {
+    if (!visible.has(event.seq)
+      || event.type !== 'user/message'
+      || event.data.source.kind !== 'plugin'
+      || event.data.source.plugin !== name) continue
+    const meta = event.data.meta
+    if (!isRecord(meta)
+      || meta.kind !== CATALOG_META_KIND
+      || meta.version !== CATALOG_META_VERSION
+      || typeof meta.digest !== 'string') continue
+    return meta.digest
+  }
+  return undefined
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
 function catalogDescription(value: string, maxLength: number): string {
   const normalized = value.replaceAll(/\s+/g, ' ').trim()
   const truncated = normalized.length <= maxLength

packages/skill/tool-skill/tests/tool-skill.spec.ts

@@ -5,9 +5,10 @@ import { tmpdir } from 'node:os'
 import { Context } from 'cordis'
 import { CallId, type Message } from '@deepseek-ai/dsh-llm'
 import { createScope, type Scope } from '@deepseek-ai/dsh-scope'
+import { Session, SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
 import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
-import { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { agentEvents, AgentMessageId, type Agent } from '@deepseek-ai/dsh-agent'
 import SkillService from '@deepseek-ai/dsh-skill'
 import * as SkillLocal from '@deepseek-ai/dsh-skill-local'
 import * as toolSkill from '@deepseek-ai/dsh-tool-skill'
@@ -28,8 +29,9 @@ async function setup(home: string, config: toolSkill.Config = {}): Promise<Conte
   const ctx = new Context()
   await ctx.plugin(SystemPrompt)
   await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
   await ctx.plugin(SkillService)
-  await ctx.plugin(SkillLocal, { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') })
+  await ctx.plugin(SkillLocal, { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents'), watch: false })
   await ctx.plugin(toolSkill, config)
   return ctx
 }
@@ -38,6 +40,48 @@ function agentForCwd(cwd: string): Agent {
   return { session: { header: { cwd } } } as unknown as Agent
 }
 
+function sessionAgent(session: Session, id = 'tool-skill-agent'): Agent {
+  return {
+    id: SessionId(id),
+    options: {},
+    session,
+    status: 'running',
+    ctx: new Context(),
+    followup: () => AgentMessageId('stub'),
+    queue: () => AgentMessageId('stub'),
+    steer: () => AgentMessageId('stub'),
+    inject(content, options) {
+      session.append('user/message', {
+        content,
+        source: options?.source ?? { kind: 'user' },
+        ...(options?.meta === undefined ? {} : { meta: options.meta }),
+      }, { surfaceOp: 'append' })
+      return AgentMessageId('stub')
+    },
+    send: () => AgentMessageId('stub'),
+    cancel() {},
+    whenIdle: () => Promise.resolve(),
+  }
+}
+
+function openMessageTurn(session: Session, turn = 1): void {
+  session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } })
+  session.append('user/message', {
+    content: [{ type: 'text', text: `turn ${turn}` }],
+    source: { kind: 'user' },
+  }, { surfaceOp: 'append' })
+}
+
+async function firePreStep(ctx: Context, agent: Agent, turn: number, step: number): Promise<void> {
+  await agentEvents(ctx, agent).serial('agent/pre-step', turn, step, new AbortController().signal)
+}
+
+function catalogUpdates(session: Session): Extract<SessionEvent, { type: 'user/message' }>[] {
+  return session.events.filter((event): event is Extract<SessionEvent, { type: 'user/message' }> => event.type === 'user/message'
+    && event.data.source.kind === 'plugin'
+    && event.data.source.plugin === 'tool-skill')
+}
+
 async function composePrefix(ctx: Context, cwd: string, signal = new AbortController().signal): Promise<Message[]> {
   return await composePrefixForAgent(ctx, agentForCwd(cwd), signal)
 }
@@ -50,8 +94,8 @@ async function composePrefixForAgent(ctx: Context, agent: Agent, signal = new Ab
   )
 }
 
-async function mintAgentScope(ctx: Context, cwd: string): Promise<{ agent: Agent; scope: Scope }> {
-  const agent = agentForCwd(cwd)
+async function mintAgentScope(ctx: Context, subject: string | Agent): Promise<{ agent: Agent; scope: Scope }> {
+  const agent = typeof subject === 'string' ? agentForCwd(subject) : subject
   let scope!: Scope
   await ctx.plugin(Object.assign((inner: Context) => { scope = createScope(inner, agent) }, {
     inject: ['tools'],
@@ -64,9 +108,10 @@ describe('dsh-tool-skill', () => {
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
+    await ctx.plugin(AgentRegistry)
     const home = await tempDir('tool-schema')
     await ctx.plugin(SkillService)
-    await ctx.plugin(SkillLocal, { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') })
+    await ctx.plugin(SkillLocal, { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents'), watch: false })
     ctx.skills.register({ name: 'lifecycle-skill', description: 'Lifecycle', source: 'runtime', content: 'body' })
 
     const fiber = await ctx.plugin(toolSkill)
@@ -169,15 +214,227 @@ describe('dsh-tool-skill', () => {
     expect(await composePrefix(ctx, '/workspace')).toEqual([])
   })
 
+  it('omits an incomplete initial catalog and retries on a later request boundary', async () => {
+    const home = await tempDir('tool-incomplete-prefix')
+    const ctx = await setup(home)
+    let failing = true
+    const provider = {
+      name: 'recovering',
+      async list() {
+        if (failing) throw new Error('temporarily unavailable')
+        return []
+      },
+      async get() {
+        return undefined
+      },
+    }
+    ctx.skills.registerProvider(provider)
+    const session = new Session(SessionId('incomplete-prefix'))
+    const agent = sessionAgent(session)
+    openMessageTurn(session)
+
+    expect(await composePrefixForAgent(ctx, agent)).toEqual([])
+    failing = false
+    ctx.skills.invalidateProvider(provider)
+    await firePreStep(ctx, agent, 1, 1)
+
+    expect(catalogUpdates(session)).toEqual([])
+  })
+
+  it('records an empty baseline when pre-step runs before prefix composition', async () => {
+    const home = await tempDir('tool-empty-pre-step')
+    const ctx = await setup(home)
+    const session = new Session(SessionId('empty-pre-step'))
+    const agent = sessionAgent(session)
+    openMessageTurn(session)
+
+    await firePreStep(ctx, agent, 1, 1)
+    await firePreStep(ctx, agent, 1, 2)
+
+    expect(catalogUpdates(session)).toEqual([])
+  })
+
+  it('injects complete replacement catalogs for additions and an empty tombstone for removals', async () => {
+    const home = await tempDir('tool-dynamic-catalog')
+    const ctx = await setup(home)
+    const disposeFirst = ctx.skills.register({
+      name: 'first-skill',
+      description: 'First skill',
+      source: 'runtime',
+      content: 'First body.',
+    })
+    const session = new Session(SessionId('dynamic-catalog'))
+    const agent = sessionAgent(session)
+    openMessageTurn(session)
+
+    expect(JSON.stringify(await composePrefixForAgent(ctx, agent))).toContain('first-skill')
+    await firePreStep(ctx, agent, 1, 1)
+    expect(catalogUpdates(session)).toEqual([])
+
+    const disposeSecond = ctx.skills.register({
+      name: 'second-skill',
+      description: 'Second skill',
+      source: 'runtime',
+      content: 'Second body.',
+    })
+    await firePreStep(ctx, agent, 1, 2)
+
+    const addition = catalogUpdates(session)[0]
+    if (addition?.type !== 'user/message') throw new Error('expected catalog addition')
+    expect(addition.data.meta).toMatchObject({ kind: 'skill-catalog', version: 1 })
+    expect(JSON.stringify(addition.data.content)).toContain('first-skill')
+    expect(JSON.stringify(addition.data.content)).toContain('second-skill')
+
+    disposeSecond()
+    disposeFirst()
+    await firePreStep(ctx, agent, 1, 3)
+
+    const removal = catalogUpdates(session)[1]
+    if (removal?.type !== 'user/message') throw new Error('expected catalog removal')
+    expect(JSON.stringify(removal.data.content)).toContain('No skills are currently available')
+    expect(JSON.stringify(removal.data.content)).not.toContain('first-skill')
+    expect(JSON.stringify(removal.data.content)).not.toContain('second-skill')
+  })
+
+  it('resumes from the latest valid visible catalog metadata', async () => {
+    const home = await tempDir('tool-catalog-resume')
+    const ctx = await setup(home)
+    ctx.skills.register({
+      name: 'resumed-skill',
+      description: 'Resumed skill',
+      source: 'runtime',
+      content: 'Resumed body.',
+    })
+    const session = new Session(SessionId('catalog-resume'))
+    const agent = sessionAgent(session)
+    openMessageTurn(session)
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'old catalog' }],
+      source: { kind: 'plugin', plugin: 'tool-skill' },
+      meta: { kind: 'skill-catalog', version: 1, digest: 'old-digest' },
+    }, { surfaceOp: 'append' })
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'malformed metadata' }],
+      source: { kind: 'plugin', plugin: 'tool-skill' },
+      meta: { kind: 'skill-catalog', version: 1, digest: 42 },
+    }, { surfaceOp: 'append' })
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'non-record metadata' }],
+      source: { kind: 'plugin', plugin: 'tool-skill' },
+      meta: [],
+    }, { surfaceOp: 'append' })
+
+    await firePreStep(ctx, agent, 1, 1)
+
+    expect(catalogUpdates(session)).toHaveLength(4)
+    expect(JSON.stringify(catalogUpdates(session).at(-1)?.data.content)).toContain('resumed-skill')
+  })
+
+  it('re-establishes a replacement catalog after compaction shadows its metadata', async () => {
+    const home = await tempDir('tool-catalog-compaction')
+    const ctx = await setup(home)
+    ctx.skills.register({
+      name: 'first-skill',
+      description: 'First skill',
+      source: 'runtime',
+      content: 'First body.',
+    })
+    const session = new Session(SessionId('catalog-compaction'))
+    const agent = sessionAgent(session)
+    openMessageTurn(session)
+    expect(JSON.stringify(await composePrefixForAgent(ctx, agent))).toContain('first-skill')
+    ctx.skills.register({
+      name: 'second-skill',
+      description: 'Second skill',
+      source: 'runtime',
+      content: 'Second body.',
+    })
+    await firePreStep(ctx, agent, 1, 1)
+    const replacement = catalogUpdates(session)[0]
+    if (replacement === undefined) throw new Error('expected replacement catalog')
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'compacted history' }],
+      source: { kind: 'plugin', plugin: 'compact' },
+    }, {
+      surfaceOp: { op: 'replace', start: replacement.seq, end: replacement.seq },
+      sourceEventSeqs: [replacement.seq],
+    })
+
+    await firePreStep(ctx, agent, 1, 2)
+
+    expect(catalogUpdates(session)).toHaveLength(2)
+    expect(JSON.stringify(catalogUpdates(session).at(-1)?.data.content)).toContain('second-skill')
+  })
+
+  it('keeps body-only edits out of the catalog and loads the latest body on demand', async () => {
+    const home = await tempDir('tool-body-refresh')
+    const root = join(home, '.dsh/skills')
+    await writeSkill(root, 'body-skill', 'Stable description', 'First body.')
+    const ctx = await setup(home)
+    const session = new Session(SessionId('body-refresh'))
+    const agent = sessionAgent(session)
+    openMessageTurn(session)
+
+    expect(JSON.stringify(await composePrefixForAgent(ctx, agent))).toContain('Stable description')
+    await writeSkill(root, 'body-skill', 'Stable description', 'Second body.')
+    await firePreStep(ctx, agent, 1, 1)
+    expect(catalogUpdates(session)).toEqual([])
+
+    const result = await ctx.tools.execute({
+      signal: testToolSignal,
+      callId: CallId('body-refresh'),
+      name: 'skill',
+      arguments: { name: 'body-skill' },
+      agent,
+    })
+    expect(result.isError).toBe(false)
+    expect(JSON.stringify(result.content)).toContain('Second body.')
+    expect(JSON.stringify(result.content)).not.toContain('First body.')
+  })
+
+  it('retains the last-good catalog while any provider discovery is incomplete', async () => {
+    const home = await tempDir('tool-incomplete-catalog')
+    const ctx = await setup(home)
+    const disposeStable = ctx.skills.register({
+      name: 'stable-skill',
+      description: 'Stable skill',
+      source: 'runtime',
+      content: 'Stable body.',
+    })
+    const session = new Session(SessionId('incomplete-catalog'))
+    const agent = sessionAgent(session)
+    openMessageTurn(session)
+    expect(JSON.stringify(await composePrefixForAgent(ctx, agent))).toContain('stable-skill')
+
+    ctx.skills.registerProvider({
+      name: 'failing',
+      async list() {
+        throw new Error('temporarily unavailable')
+      },
+      async get() {
+        return undefined
+      },
+    })
+    disposeStable()
+    await firePreStep(ctx, agent, 1, 1)
+
+    expect(catalogUpdates(session)).toEqual([])
+  })
+
   it('omits catalog guidance when the calling agent restricts away the shipped skill tool', async () => {
     const home = await tempDir('tool-restricted-catalog')
     const ctx = await setup(home)
     ctx.skills.register({ name: 'listed-skill', description: 'Listed', source: 'runtime', content: 'body' })
-    const { agent, scope } = await mintAgentScope(ctx, '/workspace')
+    const session = new Session(SessionId('restricted-catalog'))
+    const agent = sessionAgent(session)
+    openMessageTurn(session)
+    const { scope } = await mintAgentScope(ctx, agent)
     scope.ctx.tools.restrict({ deny: ['skill'] })
 
     expect(ctx.tools.get('skill', agent)).toBeUndefined()
     expect(await composePrefixForAgent(ctx, agent)).toEqual([])
+    await firePreStep(ctx, agent, 1, 1)
+    expect(catalogUpdates(session)).toEqual([])
     expect(await composePrefix(ctx, '/workspace')).toHaveLength(1)
     await scope.dispose()
   })
@@ -207,8 +464,9 @@ describe('dsh-tool-skill', () => {
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
+    await ctx.plugin(AgentRegistry)
     await ctx.plugin(SkillService)
-    await ctx.plugin(SkillLocal, { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') })
+    await ctx.plugin(SkillLocal, { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents'), watch: false })
 
     await expect(ctx.plugin(toolSkill, { catalogDescriptionMaxLength: 2 })).rejects.toThrow('greater than or equal to 3')
   })