Merge remote-tracking branch 'origin/master' into worktree-dynamic-workflows

Beyond the mechanical conflicts (provider capability lines vs master's new
inheritsParentContext field; generated catalogs regenerated rather than
hand-merged; knip/lockfile), three master-side reworks required semantic
adaptation of this branch:

- The persona rework removed AgentOptions.systemPrompt, which was the
  structured-output instruction's channel. The instruction now rides the
  SAME final-request enforcement listener that injects the schema'd tool:
  appended per request to final.system (per-request wire state, not agent
  prompt state). Tests assert the wire request (adapter.requests) instead
  of child.options; the bare-direct-dispatch test pins the no-system arm.
- Tool guidance moved out of deployment prompts into per-tool prompt
  sections; the examples' workflow paragraph became a tool:<toolName>
  section contributed by dsh-tool-workflow (explicit-ask-only policy),
  and both example personas resolve to master's minimal identity+behavior
  form. tool-workflow gains inject: systemPrompt (+ peer dep, tsconfig
  ref); the export-shape guard updated.
- The uniform-RFC-format gate: the dynamic-workflows RFC restructured to
  the implemented/ skeleton (bare Status line; Proposal -> Decision;
  What-was-rejected -> Alternatives considered; new Consequences), and
  the overall-run-timeout deferral is now recorded in the RFC's Deferred
  list. The doc-graphs atlas classification gains the workflows seam
  (workflow-vm implementation, tool-workflow consumer).

Master's harness-identity section made "empty assembled prompt" states
unreachable through the loop, so the instruction-append is a plain
undefined-ternary and the structured tests assert append-not-replace.
All snapshot goldens (including workflow-run) replay unchanged. Full
local CI-equivalent gate sequence green on the merged tree.

scripts/gen-tool-catalog.ts

