Merge remote-tracking branch 'origin/master' into feat/web-workspace-file-links

# Conflicts:
#	packages/client/ui-conversation/README.i18n.yaml
#	packages/client/ui-conversation/src/client/chat/ToolRow.module.css
#	packages/host/apiproxy/src/native-path-opener.ts

scripts/gen-config-catalog.ts

@@ -126,12 +126,13 @@ function loadFile(abs: string, rel: string, cache: Map<string, FileCtx>): FileCt
 }
 
 /** A type declaration a paste can contain. */
-type TypeDecl = ts.InterfaceDeclaration | ts.TypeAliasDeclaration
+type TypeDecl = ts.InterfaceDeclaration | ts.TypeAliasDeclaration | ts.EnumDeclaration
 
-/** Find an interface/type-alias declaration by name in a file, or null. */
+/** Find a pasteable type declaration by name in a file, or null. */
 function findTypeDecl(ctx: FileCtx, name: string): TypeDecl | null {
   for (const stmt of ctx.sf.statements) {
-    if ((ts.isInterfaceDeclaration(stmt) || ts.isTypeAliasDeclaration(stmt)) && stmt.name.text === name) return stmt
+    if ((ts.isInterfaceDeclaration(stmt) || ts.isTypeAliasDeclaration(stmt) || ts.isEnumDeclaration(stmt))
+      && stmt.name.text === name) return stmt
   }
   return null
 }
@@ -207,7 +208,7 @@ function checkMemberDocs(ctx: FileCtx, decl: TypeDecl, violations: string[]): vo
     else ts.forEachChild(type, (n) => { walkNested(n, path) })
   }
   if (ts.isInterfaceDeclaration(decl)) walkMembers(decl.members, decl.name.text)
-  else walkNested(decl.type, decl.name.text)
+  else if (ts.isTypeAliasDeclaration(decl)) walkNested(decl.type, decl.name.text)
 }
 
 /** Cross-file resolution context for the schema-path check. */

scripts/gen-doc-graphs.ts

@@ -320,8 +320,8 @@ const SERVICE_ROLES: ServiceRole[] = [
     title: 'Subprocess seam',
     mode: 'seam',
     implementations: ['subprocess-local'],
-    consumers: ['bash-local', 'bash-sandbox', 'lsp-local', 'subagent-acp'],
-    note: 'The bash executors, the LSP host, and the ACP subagent backend spawn their children through ctx.subprocess; the service owns tree lifetime, stdio dispositions (pipes, inherit, bounded spill-backed collection), and kill escalation.',
+    consumers: ['bash-local', 'bash-sandbox', 'lsp-local', 'subagent-acp', 'subagent-codex', 'subagent-claude-code'],
+    note: 'The bash executors, the LSP host, and the out-of-process ACP, Codex, and Claude Code subagent backends spawn their children through ctx.subprocess; the service owns tree lifetime, stdio dispositions (pipes, inherit, bounded spill-backed collection), and kill escalation.',
   },
   {
     key: 'bash',
@@ -417,7 +417,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'subagent',
     title: 'Subagent provider and continuation service',
     mode: 'seam',
-    implementations: ['subagent-spawn', 'subagent-fork', 'subagent-acp'],
+    implementations: ['subagent-spawn', 'subagent-fork', 'subagent-acp', 'subagent-codex', 'subagent-claude-code', 'subagent-dsh-sdk'],
     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.',
   },

scripts/gen-third-party-notices.spec.ts

@@ -2,7 +2,20 @@ import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSyn
 import { join, resolve } from 'node:path'
 import { tmpdir } from 'node:os'
 import { describe, expect, it } from 'vitest'
-import { collectPythonDependencies, isPermissive, type Manifest, manifestPatterns, parsePyprojectRequirements, parseVendoredRows, render, tierExternalDeps, virtualManifest } from './gen-third-party-notices.ts'
+import {
+  CLAUDE_AGENT_SDK_PACKAGE,
+  claudeDistributionFromManifest,
+  collectPythonDependencies,
+  isOwnerAuthorizedRuntime,
+  isPermissive,
+  type Manifest,
+  manifestPatterns,
+  parsePyprojectRequirements,
+  parseVendoredRows,
+  render,
+  tierExternalDeps,
+  virtualManifest,
+} from './gen-third-party-notices.ts'
 
 const root = resolve(import.meta.dirname, '..')
 
@@ -12,7 +25,9 @@ describe('THIRD_PARTY_NOTICES.md', () => {
   // Pre-commit regenerates the file whenever a manifest is staged, so reaching
   // this assertion means the notices were committed without that hook.
   it('matches what the generator produces from the current manifests', () => {
-    expect(readFileSync(resolve(root, 'THIRD_PARTY_NOTICES.md'), 'utf8'), 'stale notices — run `pnpm run gen-third-party-notices`').toBe(render())
+    const generated = render()
+    expect(generated).toContain('It depends on the third-party software listed below.')
+    expect(readFileSync(resolve(root, 'THIRD_PARTY_NOTICES.md'), 'utf8'), 'stale notices — run `pnpm run gen-third-party-notices`').toBe(generated)
   })
 })
 
