Merge remote-tracking branch 'origin/master' into xtr/react-loop-simplification

# Conflicts: # .agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml # .agents/notes/implemented/architecture/2026-07-31-goal-owned-durable-events.i18n.yaml # .agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml # .agents/notes/implemented/feature/2026-07-22-docked-web-goal-bar.i18n.yaml # docs/architecture.i18n.yaml # docs/architecture.md # docs/architecture.zh.md # docs/config-catalog.md # docs/cordis-catalog/events.md # docs/cordis-catalog/services.md # docs/core-data-structures/core.i18n.yaml # docs/core-data-structures/core.md # docs/core-data-structures/core.zh.md # docs/event-producer-consumer.md # docs/module-graph.md # docs/persistence-catalog.md # examples/acp-agent/tests/snapshots/advanced-toolchain/session.1.jsonl # examples/acp-agent/tests/snapshots/advanced-toolchain/session.2.jsonl # examples/acp-agent/tests/snapshots/code-mode-workspace-context/session.jsonl # examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl # examples/acp-agent/tests/snapshots/skill-load/session.jsonl # examples/acp-agent/tests/snapshots/subagent-depth-two-rejection/session.1.jsonl # examples/acp-agent/tests/snapshots/subagent-depth-two-rejection/session.2.jsonl # examples/acp-agent/tests/snapshots/subagent-fork/session.1.jsonl # examples/acp-agent/tests/snapshots/subagent-mixed/session.1.jsonl # examples/acp-agent/tests/snapshots/subagent-mixed/session.2.jsonl # examples/acp-agent/tests/snapshots/subagent-multi/session.1.jsonl # examples/acp-agent/tests/snapshots/subagent-multi/session.2.jsonl # examples/acp-agent/tests/snapshots/subagent-spawn/session.1.jsonl # examples/acp-agent/tests/snapshots/workflow-run/session.1.jsonl # examples/acp-agent/tests/snapshots/workspace-context/session.jsonl # examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl # examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl # examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl # examples/headless-agent/tests/snapshots/pty-tools/session.jsonl # examples/headless-agent/tests/subagent-inheritance-snapshots/parent-override/child.expected.jsonl # examples/jsonrpc-agent/tests/snapshots/subagent-spawn/notifications.expected.jsonl # examples/jsonrpc-agent/tests/snapshots/subagent-spawn/session.1.jsonl # packages/acp/acp/README.i18n.yaml # packages/acp/acp/src/index.ts # packages/client/connection/src/client/index.ts # packages/client/runtime/README.i18n.yaml # packages/client/runtime/README.md # packages/client/runtime/README.zh.md # packages/client/runtime/src/client/sessions/conversation.ts # packages/client/runtime/src/client/sessions/session.ts # packages/client/runtime/tests/queue-store.spec.ts # packages/client/ui-conversation/src/client/input/contract.ts # packages/client/ui-goal/README.i18n.yaml # packages/compact/compact-basic/src/index.ts # packages/context/time-context/tests/time-context.spec.ts # packages/context/tmux-context/tests/tmux-context.spec.ts # packages/context/workspace-context/tests/workspace-context.spec.ts # packages/cordis/tool-cordis/src/api-catalog.ts # packages/core/agent-loop/README.i18n.yaml # packages/core/agent-loop/README.md # packages/core/agent-loop/README.zh.md # packages/core/agent-loop/src/agent.ts # packages/core/agent-loop/tests/agent.spec.ts # packages/core/agent-loop/tests/loop.spec.ts # packages/core/agent/README.i18n.yaml # packages/core/agent/README.md # packages/core/agent/README.zh.md # packages/core/agent/src/types.ts # packages/core/session/README.i18n.yaml # packages/core/session/README.md # packages/core/session/README.zh.md # packages/goal/command-goal/tests/command-goal.spec.ts # packages/goal/goal/tests/goal.spec.ts # packages/goal/tool-goal/README.i18n.yaml # packages/goal/tool-goal/README.md # packages/goal/tool-goal/README.zh.md # packages/host/apiproxy/README.i18n.yaml # packages/host/apiproxy/README.md # packages/host/apiproxy/README.zh.md # packages/host/apiproxy/src/api-proxy.ts # packages/host/apiproxy/src/api/events.schema.ts # packages/host/apiproxy/src/api/events.ts # packages/host/apiproxy/src/api/rpc.ts # packages/host/apiproxy/tests/api-proxy-commands.spec.ts # packages/host/apiproxy/tests/api-proxy-projections.spec.ts # packages/host/apiproxy/tests/rpc-schemas.spec.ts # packages/pty/pty-local/tests/index.spec.ts # packages/pty/pty-local/tests/local.spec.ts # packages/pty/tool-pty/tests/loader-composition.spec.ts # packages/pty/tool-pty/tests/tools.spec.ts # packages/session-persistence/session-checkpoint-policy/src/index.ts # packages/session-persistence/session-persistence/tests/coordinator-contract.ts # packages/skill/tool-skill/tests/tool-skill.spec.ts # packages/subagent/subagent-inprocess/README.i18n.yaml # packages/subagent/subagent-inprocess/README.md # packages/subagent/subagent-inprocess/README.zh.md # packages/subagent/subagent-inprocess/src/index.ts # packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts # packages/support/acp-snapshot/src/harness.ts # packages/ui/tui/tests/tui.spec.ts
2026-08-03 10:56:09 +08:00
parent b4258a2c4a 8bf606ba80
commit dc1d542092
605 changed files with 25740 additions and 2265 deletions
--- a/scripts/dev-web.spec.ts
+++ b/scripts/dev-web.spec.ts
@@ -0,0 +1,42 @@
+import { mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { expect, it } from 'vitest'
+import type { TsdownBundle } from 'tsdown'
+import { watchClientPlugins } from './dev-web.ts'
+
+it('rebuilds a client-plugin bundle after its source changes', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'dsh-dev-web-watch-'))
+  let bundles: TsdownBundle[] = []
+  try {
+    await symlink(join(import.meta.dirname, '..', 'node_modules'), join(root, 'node_modules'), 'dir')
+    await writeFile(join(root, 'package.json'), JSON.stringify({ name: '@dsh-test/dev-web-watch', private: true, type: 'module' }))
+    await writeFile(join(root, 'tsdown.config.ts'), `
+import { defineConfig } from 'tsdown'
+export default defineConfig({
+  entry: { client: 'src.ts' }, outDir: 'lib', format: 'cjs', platform: 'browser', dts: false, clean: false,
+  outputOptions: { entryFileNames: 'client.js' },
+})
+`)
+    const sourcePath = join(root, 'src.ts')
+    const bundlePath = join(root, 'lib/client.js')
+    await writeFile(sourcePath, 'export const version = "watch-v1"\n')
+    bundles = await watchClientPlugins(root, ['.'], 50)
+    await expect.poll(async () => {
+      try {
+        return (await readFile(bundlePath, 'utf8')).includes('watch-v1')
+      } catch {
+        return false
+      }
+    }, { timeout: 10_000 }).toBe(true)
+
+    await new Promise(resolve => setTimeout(resolve, 1_000))
+    await writeFile(sourcePath, `export const version = "watch-v2-${'x'.repeat(100)}"\n`)
+    await expect.poll(async () => (await readFile(bundlePath, 'utf8')).includes('watch-v2-'), {
+      timeout: 10_000,
+    }).toBe(true)
+  } finally {
+    for (const bundle of bundles) await bundle[Symbol.asyncDispose]()
+    await rm(root, { recursive: true, force: true })
+  }
+}, 20_000)
--- a/scripts/dev-web.ts
+++ b/scripts/dev-web.ts
@@ -18,9 +18,10 @@
 * keys under each package's file config, and no package config defines it).
 */
 import { globSync, readFileSync } from 'node:fs'