@@ -77,6 +77,12 @@ interface ToolPackage {
   dir: string
   /** Repo-relative source path linked from the catalog entry. */
   source: 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. */
+  writes: string[]
+  /** Additional model-visible names shipped by example/app config. */
+  shippedNames?: string[]
   /** Plug the injected seams + the tool plugin onto a context that already
    * carries `systemPrompt` + `tools`. */
   mount: (ctx: Context) => Promise<void>
@@ -100,15 +106,21 @@ const TOOL_PACKAGES: ToolPackage[] = [
     pkg: '@deepseek-ai/dsh-tool-bash',
     dir: 'tool-bash',
     source: 'packages/bash/tool-bash/src/index.ts',
+    requires: ['ctx.tools', 'ctx.bash'],
+    writes: ['tool/call', 'tool/result', 'context/message via agent.inject() for background completion notices'],
     async mount(ctx) {
       await ctx.plugin(LocalBashExecutor)
       await ctx.plugin(ToolBash)
     },
+    note:
+      'The bash/bash_output/bash_kill tools are model-facing consumers of the bash executor seam.',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-fs',
     dir: 'tool-fs',
     source: 'packages/fs/tool-fs/src/index.ts',
+    requires: ['ctx.tools', 'ctx.fs', 'ctx.systemPrompt'],
+    writes: ['tool/call', 'fs/write-intent or fs/edit-intent for mutations', 'fs/observed after successful file operations', 'tool/result'],
     async mount(ctx) {
       // The tool injects `fs`; boot the local backend to satisfy it. The schemas
       // do not depend on the policy plugin (an event gate that changes behavior,
@@ -123,6 +135,9 @@ const TOOL_PACKAGES: ToolPackage[] = [
     pkg: '@deepseek-ai/dsh-tool-subagent',
     dir: 'tool-subagent',
     source: 'packages/subagent/tool-subagent/src/index.ts',
+    requires: ['ctx.tools', 'ctx.subagents'],
+    writes: ['tool/call', 'tool/result', 'child session events through the chosen provider'],
+    shippedNames: ['subagent', 'subagent_fork'],
     async mount(ctx) {
       await ctx.plugin(SubagentService)
       // Register a scripted provider under the name the tool delegates to.
@@ -136,14 +151,20 @@ const TOOL_PACKAGES: ToolPackage[] = [
     pkg: '@deepseek-ai/dsh-tool-todo',
     dir: 'tool-todo',
     source: 'packages/todo/tool-todo/src/index.ts',
+    requires: ['ctx.tools', 'owning Agent session'],
+    writes: ['tool/call', 'todo/write', 'tool/result'],
     async mount(ctx) {
       await ctx.plugin(ToolTodo)
     },
+    note:
+      'todo_write is session-owned state; UIs render the latest todo/write event as a checklist or ACP plan.',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-workflow',
     dir: 'tool-workflow',
     source: 'packages/workflow/tool-workflow/src/index.ts',
+    requires: ['ctx.tools', 'ctx.workflows', 'ctx.systemPrompt', 'a calling Agent (exec.agent parents the script children)'],
+    writes: ['tool/call', 'tool/result'],
     async mount(ctx) {
       // The tool injects `workflows`; boot the vm engine over a scripted
       // subagent provider to satisfy it. The schema does not depend on which
@@ -158,6 +179,8 @@ const TOOL_PACKAGES: ToolPackage[] = [
     pkg: '@deepseek-ai/dsh-tool-web',
     dir: 'tool-web',
     source: 'packages/web/tool-web/src/index.ts',
+    requires: ['ctx.tools', 'ctx.web', 'ctx.systemPrompt'],
+    writes: ['tool/call', 'tool/result'],
     async mount(ctx) {
       // The tools inject `web`; boot the seam plus one search and one fetch
       // provider so both `web_search` and `web_fetch` register. The schemas do
@@ -168,6 +191,8 @@ const TOOL_PACKAGES: ToolPackage[] = [
       await ctx.plugin(WebFetchLocal)
       await ctx.plugin(ToolWeb)
     },
+    note:
+      'web_search and web_fetch keep provider selection behind ctx.web so model-visible schemas stay stable across backend swaps.',
   },
 ]
 
@@ -175,6 +200,9 @@ const TOOL_PACKAGES: ToolPackage[] = [
 interface CatalogPackage {
   pkg: string
   source: string
+  requires: string[]
+  writes: string[]
+  shippedNames?: string[]
   schemas: ToolSchema[]
   /** A deployment note (see {@link ToolPackage.note}), rendered after the tools. */
   note?: string
@@ -224,7 +252,15 @@ export async function collectToolCatalog(packages: ToolPackage[] = TOOL_PACKAGES
       await ctx.plugin(ToolRegistry)
       await entry.mount(ctx)
       const schemas = ctx.tools.schemas().sort((a, b) => a.name.localeCompare(b.name))
-      catalog.push({ pkg: entry.pkg, source: entry.source, schemas, ...entry.note !== undefined ? { note: entry.note } : {} })
+      catalog.push({
+        pkg: entry.pkg,
+        source: entry.source,
+        requires: entry.requires,
+        writes: entry.writes,
+        schemas,
+        ...entry.shippedNames !== undefined ? { shippedNames: entry.shippedNames } : {},
+        ...entry.note !== undefined ? { note: entry.note } : {},
+      })
     } finally {
       await ctx.fiber.dispose()
     }
@@ -241,6 +277,14 @@ function renderTool(schema: ToolSchema, source: string): string[] {
   return out
 }
 
+function codeList(values: string[] | undefined): string {
+  return values?.length ? values.map(value => `\`${value}\``).join(', ') : '-'
+}
+
+function tableCell(value: string | undefined): string {
+  return value ? value.replace(/\|/g, '\\|').replace(/\n/g, '<br>') : '-'
+}
+
 /** Render the full catalog (pure, deterministic given the manifest-ordered input). */
 export function render(catalog: ToolCatalog): string {
   const lines: string[] = [
@@ -255,6 +299,14 @@ export function render(catalog: ToolCatalog): string {
     '',
     '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.',
     '',
+    '## Tool Package Map',
+    '',
+    'This table connects model-visible tool names to the plugin package and service seams behind them. Exact JSON Schemas follow in the package sections below.',
+    '',
+    '| Tool package | Model-visible names | Requires | Writes / affects | Shipped aliases | Deployment note |',
+    '| --- | --- | --- | --- | --- | --- |',
+    ...catalog.map(entry => `| \`${entry.pkg}\` | ${codeList(entry.schemas.map(schema => schema.name))} | ${codeList(entry.requires)} | ${codeList(entry.writes)} | ${codeList(entry.shippedNames)} | ${tableCell(entry.note)} |`),
+    '',
   ]
   for (const entry of catalog) {
     lines.push(`## \`${entry.pkg}\``, '')