@@ -223,7 +238,14 @@ describe('collectPythonDependencies', () => {
 describe('isPermissive', () => {
   it('accepts the licenses this project ships and rejects copyleft or unknown ones', () => {
     expect(['MIT', 'ISC', 'BSD-3-Clause', 'Apache-2.0', 'MIT / Apache-2.0', '(MIT OR CC0-1.0)'].every(isPermissive)).toBe(true)
-    expect(['LGPL-3.0-only', 'MPL-2.0', 'GPL-3.0-or-later', 'SEE LICENSE IN LICENSE'].some(isPermissive)).toBe(false)
+    expect([
+      'LGPL-3.0-only',
+      'MPL-2.0',
+      'GPL-3.0-or-later',
+      'SEE LICENSE IN LICENSE',
+      'SEE LICENSE IN README.md',
+      'SEE LICENSE IN LICENSE.md',
+    ].some(isPermissive)).toBe(false)
   })
 
   it('requires every operand of an AND, so a copyleft conjunct cannot ride along', () => {
@@ -245,6 +267,66 @@ describe('isPermissive', () => {
   })
 })
 
+describe('official Claude distribution authorization', () => {
+  it('authorizes only the direct SDK identity without relabeling its license', () => {
+    expect(isOwnerAuthorizedRuntime(CLAUDE_AGENT_SDK_PACKAGE)).toBe(true)
+    expect(isOwnerAuthorizedRuntime(`${CLAUDE_AGENT_SDK_PACKAGE}-linux-x64`))
+      .toBe(false)
+    expect(isOwnerAuthorizedRuntime('@anthropic-ai/unrelated')).toBe(false)
+    expect(isPermissive('SEE LICENSE IN README.md')).toBe(false)
+  })
+
+  it('derives version-independent platform payloads from the official SDK manifest', () => {
+    expect(claudeDistributionFromManifest({
+      name: CLAUDE_AGENT_SDK_PACKAGE,
+      version: '9.8.7',
+      license: 'future declared terms',
+      claudeCodeVersion: '6.5.4',
+      optionalDependencies: {
+        [`${CLAUDE_AGENT_SDK_PACKAGE}-linux-x64`]: '9.8.7',
+        [`${CLAUDE_AGENT_SDK_PACKAGE}-darwin-arm64`]: '9.8.7',
+      },
+    })).toEqual({
+      sdkVersion: '9.8.7',
+      claudeCodeVersion: '6.5.4',
+      payloads: [
+        {
+          name: `${CLAUDE_AGENT_SDK_PACKAGE}-darwin-arm64`,
+          version: '9.8.7',
+        },
+        {
+          name: `${CLAUDE_AGENT_SDK_PACKAGE}-linux-x64`,
+          version: '9.8.7',
+        },
+      ],
+    })
+  })
+
+  it('rejects a wrong SDK identity, missing payloads, and unrelated optionals', () => {
+    expect(() => claudeDistributionFromManifest({
+      name: '@anthropic-ai/unrelated',
+      version: '1.0.0',
+      claudeCodeVersion: '1.0.0',
+      optionalDependencies: {
+        [`${CLAUDE_AGENT_SDK_PACKAGE}-linux-x64`]: '1.0.0',
+      },
+    })).toThrow(`expected ${CLAUDE_AGENT_SDK_PACKAGE} manifest`)
+    expect(() => claudeDistributionFromManifest({
+      name: CLAUDE_AGENT_SDK_PACKAGE,
+      version: '1.0.0',
+      claudeCodeVersion: '1.0.0',
+    })).toThrow('declares no optional platform payloads')
+    expect(() => claudeDistributionFromManifest({
+      name: CLAUDE_AGENT_SDK_PACKAGE,
+      version: '1.0.0',
+      claudeCodeVersion: '1.0.0',
+      optionalDependencies: {
+        '@anthropic-ai/unrelated': '1.0.0',
+      },
+    })).toThrow('outside its authorized platform-payload identity')
+  })
+})
+
 describe('manifestPatterns', () => {
   it('derives globs from the declared members, so a new member area is read', () => {
     expect(manifestPatterns(['packages/*/*', 'tools/*'], ['packages/*'])).toEqual([

scripts/gen-third-party-notices.ts

@@ -49,6 +49,21 @@ const FIRST_PARTY = new Set([
   'node-addon-landlock-run-linux-x64',
 ])
 
+/** Official SDK identity covered by the project's narrow owner authorization. */
+export const CLAUDE_AGENT_SDK_PACKAGE = '@anthropic-ai/claude-agent-sdk'
+const CLAUDE_PLATFORM_PACKAGE_PREFIX = `${CLAUDE_AGENT_SDK_PACKAGE}-`
+const CLAUDE_PLATFORM_DECLARED_LICENSE = 'SEE LICENSE IN LICENSE.md'
+
+/**
+ * Whether a non-permissive runtime declaration has an identity-scoped owner
+ * authorization. This does not reclassify its terms as permissive.
+ * @param name - exact npm package identity.
+ * @returns true only for the official Claude Agent SDK package.
+ */
+export function isOwnerAuthorizedRuntime(name: string): boolean {
+  return name === CLAUDE_AGENT_SDK_PACKAGE
+}
+
 /**
  * Metadata overrides where the installed manifest is wrong or unreachable.
  * Each entry documents why the store cannot answer.
@@ -92,6 +107,7 @@ const BUILD_TIME_TOOLS = [
 /** The `package.json` fields this generator reads. */
 export interface Manifest {
   name?: string
+  version?: string
   private?: boolean
   license?: string
   dependencies?: Record<string, string>
@@ -164,7 +180,74 @@ function loadWorkspaceManifests(): { manifests: Map<string, Manifest>; names: Se
   return { manifests, names }
 }
 
-type VirtualManifest = Manifest & { license?: string; repository?: string | { url?: string }; homepage?: string }
+type VirtualManifest = Manifest & {
+  claudeCodeVersion?: string
+  license?: string
+  repository?: string | { url?: string }
+  homepage?: string
+}
+
+/** One platform payload declared by the official Claude Agent SDK. */
+export interface ClaudePlatformPayload {
+  readonly name: string
+  readonly version: string
+}
+
+/** Current SDK and CLI distribution facts derived from the installed SDK manifest. */
+export interface ClaudeDistribution {
+  readonly sdkVersion: string
+  readonly claudeCodeVersion: string
+  readonly payloads: ClaudePlatformPayload[]
+}
+
+function requiredManifestString(
+  value: string | undefined,
+  field: string,
+): string {
+  if (value === undefined || value.length === 0) {
+    throw new Error(`gen-third-party-notices: ${CLAUDE_AGENT_SDK_PACKAGE} has no ${field}.`)
+  }
+  return value
+}
+
+/**
+ * Derive the official platform payload set without a version or platform
+ * allowlist. Only identities in the SDK's own package namespace are covered.
+ * @param manifest - installed official SDK manifest.
+ * @returns current SDK, CLI, and optional platform payload facts.
+ */
+export function claudeDistributionFromManifest(
+  manifest: VirtualManifest,
+): ClaudeDistribution {
+  if (manifest.name !== CLAUDE_AGENT_SDK_PACKAGE) {
+    throw new Error(
+      `gen-third-party-notices: expected ${CLAUDE_AGENT_SDK_PACKAGE} manifest, got ${JSON.stringify(manifest.name)}.`,
+    )
+  }
+  const sdkVersion = requiredManifestString(manifest.version, 'version')
+  const claudeCodeVersion = requiredManifestString(
+    manifest.claudeCodeVersion,
+    'claudeCodeVersion',
+  )
+  const entries = Object.entries(manifest.optionalDependencies ?? {})
+  if (entries.length === 0) {
+    throw new Error(
+      `gen-third-party-notices: ${CLAUDE_AGENT_SDK_PACKAGE} declares no optional platform payloads.`,
+    )
+  }
+  const payloads = entries.map(([name, version]) => {
+    if (!name.startsWith(CLAUDE_PLATFORM_PACKAGE_PREFIX)) {
+      throw new Error(
+        `gen-third-party-notices: ${CLAUDE_AGENT_SDK_PACKAGE} optional dependency ${name} is outside its authorized platform-payload identity.`,
+      )
+    }
+    return {
+      name,
+      version: requiredManifestString(version, `${name} optional dependency version`),
+    }
+  }).sort((left, right) => left.name.localeCompare(right.name))
+  return { sdkVersion, claudeCodeVersion, payloads }
+}
 
 /**
  * Resolve one package's manifest inside a pnpm virtual store. The prefix scan
@@ -193,9 +276,8 @@ export function virtualManifest(virtual: string, name: string): VirtualManifest
   return undefined
 }
 
-/** License and repository URL for an installed external package, from the pnpm store. */
-function installedMetadata(name: string): { license: string; repo: string } {
-  const override = OVERRIDES[name]
+/** Resolve one installed external package manifest from either pnpm store. */
+function installedManifest(name: string): VirtualManifest | undefined {
   let manifest: (Manifest & { license?: string; repository?: string | { url?: string }; homepage?: string }) | undefined
   // The nested Landlock workspace installs into its own store, so a package
   // only that workspace depends on is unreachable from the root one.
@@ -210,6 +292,13 @@ function installedMetadata(name: string): { license: string; repo: string } {
     manifest = virtualManifest(virtual, name)
     if (manifest !== undefined) break
   }
+  return manifest
+}
+
+/** License and repository URL for an installed external package, from the pnpm store. */
+function installedMetadata(name: string): { license: string; repo: string } {
+  const override = OVERRIDES[name]
+  const manifest = installedManifest(name)
   const license = override?.license ?? manifest?.license
   const rawRepo = typeof manifest?.repository === 'string' ? manifest.repository : manifest?.repository?.url ?? manifest?.homepage
   const repo = override?.repo ?? normalizeRepo(rawRepo)
@@ -219,6 +308,37 @@ function installedMetadata(name: string): { license: string; repo: string } {
   return { license, repo }
 }
 
+function collectClaudeDistribution(): ClaudeDistribution {
+  const manifest = installedManifest(CLAUDE_AGENT_SDK_PACKAGE)
+  if (manifest === undefined) {
+    throw new Error(
+      `gen-third-party-notices: cannot resolve ${CLAUDE_AGENT_SDK_PACKAGE}; run \`pnpm install\`.`,
+    )
+  }
+  const distribution = claudeDistributionFromManifest(manifest)
+  let installedPayloads = 0
+  for (const payload of distribution.payloads) {
+    const installed = installedManifest(payload.name)
+    if (installed === undefined) continue
+    installedPayloads += 1
+    if (
+      installed.name !== payload.name
+      || installed.version !== payload.version
+      || installed.license !== CLAUDE_PLATFORM_DECLARED_LICENSE
+    ) {
+      throw new Error(
+        `gen-third-party-notices: installed ${payload.name} does not match its SDK-declared version and ${CLAUDE_PLATFORM_DECLARED_LICENSE} license field.`,
+      )
+    }
+  }
+  if (installedPayloads === 0) {
+    throw new Error(
+      'gen-third-party-notices: no SDK-declared Claude platform payload is installed; install optional dependencies before regenerating.',
+    )
+  }
+  return distribution
+}
+
 /** Normalize a manifest repository/homepage value to a browsable https URL. */
 function normalizeRepo(raw: string | undefined): string | undefined {
   if (raw === undefined || raw === '') return undefined
@@ -519,6 +639,26 @@ function renderNpmTable(deps: ExternalDep[]): string {
   return lines.join('\n')
 }
 
+function renderClaudeDistribution(
+  distribution: ClaudeDistribution | undefined,
+): string {
+  if (distribution === undefined) return ''
+  const rows = distribution.payloads.map(payload =>
+    `| [\`${payload.name}\`](https://www.npmjs.com/package/${payload.name}) | ${payload.version} | ${CLAUDE_PLATFORM_DECLARED_LICENSE} |`,
+  )
+  return `
+## Official Claude Code platform payloads
+
+The project owner authorizes distribution of every version of the official \`${CLAUDE_AGENT_SDK_PACKAGE}\` package and the official Claude Code CLI/platform payloads that each version declares through \`optionalDependencies\`. This identity-scoped authorization does not classify their declared terms as permissive and does not cover any unrelated runtime package; version, declared-license, and payload-set changes still require the ordinary dependency, lockfile, compatibility, terms, and notices review.
+
+The installed SDK ${distribution.sdkVersion} declares the following optional platform packages. Each carries the official Claude Code ${distribution.claudeCodeVersion} executable; the package identities and versions come from the SDK manifest, while the declared license field is verified against the platform payload installed for the current host.
+
+| Optional platform package | Version | Declared license |
+| --- | --- | --- |
+${rows.join('\n')}
+`
+}
+
 /**
  * Render the complete notices document.
  * @returns the exact bytes `THIRD_PARTY_NOTICES.md` must hold.
@@ -531,11 +671,19 @@ export function render(): string {
   const vendored = collectVendored()
   const python = collectPython()
   const patched = collectPatched()
+  const claudeDistribution = runtimeDeps.some(
+    dep => dep.name === CLAUDE_AGENT_SDK_PACKAGE,
+  )
+    ? collectClaudeDistribution()
+    : undefined
 
   const nonPermissiveDev = devDeps.filter(dep => !isPermissive(dep.license))
   // A copyleft license reaching a shipped surface is a distribution decision,
   // not a rendering detail; the notices cannot quietly absorb it.
-  const nonPermissiveRuntime = runtimeDeps.filter(dep => !isPermissive(dep.license))
+  const nonPermissiveRuntime = runtimeDeps.filter(dep =>
+    !isPermissive(dep.license)
+    && !isOwnerAuthorizedRuntime(dep.name),
+  )
   if (nonPermissiveRuntime.length > 0) {
     throw new Error(`gen-third-party-notices: runtime ${nonPermissiveRuntime.map(dep => `${dep.name} (${dep.license})`).join(', ')} is not a permissive license; review the distribution terms and record the decision before regenerating.`)
   }
@@ -546,9 +694,9 @@ export function render(): string {
 
 # Third-Party Notices
 
-DeepSeek Harness is licensed under [BSD 3-Clause](LICENSE). It depends on the third-party open-source software listed below. Each project remains under its own license; nothing in this file changes those terms.
+DeepSeek Harness is licensed under [BSD 3-Clause](LICENSE). It depends on the third-party software listed below. Each project remains under its own license; nothing in this file changes those terms.
 
-This file lists **direct** dependencies declared by the workspace. It is generated from the workspace manifests by \`scripts/gen-third-party-notices.ts\`: a pre-commit hook regenerates it whenever a staged file changes one of its inputs, and \`scripts/gen-third-party-notices.spec.ts\` asserts in the test lane that the committed bytes match. Deleting a manifest runs no hook, so that case is caught by the assertion instead. Run \`pnpm run verify-third-party-notices\` for the standalone check.
+This file lists **direct** dependencies declared by the workspace and the explicitly disclosed official Claude platform payload closure. It is generated from the workspace manifests by \`scripts/gen-third-party-notices.ts\`: a pre-commit hook regenerates it whenever a staged file changes one of its inputs, and \`scripts/gen-third-party-notices.spec.ts\` asserts in the test lane that the committed bytes match. Deleting a manifest runs no hook, so that case is caught by the assertion instead. Run \`pnpm run verify-third-party-notices\` for the standalone check.
 
 The complete npm transitive closure, with exact pinned versions, is recorded in [\`pnpm-lock.yaml\`](pnpm-lock.yaml) — inspect it with \`pnpm licenses list\`. The Python closure is recorded in [\`python/sdk/uv.lock\`](python/sdk/uv.lock), and the Landlock launcher workspace keeps its own in [\`native/landlock-run/pnpm-lock.yaml\`](native/landlock-run/pnpm-lock.yaml).
 
@@ -569,6 +717,7 @@ ${renderNpmTable(runtimeDeps)}
 pnpm applies local patches to the following packages at install time, so shipped artifacts carry modified copies; each patch file is the complete record of the modification:
 
 ${patchedLines.join('\n')}
+${renderClaudeDistribution(claudeDistribution)}
 
 ## Development-only npm dependencies
 

scripts/gen-tool-catalog.ts

@@ -14,6 +14,7 @@ import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { createScope } from '@deepseek-ai/dsh-scope'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import SessionQuerySqlite from '@deepseek-ai/dsh-session-query-sqlite'
 import GoalService from '@deepseek-ai/dsh-goal'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
@@ -175,7 +176,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
     toolsConfig: { mode: 'code' },
     async mount() {},
     note:
-      'Owned by the tool registry as a reserved transport outside filterable capability layers under `mode: code` / `mode: both` (see the Code Mode Agent Note). Under `code` it is the registry\'s only wire contribution; the other visible capabilities are declared in a generated TypeScript SDK section, and a program calls them through bindings scheduled under the native concurrency contract (submission-ordered starts and policy; concurrency-safe bodies overlap up to `maxParallelSubCalls`) that re-enter the complete guarded tool pipeline and link each nested execution to this outer result.',
+      'Owned by the tool registry as a reserved transport outside filterable capability layers under `mode: code` / `mode: both` (see the Code Mode Agent Note). Under `code` it is the registry\'s only wire contribution; the other visible capabilities are declared in a generated SDK section in the loaded runtime\'s language, and a program calls them through bindings scheduled under the native concurrency contract (submission-ordered starts and policy; concurrency-safe bodies overlap up to `maxParallelSubCalls`) that re-enter the complete guarded tool pipeline and link each nested execution to this outer result.',
   },
   {
     pkg: '@deepseek-ai/dsh-plan-mode',
@@ -401,19 +402,19 @@ const TOOL_PACKAGES: ToolPackage[] = [
       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)'],
+    requires: ['ctx.tools', 'ctx.subagents', 'ctx.sessionProjections (list_agents catalog rows)'],
     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(SessionProjectionRegistry)
       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).',
+      '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 (whose catalog rows are served through the sessionProjections registry).',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-subagent-report',
@@ -454,10 +455,10 @@ const TOOL_PACKAGES: ToolPackage[] = [
     requires: ['ctx.tools', 'owning Agent session'],
     writes: ['tool/call', 'todo/write', 'tool/result'],
     async mount(ctx) {
-      await ctx.plugin(ToolTodo)
+      await ctx.plugin(ToolTodo, { allowParallelInProgress: true })
     },
     note:
-      'todo_write is session-owned state; UIs render the latest todo/write event as a checklist.',
+      'todo_write is session-owned state; UIs render the latest todo/write event as a checklist. `allowParallelInProgress` is required with no default, so the catalog states its choice: `true`, whose description invites several `in_progress` items. A deployment choosing `false` receives the same tool with a description asking for exactly one active task.',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-workflow',
@@ -610,7 +611,7 @@ export function render(catalog: ToolCatalog): string {
     '',
     'This file is GENERATED and verified fresh by `pnpm run verify-tool-catalog` (part of `doc-sync`) — do not edit it by hand. Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each tool plugin on a real context and reads `ctx.tools.schemas()`, because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools). A completeness guard globs `packages/*/tool-*` and fails if any package is missing from the generator\'s boot manifest, so a new tool cannot be silently undocumented. See [the tool-schema-catalog Agent Note](../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md).',
     '',
-    'Scope: shipped product tools under `packages/*/tool-*`, each booted with its DEFAULT config. The registered tool NAME can be a load-time config (e.g. `tool-subagent`\'s `toolName`), so a deployment may surface a package under a different or additional name — a per-package note records those shipped aliases where they exist. The `examples/` demo tools (e.g. `echo`) are excluded, matching the cordis catalog\'s packages-only scope.',
+    'Scope: shipped product tools under `packages/*/tool-*`, each booted with its DEFAULT config, except where a Config field is REQUIRED with no default — there the generator must choose, and the per-package note records which branch this page shows. The registered tool NAME can be a load-time config (e.g. `tool-subagent`\'s `toolName`), so a deployment may surface a package under a different or additional name — a per-package note records those shipped aliases where they exist. The `examples/` demo tools (e.g. `echo`) are excluded, matching the cordis catalog\'s packages-only scope.',
     '',
     '## Tool Package Map',
     '',

scripts/project-doc-site.spec.ts

@@ -1,12 +1,14 @@
 /** Tests for the documentation website projection adapter. */
 
 import { execFileSync } from 'node:child_process'
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { docsPages, type DocsPage } from '../website/docs.ts'
-import { addProjectionFrontmatter, projectedPageContent, rewriteMarkdown } from './project-doc-site.ts'
+import {
+  addProjectionFrontmatter, projectedPageContent, publishableImage, rewriteMarkdown,
+} from './project-doc-site.ts'
 
 const roots: string[] = []
 const repositoryRoot = resolve(import.meta.dirname, '..')
@@ -63,6 +65,32 @@ describe('website source layout', () => {
   })
 })
 
+describe('publishableImage', () => {
+  it('accepts a regular file inside the repository', () => {
+    const { root } = fixture()
+    const real = realpathSync(join(root, 'packages/logo.svg'))
+    expect(publishableImage(join(root, 'packages/logo.svg'), realpathSync(root))).toBe(real)
+  })
+
+  it('refuses a target whose real path escapes the repository', () => {
+    // Publication copies the bytes onto the site, so a reference reaching a
+    // build-machine file must not be treated as an image the repository owns.
+    const { root } = fixture()
+    const outside = mkdtempSync(join(tmpdir(), 'dsh-doc-site-outside-'))
+    roots.push(outside)
+    writeFileSync(join(outside, 'secret.png'), 'not really a png\n')
+    symlinkSync(join(outside, 'secret.png'), join(root, 'packages/linked.png'))
+
+    expect(publishableImage(join(root, 'packages/linked.png'), realpathSync(root))).toBeUndefined()
+    expect(publishableImage(join(outside, 'secret.png'), realpathSync(root))).toBeUndefined()
+  })
+
+  it('refuses a directory', () => {
+    const { root } = fixture()
+    expect(publishableImage(join(root, 'packages'), realpathSync(root))).toBeUndefined()
+  })
+})
+
 describe('rewriteMarkdown', () => {
   it('maps published pages and pins unpublished source links', () => {
     const { root, pages } = fixture()
@@ -93,7 +121,7 @@ describe('rewriteMarkdown', () => {
     })).toBe('[B](./reference-root/b.md)\n')
   })
 
-  it('uses raw GitHub content for unpublished images', () => {
+  it('uses raw GitHub content for unpublished images when nothing places them', () => {
     const { root, pages } = fixture()
     expect(rewriteMarkdown('![logo](../packages/logo.svg)\n', {
       locale: 'en',
@@ -105,6 +133,57 @@ describe('rewriteMarkdown', () => {
     })).toBe('![logo](https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/abc123/packages/logo.svg)\n')
   })
 
+  it('hands an image to the placer and uses the URL it returns', () => {
+    // A raw GitHub URL cannot serve a private repository, so the site build
+    // carries images itself; the placer is what puts them there. The stand-in
+    // derives its URL the way the real one does, so a placer that stopped
+    // returning the basename would fail here rather than pass on a constant.
+    const { root, pages } = fixture()
+    const placed: string[] = []
+    expect(rewriteMarkdown('![logo](../packages/logo.svg)\n', {
+      locale: 'en',
+      sourcePath: 'docs/a.md',
+      route: 'en/a.md',
+      pages,
+      repoRoot: root,
+      repositoryRef: 'abc123',
+      placeImage: (absPath) => {
+        const name = absPath.split('/').pop() ?? ''
+        placed.push(name)
+        return `./${name}`
+      },
+    })).toBe('![logo](./logo.svg)\n')
+    expect(placed).toEqual(['logo.svg'])
+  })
+
+  it('keeps a placed image\u2019s query or fragment', () => {
+    // An SVG view fragment and a Vite query both change what the reference
+    // means, and the GitHub branch has always carried them.
+    const { root, pages } = fixture()
+    expect(rewriteMarkdown('![logo](../packages/logo.svg#view)\n', {
+      locale: 'en',
+      sourcePath: 'docs/a.md',
+      route: 'en/a.md',
+      pages,
+      repoRoot: root,
+      repositoryRef: 'abc123',
+      placeImage: absPath => `./${absPath.split('/').pop() ?? ''}`,
+    })).toBe('![logo](./logo.svg#view)\n')
+  })
+
+  it('leaves a published page link to the route even when a placer exists', () => {
+    const { root, pages } = fixture()
+    expect(rewriteMarkdown('[B](b.md)\n', {
+      locale: 'en',
+      sourcePath: 'docs/a.md',
+      route: 'en/a.md',
+      pages,
+      repoRoot: root,
+      repositoryRef: 'abc123',
+      placeImage: () => { throw new Error('a page link must not be placed as an asset') },
+    })).toBe('[B](./reference/b.md)\n')
+  })
+
   it('does not rewrite Markdown-looking text inside code fences', () => {
     const { root, pages } = fixture()
     const source = '```md\n[B](b.md)\n```\n'

scripts/project-doc-site.ts

@@ -5,8 +5,10 @@
  * tier, while this adapter rewrites cross-source links for the public site.
  */
 
-import { existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
-import { dirname, extname, posix, relative, resolve, sep } from 'node:path'
+import {
+  copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync,
+} from 'node:fs'
+import { basename, dirname, extname, posix, relative, resolve, sep } from 'node:path'
 import { fromMarkdown } from 'mdast-util-from-markdown'
 import { gfmFromMarkdown } from 'mdast-util-gfm'
 import { gfm } from 'micromark-extension-gfm'
@@ -38,6 +40,15 @@ export interface RewriteMarkdownOptions {
   pages: DocsPage[]
   repoRoot: string
   repositoryRef: string
+  /**
+   * Place one referenced image beside the projected page and return the URL to
+   * reach it from that page. A GitHub raw URL cannot serve this repository —
+   * `raw.githubusercontent.com` answers 404 for a private one, and no reader of
+   * the site is authenticated to it — so an image travels into the generated
+   * tree and Vite bundles it like any other site asset. Omitted by callers that
+   * only rewrite text, which then leave images pointing at the repository.
+   */
+  placeImage?: (absPath: string) => string
 }
 
 function repoPath(absPath: string, repoRoot: string): string {
@@ -222,9 +233,13 @@ export function rewriteMarkdown(source: string, options: RewriteMarkdownOptions)
       ? options.locale === 'root' ? 'en' : 'root'
       : options.locale
     const page = published.get(targetPath)?.get(targetLocale)
-    const nextUrl = page === undefined
-      ? githubTarget(absPath, line, suffix, options.repositoryRef, options.repoRoot, node.type === 'image')
-      : routeTarget(options.route, page.route, suffix)
+    const nextUrl = page !== undefined
+      ? routeTarget(options.route, page.route, suffix)
+      : node.type === 'image' && options.placeImage !== undefined
+        // The suffix rides along exactly as the GitHub branch keeps it: an SVG
+        // view fragment or a Vite query changes what the reference means.
+        ? `${options.placeImage(absPath)}${suffix}`
+        : githubTarget(absPath, line, suffix, options.repositoryRef, options.repoRoot, node.type === 'image')
 
     const start = node.position?.start.offset
     const end = node.position?.end.offset
@@ -291,17 +306,78 @@ export function projectedPageContent(markdown: string, page: DocsPage): string {
   return markdown.slice(0, closing + closingDelimiter.length)
 }
 
-/** Canonical Markdown files watched by the local VitePress dev server. */
+/**
+ * The repository file one image reference resolves to, or `undefined` when the
+ * target is not a local file this build may publish.
+ * @param absPath - resolved image target.
+ * @param repoRoot - repository root every published image must stay inside.
+ * @returns the file's real path, or `undefined` when it must not be copied.
+ *
+ * Only a regular file whose real path stays inside the repository qualifies.
+ * Publication copies the bytes into the site, so a reference escaping the
+ * repository — `../../.ssh/id_rsa`, or a symlink pointing out of the tree —
+ * would put a build-machine file on the site; `existsSync` alone, which is all
+ * link resolution needs, does not answer that.
+ */
+export function publishableImage(absPath: string, repoRoot: string): string | undefined {
+  const real = realpathSync(absPath)
+  const inside = real === repoRoot || real.startsWith(`${repoRoot}${sep}`)
+  return inside && statSync(real).isFile() ? real : undefined
+}
+
+/** Every local image a published page references, resolved to its repository file. */
+function referencedImages(): string[] {
+  const found = new Set<string>()
+  for (const page of docsPages) {
+    const sourceAbs = resolve(root, page.source)
+    if (!existsSync(sourceAbs)) continue
+    rewriteMarkdown(readFileSync(sourceAbs, 'utf8'), {
+      sourcePath: page.source,
+      locale: page.locale,
+      route: page.route,
+      pages: docsPages,
+      repoRoot: root,
+      repositoryRef: 'master',
+      placeImage: (absPath) => {
+        const real = publishableImage(absPath, root)
+        if (real !== undefined) found.add(real)
+        return ''
+      },
+    })
+  }
+  return [...found]
+}
+
+/**
+ * Files watched by the local VitePress dev server: every canonical Markdown
+ * source, plus the images they publish. Without the images, replacing a
+ * screenshot leaves the previous copy in the generated tree until something
+ * touches the Markdown beside it.
+ */
 export function docsSourceFiles(): string[] {
-  return [...new Set(docsPages.map(page => resolve(root, page.source)))]
+  return [...new Set([...docsPages.map(page => resolve(root, page.source)), ...referencedImages()])]
 }
 
 /** Rebuild the disposable VitePress source tree from the publication manifest. */
 export function projectDocs(): void {
   const routes = new Set<string>()
+  /** Projected path to the repository file that claimed it, pages and images alike. */
+  const claimed = new Map<string, string>()
   const repositoryRef = process.env.GITHUB_SHA ?? 'master'
   rmSync(generatedRoot, { recursive: true, force: true })
 
+  /** Reserve one projected path, refusing a second source for it. */
+  const claim = (target: string, sourceAbs: string): void => {
+    const holder = claimed.get(target)
+    if (holder !== undefined && holder !== sourceAbs) {
+      throw new Error(
+        `project-doc-site: ${repoPath(sourceAbs, root)} and ${repoPath(holder, root)}`
+        + ` both project to ${relative(generatedRoot, target).split(sep).join('/')}.`,
+      )
+    }
+    claimed.set(target, sourceAbs)
+  }
+
   for (const page of docsPages) {
     if (routes.has(page.route)) throw new Error(`project-doc-site: duplicate route ${JSON.stringify(page.route)}.`)
     routes.add(page.route)
@@ -310,6 +386,9 @@ export function projectDocs(): void {
       throw new Error(`project-doc-site: source ${JSON.stringify(page.source)} does not exist or is not a file.`)
     }
     const output = resolve(generatedRoot, page.route)
+    // Claimed before the images are placed: a page and an image landing on one
+    // path would otherwise overwrite each other in whichever order they ran.
+    claim(output, sourceAbs)
     mkdirSync(dirname(output), { recursive: true })
     const markdown = readFileSync(sourceAbs, 'utf8')
     const projected = rewriteMarkdown(markdown, {
@@ -319,6 +398,25 @@ export function projectDocs(): void {
       pages: docsPages,
       repoRoot: root,
       repositoryRef,
+      placeImage: (absPath) => {
+        const real = publishableImage(absPath, root)
+        if (real === undefined) {
+          throw new Error(
+            `project-doc-site: ${page.source} references image ${repoPath(absPath, root)},`
+            + ' which is not a regular file inside the repository.',
+          )
+        }
+        // Beside the page that references it, under its own basename: each
+        // locale's route tree gets its own copy, so one relative URL is correct
+        // from both.
+        const name = basename(real)
+        const target = resolve(dirname(output), name)
+        claim(target, real)
+        copyFileSync(real, target)
+        // Encoded because the destination is a Markdown inline target, where an
+        // unescaped space would end it early.
+        return `./${encodeURI(name)}`
+      },
     })
     writeFileSync(output, addProjectionFrontmatter(projectedPageContent(projected, page), page))
   }

scripts/run-gates.spec.ts

@@ -189,6 +189,12 @@ describe('Node 24 lane ownership', () => {
     expect(subject.find(item => item.id === 'doc-typecheck')?.env).toEqual({
       DSH_DOC_TYPECHECK_USE_BUILD_OUTPUT: '1',
     })
+    expect(subject.find(item => item.id === 'built-bin-smoke')?.args).toEqual(
+      expect.arrayContaining([
+        'packages/subagent/subagent-codex/tests/loader-composition.e2e.ts',
+        'packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts',
+      ]),
+    )
     expect(subject.find(item => item.id === 'web-snapshot')).toMatchObject({
       displayCommand: 'DSH_SNAPSHOT=replay pnpm run test:web:built',
       env: { DSH_SNAPSHOT: 'replay' },

scripts/run-gates.ts

@@ -599,6 +599,8 @@ function builtBinSmokeGate(needs: string[] = ['build']): Gate {
     'packages/examples/acp-demo/tests/built-bin.e2e.ts',
     'packages/host/directory-picker-native/tests/built-worker.e2e.ts',
     'packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts',
+    'packages/subagent/subagent-codex/tests/loader-composition.e2e.ts',
+    'packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts',
     // The worker-entry packages' built bundles: the only automated proof
     // that lib/index.js resolves its sibling lib/worker.cjs under plain node
     // (the e2e lane runs unbuilt, so these files self-skip there).