-import { dirname, join, sep } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { dirname, join, resolve, sep } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 import { build } from 'tsdown'
+import type { TsdownBundle } from 'tsdown'

 const repoRoot = fileURLToPath(new URL('..', import.meta.url))

@@ -29,46 +30,64 @@ const repoRoot = fileURLToPath(new URL('..', import.meta.url))
 * whose package.json carries `dshClient` with platform "web" is a client
 * plugin bundle emitter. Scanned once at startup — a package added while
 * watching means restarting this script.
+ * @param root - repository root containing the grouped package directories.
 * @returns workspace-relative plugin package directories.
 */
-function discoverPluginDirs(): string[] {
+export function discoverPluginDirs(root = repoRoot): string[] {
  const dirs: string[] = []
-  for (const manifestPath of globSync('packages/*/*/package.json', { cwd: repoRoot }).sort()) {
-    const manifest = JSON.parse(readFileSync(join(repoRoot, manifestPath), 'utf8')) as { dshClient?: { platform?: unknown } }
+  for (const manifestPath of globSync('packages/*/*/package.json', { cwd: root }).sort()) {
+    const manifest = JSON.parse(readFileSync(join(root, manifestPath), 'utf8')) as { dshClient?: { platform?: unknown } }
    if (manifest.dshClient?.platform === 'web') dirs.push(dirname(manifestPath).split(sep).join('/'))
  }
  return dirs
 }

-const PLUGIN_DIRS = discoverPluginDirs()
-if (PLUGIN_DIRS.length === 0) {
-  console.error('dev-web: no dshClient (platform "web") packages found under packages/')
-  process.exit(1)
+/**
+ * Start the tsdown watch build used by `pnpm run dev:web`.
+ * @param root - repository or fixture root passed to tsdown.
+ * @param pluginDirs - workspace-relative package directories to watch.
+ * @param pollInterval - optional source-watcher polling interval in milliseconds.
+ * @returns live bundles whose async disposers stop every watcher.
+ */
+export async function watchClientPlugins(
+  root: string,
+  pluginDirs: readonly string[],
+  pollInterval?: number,
+): Promise<TsdownBundle[]> {
+  return build({
+    cwd: root,
+    workspace: [...pluginDirs],
+    watch: true,
+    ...pollInterval !== undefined
+      ? { inputOptions: { watch: { watcher: { usePolling: true, pollInterval } } } }
+      : {},
+  })
 }

-const args = process.argv.slice(2)
-const pollArg = args.find(a => a === '--poll' || a.startsWith('--poll='))
-if (args.some(a => a !== pollArg)) {
-  console.error('dev-web: usage: tsx scripts/dev-web.ts [--poll[=ms]]')
-  process.exit(1)
-}
-const pollInterval = pollArg === undefined ? undefined : Number(pollArg.split('=')[1] ?? '500')
-if (pollInterval !== undefined && (!Number.isInteger(pollInterval) || pollInterval <= 0)) {
-  console.error(`dev-web: invalid --poll interval "${pollArg ?? ''}"`)
-  process.exit(1)
-}
+const invokedPath = process.argv[1]
+const isMain = invokedPath !== undefined && import.meta.url === pathToFileURL(resolve(invokedPath)).href
+if (isMain) {
+  const pluginDirs = discoverPluginDirs()
+  if (pluginDirs.length === 0) {
+    console.error('dev-web: no dshClient (platform "web") packages found under packages/')
+    process.exit(1)
+  }

-await build({
-  cwd: repoRoot,
-  workspace: PLUGIN_DIRS,
-  watch: true,
-  // Rolldown watch options ride through inputOptions (tsdown has no watcher
-  // tuning of its own); polling is opt-in for network mounts without inotify.
-  ...pollInterval !== undefined
-    ? { inputOptions: { watch: { watcher: { usePolling: true, pollInterval } } } }
-    : {},
-})
-console.log(
-  `dev-web: watching ${String(PLUGIN_DIRS.length)} dshClient plugin packages`
-  + `${pollInterval !== undefined ? ` (polling ${String(pollInterval)}ms)` : ''}:\n  ${PLUGIN_DIRS.join('\n  ')}`,
-)
+  const args = process.argv.slice(2)
+  const pollArg = args.find(a => a === '--poll' || a.startsWith('--poll='))
+  if (args.some(a => a !== pollArg)) {
+    console.error('dev-web: usage: tsx scripts/dev-web.ts [--poll[=ms]]')
+    process.exit(1)
+  }
+  const pollInterval = pollArg === undefined ? undefined : Number(pollArg.split('=')[1] ?? '500')
+  if (pollInterval !== undefined && (!Number.isInteger(pollInterval) || pollInterval <= 0)) {
+    console.error(`dev-web: invalid --poll interval "${pollArg ?? ''}"`)
+    process.exit(1)
+  }
+
+  await watchClientPlugins(repoRoot, pluginDirs, pollInterval)
+  console.log(
+    `dev-web: watching ${String(pluginDirs.length)} dshClient plugin packages`
+    + `${pollInterval !== undefined ? ` (polling ${String(pollInterval)}ms)` : ''}:\n  ${pluginDirs.join('\n  ')}`,
+  )
+}
--- a/scripts/doc-budgets.manifest.json
+++ b/scripts/doc-budgets.manifest.json
@@ -1,7 +1,7 @@
 {
  "AGENTS.md": 1775,
  "docs/AGENTS.md": 1150,
-  "docs/architecture.md": 1920,
+  "docs/architecture.md": 2160,
  "docs/cordis-primer.md": 600,
  "docs/defensive-patterns.md": 550,
  "docs/testing.md": 1100,
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -159,7 +159,18 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
  SkillSummary: 'skills.md',
  SaveTextSpill: 'spill.md',
  SpillRef: 'spill.md',
+  ContinuableCreateRequest: 'subagent.md',
+  ContinuableCreateSpec: 'subagent.md',
+  ContinuableSetupContribution: 'subagent.md',
+  ContinuableStart: 'subagent.md',
+  ContinuableStartSpec: 'subagent.md',
+  CoordinatorMessageSource: 'subagent.md',
+  SubagentFollowupOptions: 'subagent.md',
+  SubagentListEntry: 'subagent.md',
  SubagentProvider: 'subagent.md',
+  SubagentReportDelivery: 'subagent.md',
+  SubagentReportMessageSource: 'subagent.md',
+  SubagentReportOptions: 'subagent.md',
  SubagentRun: 'subagent.md',
  SubagentService: 'subagent.md',
  SubagentStartRequest: 'subagent.md',
@@ -277,8 +288,8 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
  PromptAssembly: 'assembly result is owned by packages/core/system-prompt/README.md',
  ResumeAgentOptions: 'agent resume contract is owned by packages/core/agent/README.md',
  SessionForkSource: 'service-local fork input is owned by packages/core/session/src/index.ts',
-  SubagentRunEndInfo: 'event-local snapshot is owned by packages/subagent/subagent/src/index.ts',
-  SubagentRunInfo: 'event-local snapshot is owned by packages/subagent/subagent/src/index.ts',
+  SubagentRunEndInfo: 'event payload contract is owned by packages/subagent/subagent/src/types.ts',
+  SubagentRunInfo: 'event payload contract is owned by packages/subagent/subagent/src/types.ts',
  TelemetryRecord: 'seam-local record contract is owned by packages/telemetry/session-telemetry/src/index.ts',
  WorkflowAgentEndInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
  WorkflowAgentInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
@@ -302,7 +313,8 @@ export const CORDIS_CATALOG_POLICY: CordisCatalogPolicy = {
    { name: 'internal/listener', summary: 'A listener was registered.', source: 'vendor/cordis/src/events.ts:340' },
    { name: 'internal/dispatch', summary: 'An event is being dispatched to listeners.', source: 'vendor/cordis/src/events.ts:342' },
    { name: 'hmr/change', summary: 'A watched source file changed on disk.', source: 'vendor/hmr/src/index.ts:20' },
-    { name: 'hmr/reload', summary: 'Plugins are being reloaded after a change.', source: 'vendor/hmr/src/index.ts:21' },
+    { name: 'hmr/reload', summary: 'Plugins are being reloaded after a change.', source: 'vendor/hmr/src/index.ts:22' },
+    { name: 'hmr/config-update-failed', summary: 'A watched config-file refresh failed.', source: 'vendor/hmr/src/index.ts:29' },
    { name: 'exit', summary: 'The process is exiting on a signal.', source: 'vendor/loader/src/index.ts:23' },
    { name: 'loader/config-update', summary: 'The loader config tree changed.', source: 'vendor/loader/src/index.ts:24' },
    { name: 'loader/entry-init', summary: 'A config entry is being initialized.', source: 'vendor/loader/src/index.ts:25' },
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -424,11 +424,11 @@ const SERVICE_ROLES: ServiceRole[] = [
  {
    key: 'subagents',
    pkg: 'subagent',
-    title: 'Subagent provider registry',
+    title: 'Subagent provider and continuation service',
    mode: 'seam',
    implementations: ['subagent-spawn', 'subagent-fork', 'subagent-acp'],
-    consumers: ['tool-subagent', 'tool-ralph'],
-    note: 'Providers implement transports; tool-subagent exposes configured delegation while tool-ralph requires one fresh structured-output route.',
+    consumers: ['tool-subagent', 'tool-subagent-control', 'tool-ralph'],
+    note: 'Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route.',
  },
  {
    key: 'tasks',
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -11,7 +11,9 @@ import { basename, resolve } from 'node:path'
 import { Context } from 'cordis'
 import type { ToolSchema } from '@deepseek-ai/dsh-llm'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
-import SessionStore from '@deepseek-ai/dsh-session'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { createScope } from '@deepseek-ai/dsh-scope'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import SessionQuerySqlite from '@deepseek-ai/dsh-session-query-sqlite'
 import GoalService from '@deepseek-ai/dsh-goal'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
@@ -28,6 +30,9 @@ import * as WebSearchExa from '@deepseek-ai/dsh-web-search-exa'
 import * as WebFetchLocal from '@deepseek-ai/dsh-web-fetch-local'
 import SubagentService from '@deepseek-ai/dsh-subagent'
 import type { SubagentProvider } from '@deepseek-ai/dsh-subagent'
+import * as ToolSubagentControl from '@deepseek-ai/dsh-tool-subagent-control'
+import * as ToolSubagentListAgents from '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+import * as ToolSubagentReport from '@deepseek-ai/dsh-tool-subagent-report'
 import SkillService from '@deepseek-ai/dsh-skill'
 import * as SkillLocal from '@deepseek-ai/dsh-skill-local'
 import LocalTaskService from '@deepseek-ai/dsh-tasks-local'
@@ -106,10 +111,32 @@ function registerCatalogSubagentProvider(ctx: Context, name: string): void {
    capabilities: { outputSchema: true, depthLimit: true, toolFilter: true, persona: true },
    inheritsParentContext: false,
    start: () => Promise.reject(new Error('tool-catalog provider cannot start a child')),
+    // Declared so consumers configured for continuable background mode mount.
+    prepareContinuable: () => Promise.reject(new Error('tool-catalog provider cannot prepare a child')),
  }
  ctx.subagents.registerProvider(provider)
 }

+/** Minted child-scope keys for packages whose tools are never global. */
+const catalogChildScopes = new WeakMap<Context, Agent>()
+
+/**
+ * Install one scope-local tool package into an agent-like child scope for
+ * schema harvest, without starting a model, Agent loop, or persistence backend.
+ * @param ctx - catalog context owning the scope.
+ * @param mountScoped - package installer for the scoped context.
+ */
+async function mountCatalogChildScope(
+  ctx: Context,
+  mountScoped: (childCtx: Context) => void,
+): Promise<void> {
+  const key = { id: SessionId('tool-catalog-child') } as Agent
+  await ctx.plugin(Object.assign((inner: Context) => {
+    mountScoped(createScope(inner, key).ctx)
+  }, { inject: ['tools', 'systemPrompt', 'subagents'] }))
+  catalogChildScopes.set(ctx, key)
+}
+
 /**
 * Tool package plus its hand-maintained boot recipe. The caller mounts the
 * prompt and registry; each recipe supplies only package-specific seams and
@@ -120,8 +147,12 @@ interface ToolPackage {
  pkg: string
  /** The `packages/<group>/<dir>` leaf name — matched by the completeness guard. */
  dir: string
-  /** Repo-relative source path linked from the catalog entry. */
-  source: string
+  /**
+   * Repo-relative implementation source linked per harvested tool. Packages
+   * whose tools share one plugin may use a string; split plugins map each tool
+   * name to its own source.
+   */
+  source: string | Readonly<Record<string, string>>
  /** Services or owning runtime surfaces the package requires at execution time. */
  requires: string[]
  /** Session events or other visible state the tools write or affect. */
@@ -131,6 +162,8 @@ interface ToolPackage {
  /** Plug the injected seams + the tool plugin onto a context that already
   * carries `systemPrompt` + `tools`. */
  mount: (ctx: Context) => Promise<void>
+  /** Agent-like scope key whose tool view is catalogued instead of the global view. */
+  scope?: (ctx: Context) => Agent
  /**
   * Config for the caller's `ToolRegistry` mount. The registry itself ships a
   * model-facing tool (`run_code`, registered under a non-native `mode`), so
@@ -379,6 +412,46 @@ const TOOL_PACKAGES: ToolPackage[] = [
    note:
      'The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `apps/cli/config/base.cordis.yml` and `examples/acp-agent/cordis.yml`.',
  },
+  {
+    pkg: '@deepseek-ai/dsh-tool-subagent-control',
+    dir: 'tool-subagent-control',
+    source: {
+      list_agents: 'packages/subagent/tool-subagent-control/src/list-agents.ts',
+      send_message: 'packages/subagent/tool-subagent-control/src/index.ts',
+    },
+    requires: ['ctx.tools', 'ctx.subagents', 'ctx.sessionQuery (list_agents only)'],
+    writes: ['tool/call', 'tool/result', 'child session events through ctx.subagents'],
+    async mount(ctx) {
+      await ctx.plugin(SubagentService)
+      await ctx.plugin(LocalTaskService)
+      await ctx.plugin(AgentRegistry)
+      await ctx.plugin(SessionStore)
+      await ctx.plugin(SessionQuerySqlite, { path: ':memory:' })
+      await ctx.plugin(ToolSubagentControl)
+      await ctx.plugin(ToolSubagentListAgents)
+    },
+    note:
+      'The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` once, plus `list_agents` from its separately loaded `/list-agents` plugin (which additionally requires session query).',
+  },
+  {
+    pkg: '@deepseek-ai/dsh-tool-subagent-report',
+    dir: 'tool-subagent-report',
+    source: 'packages/subagent/tool-subagent-report/src/index.ts',
+    requires: ['ctx.subagents', 'a live continuable in-process child Agent'],
+    writes: ['tool/call', 'tool/result', 'a user-role message in the direct parent session'],
+    async mount(ctx) {
+      await ctx.plugin(AgentRegistry)
+      await ctx.plugin(SubagentService)
+      await mountCatalogChildScope(ctx, (childCtx) => {
+        ToolSubagentReport.installReportTool(childCtx, ctx, 'quiet')
+      })
+    },
+    scope: ctx => catalogChildScopes.get(ctx) as Agent,
+    note:
+      'Registered per continuable in-process child rather than globally, so this schema is visible only '
+      + 'inside such a child and survives its global `toolFilter`. The parent-facing `send_message` tool '
+      + 'is installed independently.',
+  },
  {
    pkg: '@deepseek-ai/dsh-tool-tasks',
    dir: 'tool-tasks',
@@ -442,7 +515,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
 /** One package's contribution to the catalog: its schemas plus attribution. */
 interface CatalogPackage {
  pkg: string
-  source: string
+  sources: Readonly<Record<string, string>>
  requires: string[]
  writes: string[]
  shippedNames?: string[]
@@ -494,10 +567,13 @@ export async function collectToolCatalog(packages: ToolPackage[] = TOOL_PACKAGES
      await ctx.plugin(SystemPrompt)
      await ctx.plugin(ToolRegistry, entry.toolsConfig ?? {})
      await entry.mount(ctx)
-      const schemas = ctx.tools.schemas().sort((a, b) => a.name.localeCompare(b.name))
+      const schemas = ctx.tools.schemas(entry.scope?.(ctx)).sort((a, b) => a.name.localeCompare(b.name))
      catalog.push({
        pkg: entry.pkg,
-        source: entry.source,
+        sources: Object.fromEntries(schemas.map(schema => [
+          schema.name,
+          toolSource(entry, schema.name),
+        ])),
        requires: entry.requires,
        writes: entry.writes,
        schemas,
@@ -511,6 +587,18 @@ export async function collectToolCatalog(packages: ToolPackage[] = TOOL_PACKAGES
  return catalog
 }

+/** Resolve one harvested tool to the plugin source that registered it. */
+function toolSource(entry: ToolPackage, toolName: string): string {
+  if (typeof entry.source === 'string') return entry.source
+  const source = entry.source[toolName]
+  if (source === undefined) {
+    throw new Error(
+      `gen-tool-catalog: ${entry.pkg} has no source mapping for harvested tool ${toolName}`,
+    )
+  }
+  return source
+}
+
 /** Render one tool's entry: name, description, JSON-Schema parameters, source. */
 function renderTool(schema: ToolSchema, source: string): string[] {
  const out = [`### \`${schema.name}\``, '']
@@ -553,7 +641,11 @@ export function render(catalog: ToolCatalog): string {
  ]
  for (const entry of catalog) {
    lines.push(`## \`${entry.pkg}\``, '')
-    for (const schema of entry.schemas) lines.push(...renderTool(schema, entry.source))
+    for (const schema of entry.schemas) {
+      // Collection validated that every harvested schema has a source.
+      const source = entry.sources[schema.name] as string
+      lines.push(...renderTool(schema, source))
+    }
    if (entry.note) lines.push(entry.note, '')
  }
  return lines.join('\n')
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -215,7 +215,7 @@ fi

 # pnpm is the only dependency we offer to install for you.
 if command -v pnpm >/dev/null 2>&1; then
-  info "pnpm $(pnpm --version 2>/dev/null) ... ok"
+  info "pnpm $(pnpm --version) ... ok"
 else
  warn "pnpm is not installed."
  if confirm "Install pnpm now?" Y; then
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -1064,6 +1064,51 @@
      "symbol": "SubagentStartRequest",
      "source": "packages/subagent/subagent/src/types.ts"
    },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "ResolvedSubagentStartRequest",
+      "source": "packages/subagent/subagent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "CoordinatorMessageSource",
+      "source": "packages/subagent/subagent/src/continuation.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "SubagentReportMessageSource",
+      "source": "packages/subagent/subagent/src/continuation.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "SubagentReportDelivery",
+      "source": "packages/subagent/subagent/src/continuation.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "SubagentReportOptions",
+      "source": "packages/subagent/subagent/src/continuation.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "SubagentFollowupOptions",
+      "source": "packages/subagent/subagent/src/continuation.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "ContinuableStart",
+      "source": "packages/subagent/subagent/src/continuation.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "ContinuableCreateRequest",
+      "source": "packages/subagent/subagent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/subagent.md",
+      "symbol": "ContinuableCreateSpec",
+      "source": "packages/subagent/subagent/src/types.ts"
+    },
    {
      "doc": "docs/core-data-structures/subagent.md",
      "symbol": "SubagentResult",
--- a/scripts/verify-vendored-links.ts
+++ b/scripts/verify-vendored-links.ts
@@ -0,0 +1,72 @@
+/**
+ * Verify that pnpm-lock.yaml resolves every vendored package name to its
+ * workspace `link:` — never a registry copy. `linkWorkspacePackages: true`
+ * (pnpm-workspace.yaml) makes matching upstream semver ranges resolve to the
+ * pinned vendored sources; a registry copy of the same name coexisting with
+ * the vendored one silently forks the framework layer (vendor/README.md).
+ */
+import { readdir, readFile } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import * as yaml from 'js-yaml'
+
+const root = resolve(import.meta.dirname, '..')
+
+async function vendoredNames(): Promise<Set<string>> {
+  const names = new Set<string>()
+  for (const entry of await readdir(join(root, 'vendor'), { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue
+    let manifest: { name?: string }
+    try {
+      manifest = JSON.parse(await readFile(join(root, 'vendor', entry.name, 'package.json'), 'utf8')) as { name?: string }
+    } catch {
+      continue // not a package directory (e.g. vendor/README.md siblings)
+    }
+    if (manifest.name !== undefined) names.add(manifest.name)
+  }
+  return names
+}
+
+interface Lockfile {
+  importers?: Record<string, Record<string, unknown>>
+  packages?: Record<string, unknown>
+  snapshots?: Record<string, unknown>
+}
+
+const names = await vendoredNames()
+if (names.size === 0) throw new Error('verify-vendored-links: no vendored package manifests found under vendor/')
+const lockfile = yaml.load(await readFile(join(root, 'pnpm-lock.yaml'), 'utf8')) as Lockfile
+
+const violations: string[] = []
+
+// Importer resolutions: every dependency entry naming a vendored package must
+// resolve to a link:, or the build silently uses a registry copy.
+for (const [importer, sections] of Object.entries(lockfile.importers ?? {})) {
+  for (const [section, dependencies] of Object.entries(sections)) {
+    if (typeof dependencies !== 'object' || dependencies === null) continue
+    for (const [dependency, entry] of Object.entries(dependencies as Record<string, { version?: string }>)) {
+      if (!names.has(dependency)) continue
+      const version = entry.version ?? ''
+      if (!version.startsWith('link:')) {
+        violations.push(`${importer} ${section}.${dependency} resolves to ${JSON.stringify(version)} (expected link:)`)
+      }
+    }
+  }
+}
+
+// Package/snapshot keys: a registry copy materializes as a `<name>@<version>`
+// key; vendored names must never appear there at all.
+for (const section of ['packages', 'snapshots'] as const) {
+  for (const key of Object.keys(lockfile[section] ?? {})) {
+    const atIndex = key.lastIndexOf('@')
+    if (atIndex <= 0) continue
+    const packageName = key.slice(0, atIndex)
+    if (names.has(packageName)) violations.push(`${section} entry ${key} is a registry copy of a vendored package`)
+  }
+}
+
+if (violations.length > 0) {
+  console.error(`verify-vendored-links: ${String(violations.length)} lockfile resolution(s) bypass the vendored workspaces:`)
+  for (const violation of violations) console.error(`  - ${violation}`)
+  process.exit(1)
+}
+console.log(`verify-vendored-links: all ${String(names.size)} vendored package names resolve to workspace links.`)