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.

packages/bash/bash-local/README.md

@@ -27,4 +27,4 @@ Design surveyed against the bash tools of Claude Code, OpenCode, Codex, and pi;
 
 ## Sandboxing
 
-`TODO(permissions/sandbox)`: execution policy does NOT belong in this package. Use the `tools/pre-execute` deny/ask gate or implement a sandboxing `BashExecutor` — see docs/architecture.md § plugin checklist. Reference points: Claude Code wraps commands in sandbox-exec/bubblewrap; Codex applies seatbelt/landlock plus an execpolicy prefix-rule engine.
+`TODO(permissions/sandbox)`: execution policy does NOT belong in this package. Use the `tools/pre-execute` deny/ask gate or implement a sandboxing `BashExecutor` — see docs/architecture.md § Extending The Harness. Reference points: Claude Code wraps commands in sandbox-exec/bubblewrap; Codex applies seatbelt/landlock plus an execpolicy prefix-rule engine.

packages/bash/bash-local/src/index.ts

@@ -5,8 +5,9 @@
  * survey notes), tracks background tasks, and kills everything on dispose.
  *
  * TODO(permissions/sandbox): execution policy does NOT belong here — use
- * the `tools/pre-execute` deny/ask gate (see docs/architecture.md § plugin
- * checklist) or implement a sandboxing `BashExecutor`. Reference points:
+ * the `tools/pre-execute` deny/ask gate (see docs/architecture.md
+ * § Extending The Harness) or implement a sandboxing `BashExecutor`.
+ * Reference points:
  * Claude Code wraps commands in sandbox-exec/bubblewrap; Codex applies
  * seatbelt/landlock plus an execpolicy prefix-rule engine.
  *

packages/bash/tool-bash/README.md

@@ -2,7 +2,9 @@
 
 The model-facing bash tools — `bash`, `bash_output`, `bash_kill` — registered over the `ctx.bash` executor seam (`@deepseek-ai/dsh-bash`). Pure schema + text shaping; every process concern lives behind the seam, so sandboxed or remote executor implementations swap in without changing what the model sees.
 
-Requires a loaded executor implementation (e.g. `@deepseek-ai/dsh-bash-local`); the plugin stays pending until `ctx.bash` exists (`inject: ['tools', 'bash']`).
+Requires a loaded executor implementation (e.g. `@deepseek-ai/dsh-bash-local`); the plugin stays pending until `ctx.bash` exists (`inject: ['tools', 'bash', 'systemPrompt']`).
+
+The plugin also contributes the `tool:bash` prompt section (order 105) — the cross-call habit the per-tool descriptions cannot carry: check the `[exit code: N]` marker on every result and investigate failures before moving on.
 
 ## Tools
 

packages/bash/tool-bash/package.json

@@ -25,6 +25,7 @@
     "@deepseek-ai/dsh-agent": "^0.0.1",
     "@deepseek-ai/dsh-bash": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
     "cordis": "^4.0.0-rc.6"
   },

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

@@ -33,7 +33,7 @@
  * TODO(permissions): commands run with the executor's full authority. The
  * permission/sandbox seam is the `tools/pre-execute` waterfall (deny/ask) plus
  * sandboxing `BashExecutor` implementations — see docs/architecture.md
- * § plugin checklist.
+ * § Extending The Harness.
  *
  * @module @deepseek-ai/dsh-tool-bash
  */
@@ -43,11 +43,12 @@ import { isAbsolute, resolve as resolvePath } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { GenericCallView, TerminalCallView, ToolResult, ToolResultView } from '@deepseek-ai/dsh-tools'
 import type { Agent } from '@deepseek-ai/dsh-agent'
+import type {} from '@deepseek-ai/dsh-system-prompt'
 import { BashTaskId, OwnerToken } from '@deepseek-ai/dsh-bash'
 import type { BashRunResult, BashTask, CollectedOutput } from '@deepseek-ai/dsh-bash'
 
 export const name = 'tool-bash'
-export const inject = ['tools', 'bash']
+export const inject = ['tools', 'bash', 'systemPrompt']
 
 /**
  * Validate the constraints the SchemaSpec can't express. `defineTool` now
@@ -285,6 +286,15 @@ function statusLine(task: BashTask): string {
 }
 
 export function apply(ctx: Context): void {
+  // The bash tools' cross-call HABIT, which the per-tool descriptions cannot
+  // carry (they describe one call each): the exit-code marker is only useful
+  // if the model actually checks it every time.
+  ctx.systemPrompt.section({
+    name: 'tool:bash',
+    order: 105,
+    text: 'Check the [exit code: N] marker on every bash result; investigate failures before moving on.',
+  })
+
   /**
    * The caller's owner TOKEN — the owning agent's `session.header.id`, or
    * `undefined` for a non-agent caller. Read `session.header.id` (NOT

packages/bash/tool-bash/tests/tools.spec.ts

@@ -261,6 +261,14 @@ describe('bash tool', () => {
     })
   })
 
+  it('contributes the exit-code habit as its prompt section (guidance the descriptions cannot carry)', async () => {
+    const ctx = await setup()
+    const assembly = await ctx.systemPrompt.assemble()
+    const section = assembly.sections.find(s => s.name === 'tool:bash')
+    expect(section?.order).toBe(105)
+    expect(section?.text).toContain('[exit code: N]')
+  })
+
   it('unregisters everything when the plugin fiber is disposed (HMR safety)', async () => {
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
@@ -268,8 +276,11 @@ describe('bash tool', () => {
     await ctx.plugin(LocalBashExecutor, {})
     const fiber = await ctx.plugin(ToolBash)
     expect(ctx.tools.schemas()).toHaveLength(3)
+    expect((await ctx.systemPrompt.assemble()).sections.map(s => s.name)).toEqual(['harness:identity', 'deployment:persona', 'tool:bash'])
     await fiber.dispose()
     expect(ctx.tools.schemas()).toHaveLength(0)
+    // Only the system-prompt plugin's own built-in sections remain.
+    expect((await ctx.systemPrompt.assemble()).sections.map(s => s.name)).toEqual(['harness:identity', 'deployment:persona'])
   })
 
   it('tools depend on the executor: no registration without ctx.bash', async () => {

packages/core/agent-core/README.md

@@ -18,6 +18,7 @@ This is the package to read to see **the whole plugin tree at once** — the tea
 @deepseek-ai/dsh-invariants       dev-mode event-contract assertions
 @deepseek-ai/dsh-tool-bash        the model-facing bash/bash_output/bash_kill schemas
 @deepseek-ai/dsh-agent-loop       THE concrete loop (gets the forwarded `agents`)
+                                  (dsh-system-prompt gets the forwarded `persona`)
 ```
 
 ## What it deliberately leaves OUTSIDE the bundle
@@ -34,10 +35,11 @@ This is the [interface/implementation/consumer seam](../../../docs/rfc/implement
 
 ```ts
 import type { Config } from '@deepseek-ai/dsh-agent-core'
-// Config === AgentLoop.Config — the `agents` list, default [].
+// { agents?, persona? } — the schema is z.intersect([AgentLoop.Config, SystemPrompt.Config]),
+// so validation and defaulting can never drift from the owners'.
 ```
 
-The bundle FORWARDS `agent-loop`'s `agents` list as its own (default `[]`), so each app supplies its own pre-created agents — a stdio app pre-creates a `main`; the ACP app pre-creates none (it creates agents on demand at `session/new`). Forwarding the list is exactly why the loop can live in the shared spine even though the apps disagree on which agents to pre-create.
+The bundle FORWARDS each field to the child that owns it: `agents` to `agent-loop` (default `[]`), so each app supplies its own pre-created agents — a stdio app pre-creates a `main`; the ACP app pre-creates none (it creates agents on demand at `session/new`) — and `persona` to `dsh-system-prompt` (default `''`), the deployment's persona section. Forwarding is exactly why the owners can live in the shared spine even though the apps disagree on what to configure.
 
 ## Why a code bundle, not a shared YAML include
 

packages/core/agent-core/package.json

@@ -44,5 +44,8 @@
     "@deepseek-ai/dsh-tool-bash": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "cordis": "^4.0.0-rc.6"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
   }
 }

packages/core/agent-core/src/index.ts

@@ -44,9 +44,10 @@
 
 import type { Context } from 'cordis'
 import Timer from '@cordisjs/plugin-timer'
+import z from 'schemastery'
 import LlmService from '@deepseek-ai/dsh-llm'
 import SessionStore from '@deepseek-ai/dsh-session'
-import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import SystemPrompt, { type Config as SystemPromptConfig } from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import * as invariants from '@deepseek-ai/dsh-invariants'
@@ -56,33 +57,45 @@ import AgentLoop, { type Config as AgentLoopConfig } from '@deepseek-ai/dsh-agen
 export const name = 'agent-core'
 
 /**
- * Bundle config: the agent-loop `agents` list, forwarded verbatim. Default `[]`
- * — an app that pre-creates no agents (the ACP bridge creates them on demand at
- * `session/new`) simply omits it; an app that needs a pre-created `main` (the
- * stdio chat) supplies one. This IS {@link AgentLoopConfig}, so the schema and
- * the forwarded shape can never drift.
+ * Bundle config: each field forwarded verbatim to the child that owns it —
+ * `agents` to the agent loop (an app that pre-creates no agents, like the ACP
+ * bridge, simply omits it), `persona` to the system-prompt plugin (the
+ * deployment's persona section). Both are optional INPUT here because each
+ * owner's schema supplies the default (`[]` / `''`); the schema is the
+ * INTERSECTION of the owners' own schemas, so validation and defaulting can
+ * never drift from them.
  */
-export type Config = AgentLoopConfig
+export interface Config {
+  /** The agent-loop `agents` list (see dsh-agent-loop's `Config`). */
+  agents?: AgentLoopConfig['agents']
+  /** The deployment persona (see dsh-system-prompt's `Config`). */
+  persona?: SystemPromptConfig['persona']
+}
 
-/** Forward the loop's own schema so validation + defaulting stay identical. */
-export const Config = AgentLoop.Config
+/** Intersect the owners' schemas so validation + defaulting stay identical. */
+export const Config = z.intersect([AgentLoop.Config, SystemPrompt.Config]) as unknown as z<Config>
 
 /**
  * Load the spine. Each `ctx.plugin(...)` mounts one child of the bundle fiber;
- * `agent-loop` receives the forwarded `agents` list. Load order is irrelevant
- * (cordis pends each fiber on its `inject` until the services it needs exist),
- * but the listing mirrors the dependency layering for readability: the LLM
- * vocabulary and core registries first, then the dev tripwire and the bash tool
- * consumer, then the loop that drives them.
+ * `agent-loop` receives the forwarded `agents` list and `system-prompt` the
+ * forwarded `persona`. Load order is irrelevant (cordis pends each fiber on
+ * its `inject` until the services it needs exist), but the listing mirrors the
+ * dependency layering for readability: the LLM vocabulary and core registries
+ * first, then the dev tripwire and the bash tool consumer, then the loop that
+ * drives them.
  */
 export function apply(ctx: Context, config: Config): void {
   ctx.plugin(Timer)
   ctx.plugin(LlmService)
   ctx.plugin(SessionStore)
-  ctx.plugin(SystemPrompt)
+  // The forwarded fields are validated + defaulted by this bundle's intersected
+  // schema before apply runs, so the ?? fallbacks only narrow the
+  // optional-input TYPES — they mirror the owners' schema defaults, never
+  // introduce different ones.
+  ctx.plugin(SystemPrompt, { persona: config.persona ?? '' })
   ctx.plugin(ToolRegistry)
   ctx.plugin(AgentRegistry)
   ctx.plugin(invariants)
   ctx.plugin(toolBash)
-  ctx.plugin(AgentLoop, { agents: config.agents })
+  ctx.plugin(AgentLoop, { agents: config.agents ?? [] })
 }

packages/core/agent-core/tests/agent-core.spec.ts

@@ -43,11 +43,27 @@ describe('dsh-agent-core bundle', () => {
     await ctx.fiber.dispose()
   })
 
-  it('forwards a pre-created agent to the loop', async () => {
+  it('forwards a pre-created agent to the loop and the persona to system-prompt', async () => {
     const ctx = await mount({
-      agents: [{ id: AgentId('main'), model: 'mock', systemPrompt: 'hi' }],
+      agents: [{ id: AgentId('main'), model: 'mock' }],
+      persona: 'You are main.',
     })
     expect(ctx.get('agents')?.get(AgentId('main'))).toBeDefined()
+    const assembly = await ctx.get('systemPrompt')!.assemble()
+    expect(assembly.sections.find(s => s.name === 'deployment:persona')?.text).toBe('You are main.')
+    await ctx.fiber.dispose()
+  })
+
+  it('tolerates a schema-bypassing direct apply (the ?? fallbacks fire)', async () => {
+    // ctx.plugin validates + defaults the bundle config first; a direct apply
+    // skips the schema, so the forwarding `?? []` / `?? ''` are what fire.
+    const ctx = new Context()
+    agentCore.apply(ctx, {})
+    await new Promise(resolve => setTimeout(resolve, 50))
+    expect(ctx.get('agentLoop')).toBeDefined()
+    expect(ctx.get('agents')?.list()).toHaveLength(0)
+    const assembly = await ctx.get('systemPrompt')!.assemble()
+    expect(assembly.sections.find(s => s.name === 'deployment:persona')?.text).toBe('')
     await ctx.fiber.dispose()
   })
 

packages/core/agent-core/tsconfig.json

@@ -11,6 +11,9 @@
     {
       "path": "../../../vendor/cordis"
     },
+    {
+      "path": "../../../vendor/schemastery"
+    },
     {
       "path": "../../../vendor/timer"
     },

packages/core/agent-loop/README.md

@@ -28,12 +28,11 @@ interface Config {
   agents: Array<{
     id: string                 // required
     model?: string
-    systemPrompt?: string
   }>
 }
 ```
 
-Agents listed in config are auto-created at startup.
+Agents listed in config are auto-created at startup. (There is no per-agent persona: the deployment persona is `dsh-system-prompt`'s own `persona` config, shared by every agent in the context.) The plugin registers the built-in `model`/`cwd` prompt variables on `ctx.systemPrompt`, resolved per step from the `assemble({ agent })` context — runtime facts of the agents THIS loop drives, unlike the `harness:identity`/`deployment:persona` sections, which live on `dsh-system-prompt` so they survive a swapped loop plugin.
 
 ### Classes
 
@@ -55,7 +54,7 @@ forever:
     if every prompt blocked: 'turn/end'(rejected), no step  ⟵ zero-step turn
     STEP loop:
       drain steering
-      assembly = systemPrompt.assemble()
+      assembly = systemPrompt.assemble({agent})  ⟵ renderPrompt(assembly) IS the full prompt
       await serial agent/pre-step        ⟵ surface mutation (compaction) outside the step
       session('step/start')
       request = waterfall agent/request

packages/core/agent-loop/src/index.ts

@@ -72,7 +72,6 @@ export class AgentLoop extends Service implements AgentFactory {
     agents: z.array(z.object({
       id: z.string().required(),
       model: z.string(),
-      systemPrompt: z.string(),
       resumeSessionId: z.string(),
     })).default([]),
   }) as unknown as z<Config>
@@ -82,6 +81,16 @@ export class AgentLoop extends Service implements AgentFactory {
     // Provide the agent-creation factory to the registry (effect-scoped: the
     // slot is cleared on dispose).
     ctx.effect(() => this.ctx.agents.setFactory(this), 'agentLoop.setFactory()')
+    // The prompt variables the shipped loop provides, registered once. The
+    // sections themselves (`harness:identity`, `deployment:persona`) belong to
+    // dsh-system-prompt — they must survive a swapped loop plugin — but
+    // `{{model}}`/`{{cwd}}` are runtime facts of the agents THIS loop drives:
+    // it assembles with `{ agent }` each step (loop.ts), and the variables
+    // project the agent's configured model and its session workspace from that
+    // context. A provider returns undefined when the fact is absent
+    // (renderPrompt then rejects a persona that claims it — fail loud).
+    ctx.systemPrompt.variable('model', context => context.agent?.options.model)
+    ctx.systemPrompt.variable('cwd', context => context.agent?.session.header.cwd)
     for (const { id, resumeSessionId, ...options } of config.agents) {
       if (resumeSessionId !== undefined && resumeSessionId !== '') {
         // Resume a prior session instead of starting fresh. resume() needs

packages/core/agent-loop/src/loop.ts

@@ -152,7 +152,8 @@ export interface LoopHandle {
  *     every prompt blocked → 'turn/end'(rejected), 0 steps
  *     STEP loop:
  *       drain steering → session('steering/message')  ⟵ catches late steering
- *       assembly = ctx.systemPrompt.assemble()        ⟵ waterfall system-prompt/assemble
+ *       assembly = ctx.systemPrompt.assemble({agent}) ⟵ waterfall system-prompt/assemble; renderPrompt
+ *                                                        (persona section + {{variables}}) IS the full prompt
  *       await ctx.serial('agent/pre-step')            ⟵ surface mutation (compaction) OUTSIDE the step
  *       session('step/start')                         ⟵ durable step boundary (no agent/* mirror)
  *       req = {model, system, tools, messages: session.deriveMessages(), signal}
@@ -434,11 +435,11 @@ async function runTurn(ctx: Context, agent: ReactLoopAgent, handle: LoopHandle,
       // because the pre-step seam needs it: compaction measures token pressure
       // against the system prompt (it counts toward the budget). runStep reuses
       // this same assembly for the request, so the prompt is assembled once per
-      // step.
-      const assembly = await ctx.systemPrompt.assemble()
-      const fullSystemPrompt = [renderPrompt(assembly), agent.options.systemPrompt ?? '']
-        .filter(text => text.length > 0)
-        .join('\n\n')
+      // step. renderPrompt IS the full prompt — the persona is the order-0
+      // section (registered by the AgentLoop plugin) and `{{variable}}`
+      // interpolation happens in the render, so there is no separate join.
+      const assembly = await ctx.systemPrompt.assemble({ agent })
+      const fullSystemPrompt = renderPrompt(assembly)
 
       // Interruption landing after assembly: dispose() or cancel() in a
       // turn-start listener (or a listener whose promise resolved before the

packages/core/agent-loop/tests/config-session-id.spec.ts

@@ -35,7 +35,7 @@ describe('config-driven session id', () => {
     await ctx1.plugin(SystemPrompt)
     await ctx1.plugin(ToolRegistry)
     await ctx1.plugin(AgentRegistry)
-    await ctx1.plugin(AgentLoop, { agents: [{ id: AgentId('cfg'), model: 'mock', systemPrompt: '' }] })
+    await ctx1.plugin(AgentLoop, { agents: [{ id: AgentId('cfg'), model: 'mock' }] })
     await ctx1.plugin(SessionPersistenceJsonl, { root })
     ctx1.llm.registerAdapter(['mock'], new MockAdapter([textResponse('cfg')]))
     const a1 = ctx1.agents.get(AgentId('cfg')) as ReactLoopAgent
@@ -52,7 +52,7 @@ describe('config-driven session id', () => {
     await ctx2.plugin(SystemPrompt)
     await ctx2.plugin(ToolRegistry)
     await ctx2.plugin(AgentRegistry)
-    await ctx2.plugin(AgentLoop, { agents: [{ id: AgentId('cfg'), model: 'mock', systemPrompt: '' }] })
+    await ctx2.plugin(AgentLoop, { agents: [{ id: AgentId('cfg'), model: 'mock' }] })
     await ctx2.plugin(SessionPersistenceJsonl, { root })
     ctx2.llm.registerAdapter(['mock'], new MockAdapter([textResponse('cfg2')]))
     const a2 = ctx2.agents.get(AgentId('cfg')) as ReactLoopAgent
@@ -92,7 +92,7 @@ describe('config-driven session id', () => {
     await ctx2.plugin(SystemPrompt)
     await ctx2.plugin(ToolRegistry)
     await ctx2.plugin(AgentRegistry)
-    await ctx2.plugin(AgentLoop, { agents: [{ id: AgentId('main'), model: 'mock', systemPrompt: '', resumeSessionId: SessionId('sticky-1') }] })
+    await ctx2.plugin(AgentLoop, { agents: [{ id: AgentId('main'), model: 'mock', resumeSessionId: SessionId('sticky-1') }] })
     await ctx2.plugin(SessionPersistenceJsonl, { root })
     ctx2.llm.registerAdapter(['mock'], new MockAdapter([textResponse('second')]))
 
@@ -120,7 +120,7 @@ describe('config-driven session id', () => {
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(AgentRegistry)
-    await ctx.plugin(AgentLoop, { agents: [{ id: AgentId('main'), model: 'mock', systemPrompt: '', resumeSessionId: SessionId('does-not-exist') }] })
+    await ctx.plugin(AgentLoop, { agents: [{ id: AgentId('main'), model: 'mock', resumeSessionId: SessionId('does-not-exist') }] })
     const warn = vi.spyOn((ctx.agentLoop as unknown as { ctx: { logger: { warn: (...a: unknown[]) => void } } }).ctx.logger, 'warn')
       .mockImplementation(() => undefined)
     await ctx.plugin(SessionPersistenceJsonl, { root })

packages/core/agent-loop/tests/loop.spec.ts

@@ -8,11 +8,11 @@ import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
 import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
 import { MockAdapter, maxTokensResponse, textResponse, toolCallResponse } from './mock-adapter.ts'
 
-async function harness(adapter: MockAdapter) {
+async function harness(adapter: MockAdapter, persona = '') {
   const ctx = new Context()
   await ctx.plugin(LlmService)
   await ctx.plugin(SessionStore)
-  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(SystemPrompt, { persona })
   await ctx.plugin(ToolRegistry)
   await ctx.plugin(AgentRegistry)
   await ctx.plugin(AgentLoop, { agents: [] })
@@ -141,10 +141,12 @@ describe('agent loop', () => {
       .toEqual({ diffs: [{ path: 'a.txt', oldText: null, newText: 'x' }] })
   })
 
-  it('passes assembled system prompt and tool schemas into the request', async () => {
+  it('renders harness identity, then the persona, then tool guidance — with {{variables}} resolved', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
-    const ctx = await harness(adapter)
-    ctx.systemPrompt.section({ name: 'persona', order: 0, text: 'You are a test agent.' })
+    // The persona is a TEMPLATE: {{model}} is the loop-registered variable
+    // projecting this agent's configured model, so the model knows its own name.
+    const ctx = await harness(adapter, 'You are a test agent on {{model}}.')
+    ctx.systemPrompt.section({ name: 'tool:noop', order: 100, text: 'Use the noop tool wisely.' })
     ctx.tools.register(defineTool({
       name: 'noop',
       description: 'does nothing',
@@ -153,16 +155,111 @@ describe('agent loop', () => {
         return []
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock', systemPrompt: 'Agent-specific suffix.' })
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
 
     send(agent, 'hi')
     await waitForIdle(ctx, agent)
 
     const request = adapter.requests[0]
-    expect(request!.system).toBe('You are a test agent.\n\nAgent-specific suffix.')
+    expect(request!.system).toBe('You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a test agent on mock.\n\nUse the noop tool wisely.')
     expect(request!.tools?.map(t => t.name)).toEqual(['noop'])
   })
 
+  it('resolves {{cwd}} from the agent session workspace (factory create with meta.cwd)', async () => {
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = await harness(adapter, 'Working in {{cwd}}.')
+    const handle = ctx.agents.create({
+      agentId: AgentId('a-cwd'),
+      sessionId: SessionId('s-cwd'),
+      meta: { cwd: '/work/space' },
+      agentOptions: { model: 'mock' },
+    })
+
+    const agent = handle.agent as ReactLoopAgent
+    send(agent, 'hi')
+    await waitForIdle(ctx, agent)
+
+    expect(adapter.requests[0]!.system).toBe('You are an AI agent powered by the DeepSeek Harness SDK.\n\nWorking in /work/space.')
+  })
+
+  it('contains a strict-variable render failure: the turn errors, the loop keeps serving turns', async () => {
+    // A persona claiming {{cwd}} on a session with NO cwd is a deployment
+    // authoring error — renderPrompt throws, the turn ends with an error, and
+    // the same agent must then RUN a later turn to completion (not merely
+    // report idle status): a rescue listener supplies the variable and the
+    // follow-up prompt reaches the model.
+    const adapter = new MockAdapter([textResponse('ok after rescue')])
+    const ctx = await harness(adapter, 'In {{cwd}}.')
+    const errors: Error[] = []
+    ctx.on('agent/error', (_agent, _turn, _step, error) => void errors.push(error))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+
+    send(agent, 'hi')
+    await waitForIdle(ctx, agent)
+
+    expect(adapter.requests).toHaveLength(0) // the request was never sent
+    expect(errors.some(e => e.message.includes('no value for this assembly'))).toBe(true)
+    const turnEnd = agent.session.events.find(e => e.type === 'turn/end')
+    expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason.kind).toBe('error')
+
+    // The loop survived: a waterfall listener rescues {{cwd}} and the SAME
+    // agent completes a real model turn.
+    ctx.on('system-prompt/assemble', async (assembly, _context, next) => {
+      assembly.variables['cwd'] = '/rescued'
+      return next()
+    })
+    send(agent, 'again')
+    await waitForIdle(ctx, agent)
+
+    expect(adapter.requests).toHaveLength(1)
+    expect(adapter.requests[0]!.system).toBe('You are an AI agent powered by the DeepSeek Harness SDK.\n\nIn /rescued.')
+    const turnEnds = agent.session.events.filter(e => e.type === 'turn/end')
+    expect(turnEnds).toHaveLength(2)
+    expect(turnEnds[1]?.type === 'turn/end' && turnEnds[1].data.reason.kind).toBe('completed')
+  })
+
+  it('supports the model-via-agent/request path with a {{model}} persona: the supplier states it via the assemble waterfall', async () => {
+    // AgentOptions.model unset: the model arrives in the agent/request
+    // waterfall (the loop's documented fallback — see runStep's no-model
+    // error). {{model}} renders BEFORE that waterfall, so the SAME plugin
+    // states the fact early on system-prompt/assemble — the owner of a
+    // late-bound fact owns stating it wherever it is claimed.
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = await harness(adapter, 'You run on {{model}}.')
+    ctx.on('system-prompt/assemble', async (assembly, _context, next) => {
+      assembly.variables['model'] = 'mock'
+      return next()
+    })
+    ctx.on('agent/request', async (_agent, _turn, _step, options, next) => {
+      options.model = 'mock'
+      return next()
+    })
+    const agent = ctx.agentLoop.create(AgentId('a-late-model'), {})
+
+    send(agent, 'hi')
+    await waitForIdle(ctx, agent)
+
+    expect(adapter.requests).toHaveLength(1)
+    expect(adapter.requests[0]!.model).toBe('mock')
+    expect(adapter.requests[0]!.system).toBe('You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou run on mock.')
+  })
+
+  it('omits the system field when a system-prompt/assemble veto empties the assembly', async () => {
+    // The documented escape valve: a deployment that must drop the harness
+    // openers short-circuits the assemble waterfall; the request then carries
+    // NO system field at all (not an empty string).
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = await harness(adapter)
+    ctx.on('system-prompt/assemble', async () => ({ sections: [], tools: [], variables: {} }))
+    const agent = ctx.agentLoop.create(AgentId('a-no-system'), { model: 'mock' })
+
+    send(agent, 'hi')
+    await waitForIdle(ctx, agent)
+
+    expect(adapter.requests).toHaveLength(1)
+    expect('system' in adapter.requests[0]!).toBe(false)
+  })
+
   it('records raw chunks for replay as assistant/chunk session events', async () => {
     const adapter = new MockAdapter([textResponse('abc')])
     const ctx = await harness(adapter)
@@ -371,10 +468,12 @@ describe('agent loop', () => {
     send(agent, 'go')
     await waitForIdle(ctx, agent)
 
-    // One fire per step, in order, each with the assembled system prompt.
+    // One fire per step, in order, each with the assembled system prompt
+    // (here just the loop's own harness-identity section — no persona set).
+    const HARNESS = 'You are an AI agent powered by the DeepSeek Harness SDK.'
     expect(fires).toEqual([
-      { turn: 1, step: 1, fullSystemPrompt: '' },
-      { turn: 1, step: 2, fullSystemPrompt: '' },
+      { turn: 1, step: 1, fullSystemPrompt: HARNESS },
+      { turn: 1, step: 2, fullSystemPrompt: HARNESS },
     ])
   })
 
@@ -796,7 +895,7 @@ describe('agent loop', () => {
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(AgentLoop, {
-      agents: [{ id: AgentId('config-agent'), model: 'mock', systemPrompt: 'Config prompt' }],
+      agents: [{ id: AgentId('config-agent'), model: 'mock' }],
     })
     ctx.llm.registerAdapter(['mock'], adapter)
 

packages/core/agent-loop/tests/review-fixes.spec.ts

@@ -1016,7 +1016,7 @@ describe('disposal/cancel honored during pre-step assembly (P1-1)', () => {
     ctx.llm.registerAdapter(['mock'], adapter)
 
     // Blocking listener on the parent context (survives fiber disposal).
-    const unlisten = ctx.on('system-prompt/assemble', async function (_assembly, next) {
+    const unlisten = ctx.on('system-prompt/assemble', async function (_assembly, _context, next) {
       await blocked
       return next()
     })
@@ -1072,7 +1072,7 @@ describe('disposal/cancel honored during pre-step assembly (P1-1)', () => {
     await ctx.plugin(Invariants, { freeze: false })
     ctx.llm.registerAdapter(['mock'], adapter)
 
-    const unlisten = ctx.on('system-prompt/assemble', async function (_assembly, next) {
+    const unlisten = ctx.on('system-prompt/assemble', async function (_assembly, _context, next) {
       await blocker
       return next()
     })
@@ -1229,7 +1229,7 @@ describe('disposal/cancel honored during pre-step assembly (P1-1)', () => {
     await ctx.plugin(Invariants, { freeze: false })
     ctx.llm.registerAdapter(['mock'], adapter)
 
-    ctx.on('system-prompt/assemble', async function (_assembly, next) {
+    ctx.on('system-prompt/assemble', async function (_assembly, _context, next) {
       await blocker
       return next()
     })

packages/core/agent/package.json

@@ -25,12 +25,14 @@
     "@deepseek-ai/dsh-brand": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
     "cordis": "^4.0.0-rc.6"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-brand": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "cordis": "^4.0.0-rc.6"
   }
 }

packages/core/agent/src/index.ts

@@ -49,7 +49,7 @@ export interface CreateAgentOptions {
    * for a fresh (spawn) child.
    */
   seed?: SessionEvent[]
-  /** Per-agent options (model, system prompt). */
+  /** Per-agent options (model, …). */
   agentOptions?: AgentOptions
 }
 
@@ -62,7 +62,7 @@ export interface ResumeAgentOptions {
   agentId: AgentId
   /** The persisted session id to load and resume on. */
   resumeSessionId: SessionId
-  /** Per-agent options (model, system prompt). */
+  /** Per-agent options (model, …). */
   agentOptions?: AgentOptions
 }
 

packages/core/agent/src/types.ts

@@ -45,6 +45,7 @@
 
 import type { Branded } from '@deepseek-ai/dsh-brand'
 import type { ContentBlock, GenerateOptions, Message, MessageSource } from '@deepseek-ai/dsh-llm'
+import type {} from '@deepseek-ai/dsh-system-prompt'
 
 /** Identifies one live agent in the registry. */
 export type AgentId = Branded<'AgentId'>
@@ -55,15 +56,28 @@ export function AgentId(id: string): AgentId {
 }
 import type { Session } from '@deepseek-ai/dsh-session'
 
+declare module '@deepseek-ai/dsh-system-prompt' {
+  interface AssembleContext {
+    /**
+     * The agent this assembly is for. The agent loop passes it on every
+     * per-step `assemble({ agent })`; variable providers project per-agent
+     * facts from it (`options.model` → `{{model}}`, `session.header.cwd` →
+     * `{{cwd}}`). Optional because a bare `assemble()` (tests, diagnostics)
+     * has no agent — providers must tolerate its absence.
+     */
+    agent?: Agent
+  }
+}
+
 /**
- * Options an agent is created with.
+ * Options an agent is created with. The persona is NOT here — it is the
+ * deployment's `persona` config on the dsh-system-prompt plugin, shared by
+ * every agent in the context.
  * Merge-extensible: plugins declare extra fields via declaration merging.
  */
 export interface AgentOptions {
   /** Model name (must have a registered adapter at call time). */
   model?: string
-  /** Per-agent system prompt appended after the assembled sections. */
-  systemPrompt?: string
 }
 
 export interface SendOptions {

packages/core/agent/tsconfig.json

@@ -22,6 +22,9 @@
     },
     {
       "path": "../../core/session"
+    },
+    {
+      "path": "../../core/system-prompt"
     }
   ]
 }

packages/core/system-prompt/README.md

@@ -1,37 +1,48 @@
 # dsh-system-prompt
 
-System prompt assembly registry. Plugins contribute ordered text sections and tool-schema providers; the agent loop calls `assemble()` once per step.
+System prompt assembly registry. Plugins contribute ordered text sections, tool-schema providers, and named prompt variables; the agent loop calls `assemble(context)` once per step, and `renderPrompt(assembly)` is the full system prompt the model sees. The plugin registers the harness-owned openers itself — the static `harness:identity` section and the deployment's `deployment:persona` section — so they exist for every agent regardless of which loop plugin drives it.
+
+## Config
+
+| Key | Default | Meaning |
+|---|---|---|
+| `persona` | `''` | The deployment persona: the ONE deployment-authored prompt fragment, rendered as the order-0 `deployment:persona` section and shared by every agent in the context (subagents included). A template — complete `{{…}}` groups are interpreted strictly against the registered variables (the shipped loop registers `{{model}}`/`{{cwd}}`), with no escape syntax for literal braces yet. Empty ⇒ the section is dropped at render. |
 
 ## Service: `SystemPrompt` (ctx key: `systemPrompt`)
 
 ### Public API
 
-- `ctx.systemPrompt.section(section: PromptSection): () => void` Contribute a section. Disposed with the calling fiber.
+- `ctx.systemPrompt.section(section: PromptSection): () => void` Contribute a section. Duplicate names throw. Disposed with the calling fiber.
 - `ctx.systemPrompt.tools(provider: () => ToolSchema[]): () => void` Contribute tool schemas (evaluated at each assembly). Disposed with the calling fiber.
-- `ctx.systemPrompt.assemble(): Promise<PromptAssembly>` Assemble the current prompt. Runs through the `system-prompt/assemble` waterfall.
+- `ctx.systemPrompt.variable(name: string, provider: (context) => string | undefined): () => void` Contribute a prompt variable, referenced from section text as `{{name}}`. Duplicate or unreferenceable names throw; `undefined` means "no value for this assembly". Disposed with the calling fiber.
+- `ctx.systemPrompt.assemble(context?: AssembleContext): Promise<PromptAssembly>` Assemble the prompt for one caller. Runs through the `system-prompt/assemble` waterfall.
 
 ### Events
 
 | Event | Mode | Purpose |
 |---|---|---|
-| `system-prompt/assemble` | waterfall | Mutate/extend the assembly before it reaches the model |
-| `system-prompt/change` | emit | A section or tool provider was registered or unregistered |
+| `system-prompt/assemble` | waterfall | Mutate/extend the assembly (with the caller's context) before it reaches the model |
+| `system-prompt/change` | emit | A section, tool provider, or variable was registered or unregistered |
 
 ### Key types
 
-- `PromptSection` — `{ name, order, text: string | (() => string) }`. Sections are concatenated in ascending `order`.
-- `PromptAssembly` — `{ sections: PromptSection[], tools: ToolSchema[] }`. Tool schemas are part of the assembly by design: "what the model is told it can do" is one coherent thing, even though adapters transmit schemas as a separate wire field.
-- `renderPrompt(assembly)` — joins section texts with blank lines.
+- `AssembleContext` — what one `assemble()` call is FOR. Declared empty here and merge-extensible; `dsh-agent` declares `agent?: Agent`, so providers project per-agent facts. Providers must tolerate absent fields (a bare `assemble()` carries an empty context).
+- `PromptSection` — `{ name, order, text: string | ((context) => string) }`. Sections are concatenated in ascending `order`. Order bands: `-100` is the harness identity, `0` the deployment persona (both registered by this plugin), tool guidance uses `100–199`; other negative orders also render before the persona.
+- `PromptAssembly` — `{ sections: AssembledSection[], tools: ToolSchema[], variables: Record<string, string | undefined> }`. Section texts arrive resolved but not yet interpolated; `variables` holds every registered variable resolved against the context. Tool schemas are part of the assembly by design: "what the model is told it can do" is one coherent thing, even though adapters transmit schemas as a separate wire field.
+- `renderPrompt(assembly)` — interpolates `{{variable}}` references in each section, drops empty sections, joins with blank lines. STRICT: an unknown reference (`Object.hasOwn` lookup — prototype names like `{{constructor}}` are unknown), a registered-but-valueless reference, a malformed complete `{{…}}` group, or a `{{` that opens no complete group while a `}}` still follows (`{{{model}}}`) throws — fail loud beats shipping a malformed prompt. A lone `{{` with no `}}` anywhere after it passes through verbatim; substituted values are never re-scanned.
 
-Merge-extensible: plugins can declare extra fields on `PromptAssembly` via declaration merging.
+Merge-extensible: plugins can declare extra fields on `PromptAssembly` and `AssembleContext` via declaration merging.
 
 ### Extension points
 
-- Section providers: AGENTS.md reader, cwd notifier, persona config, etc.
+- Section providers: tool packages own their cross-call guidance (`tool:bash`, `tool:read`, …); this plugin owns `harness:identity` and `deployment:persona`.
+- Variable providers: the agent loop registers `model` and `cwd`; any plugin can register the facts it owns (a future `date`, git state, …).
 - Tool schema providers: `ToolRegistry` registers itself as a tool provider automatically.
-- The `system-prompt/assemble` waterfall: mutate or replace the assembly (system-prompt configurability, dynamic tool filtering).
+- The `system-prompt/assemble` waterfall: mutate or replace the assembly per caller (dynamic tool filtering, extra variables).
 
 ### What is NOT here
 
-- Any hardcoded prompt text — every section comes from plugins.
+- Any deployment-authored prompt text outside config — the persona is this plugin's `persona` config, and every other section comes from the plugin that owns the fact. (The `harness:identity` line is deliberately a code literal: a harness fact, not a deployment choice; the `system-prompt/assemble` waterfall is the escape valve for a deployment that must drop it.)
 - Prompt compaction (belongs on the `agent/pre-step` seam in `dsh-agent`).
+
+Design rationale: [the prompt-variables RFC](../../../docs/rfc/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md).

packages/core/system-prompt/package.json

@@ -25,6 +25,9 @@
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "cordis": "^4.0.0-rc.6"
   },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
   "devDependencies": {
     "@deepseek-ai/dsh-llm": "workspace:^",
     "cordis": "^4.0.0-rc.6"

packages/core/system-prompt/src/index.ts

@@ -1,12 +1,19 @@
 /**
- * System prompt assembly registry. Plugins contribute ordered text sections and
- * tool schema providers; `assemble()` collates them through a waterfall that
- * runs once per step.
+ * System prompt assembly registry. Plugins contribute ordered text sections,
+ * tool schema providers, and named prompt variables; `assemble(context)`
+ * collates them through a waterfall that runs once per step, and
+ * `renderPrompt` interpolates `{{variable}}` references into the final text.
+ *
+ * The harness-owned prompt openers live here too: this plugin registers the
+ * static `harness:identity` section (order −100) and the deployment's
+ * `deployment:persona` section (order 0, from its `persona` config), so they
+ * exist for every agent regardless of which loop plugin drives it.
  *
  * @module @deepseek-ai/dsh-system-prompt
  */
 
 import { Context, Service } from 'cordis'
+import z from 'schemastery'
 import type { ToolSchema } from '@deepseek-ai/dsh-llm'
 
 declare module 'cordis' {
@@ -17,30 +24,63 @@ declare module 'cordis' {
   interface Events {
     /**
      * Waterfall around prompt assembly — mutate or extend the
-     * {@link PromptAssembly} (sections + tool schemas) before it is rendered.
-     * Bound to the {@link SystemPrompt} service; call `next()` to delegate.
-     * @param assembly - the assembly built from the registered sections and
-     *   tool providers; listeners may mutate it or return a replacement.
+     * {@link PromptAssembly} (sections + tools + variables) before it is
+     * rendered. Bound to the {@link SystemPrompt} service; call `next()` to
+     * delegate.
+     * @param assembly - the assembly built from the registered sections, tool
+     *   providers, and variable providers; listeners may mutate it or return a
+     *   replacement.
+     * @param context - the per-assembly {@link AssembleContext} the caller
+     *   passed to {@link SystemPrompt.assemble} (e.g. which agent the prompt
+     *   is for), so a listener can filter or extend per agent.
      * @mode waterfall
      */
-    'system-prompt/assemble'(this: SystemPrompt, assembly: PromptAssembly, next: () => Promise<PromptAssembly>): Promise<PromptAssembly>
+    'system-prompt/assemble'(this: SystemPrompt, assembly: PromptAssembly, context: AssembleContext, next: () => Promise<PromptAssembly>): Promise<PromptAssembly>
     /**
-     * A section or tool provider was registered or unregistered (the assembly
-     * inputs changed).
+     * A section, tool provider, or variable provider was registered or
+     * unregistered (the assembly inputs changed).
      * @mode emit
      */
     'system-prompt/change'(): void
   }
 }
 
-/** One contributed section of the system prompt. */
+/**
+ * Per-assembly input: what one {@link SystemPrompt.assemble} call is FOR.
+ * Declared empty here so this package stays agnostic of who assembles;
+ * merge-extensible — `@deepseek-ai/dsh-agent` declares the `agent` field, so
+ * section text and variable providers can be functions of the calling agent.
+ * Every field is optional by nature: a bare `assemble()` (tests, diagnostics)
+ * carries an empty context, and providers must tolerate absent fields.
+ */
+export interface AssembleContext {}
+
+/** One contributed section of the system prompt (registry input). */
 export interface PromptSection {
-  /** Unique name (diagnostics / dedup). */
+  /** Unique name — a duplicate registration throws (see {@link SystemPrompt.section}). */
   name: string
-  /** Sections are concatenated in ascending order. */
+  /**
+   * Sections are concatenated in ascending order. Convention: `-100` is the
+   * harness identity, `0` the deployment persona, tool guidance uses 100–199;
+   * other negative orders also render before the persona.
+   */
   order: number
-  /** Static text or a provider evaluated at each assembly. */
-  text: string | (() => string)
+  /**
+   * Static text or a provider evaluated at each assembly with that assembly's
+   * {@link AssembleContext}. The text may reference `{{variable}}`s — they are
+   * interpolated later, by {@link renderPrompt}.
+   */
+  text: string | ((context: AssembleContext) => string)
+}
+
+/** One section of an assembly: {@link PromptSection} with its text resolved. */
+export interface AssembledSection {
+  /** The contributing section's unique name. */
+  name: string
+  /** The contributing section's order (sections arrive sorted ascending). */
+  order: number
+  /** The resolved (but not yet interpolated) section text. */
+  text: string
 }
 
 /**
@@ -50,43 +90,156 @@ export interface PromptSection {
  * can do" is one coherent thing managed here, even though adapters transmit
  * `tools` as a separate wire field rather than prompt text.
  *
+ * `variables` carries every registered prompt variable resolved against this
+ * assembly's context — key present means registered, `undefined` value means
+ * "no value for this assembly" (referencing it renders an error). Section
+ * texts are resolved but NOT yet interpolated; {@link renderPrompt} applies
+ * the variables, so waterfall listeners can still add sections or variables.
+ *
  * Merge-extensible: plugins can declare extra fields on this interface.
  */
 export interface PromptAssembly {
-  sections: PromptSection[]
+  sections: AssembledSection[]
   tools: ToolSchema[]
+  variables: Record<string, string | undefined>
 }
 
-/** Renders the text part of an assembly (sections joined by blank lines). */
+/** Valid variable names: how they are written between the braces. */
+const VARIABLE_NAME = /^[a-z][a-z0-9_]*$/
+
+/** A complete `{{...}}` reference group at the scan position (validated after). */
+const GROUP_AT = /^\{\{([^{}]*)\}\}/
+
+export interface Config {
+  /**
+   * The deployment's persona — the ONE deployment-authored fragment of the
+   * system prompt, rendered as the order-0 `deployment:persona` section
+   * (after the harness identity, before all tool guidance). Every agent in
+   * the context shares it, subagents included. Template, not free-form text:
+   * every complete `{{…}}` group is interpreted strictly against the
+   * registered prompt variables (the shipped agent loop registers `{{model}}`
+   * and `{{cwd}}`), and there is no escape syntax for literal `{{…}}` prose
+   * yet (a deliberate deferral; see the prompt-variables RFC). Defaults to
+   * `''` — the empty section is dropped at render, so a persona-less
+   * deployment opens with the harness identity alone.
+   */
+  persona?: string
+}
+
+/**
+ * Renders the text part of an assembly: interpolates `{{variable}}`
+ * references in each section from `assembly.variables`, drops empty sections,
+ * and joins the rest with blank lines.
+ *
+ * Strict by design (fail loud beats shipping a malformed prompt): a reference
+ * to an unregistered variable, to a registered variable with no value for
+ * this assembly, a complete `{{…}}` group that is not a well-formed variable
+ * name (e.g. `{{ model }}`), or a `{{` that does not open a complete group
+ * while a `}}` still follows (e.g. `{{{model}}}`, `{{a{b}}`) all throw. A
+ * lone `{{` with no `}}` anywhere after it is ordinary prose and passes
+ * through verbatim. Substituted values are never re-scanned.
+ */
 export function renderPrompt(assembly: PromptAssembly): string {
   return assembly.sections
-    .map(section => typeof section.text === 'function' ? section.text() : section.text)
+    .map(section => interpolate(section, assembly.variables))
     .filter(text => text.length > 0)
     .join('\n\n')
 }
 
+/** Interpolate one section's `{{variable}}` references (see {@link renderPrompt}). */
+function interpolate(section: AssembledSection, variables: Record<string, string | undefined>): string {
+  const text = section.text
+  let result = ''
+  let last = 0
+  for (let open = text.indexOf('{{'); open >= 0; open = text.indexOf('{{', last)) {
+    const group = GROUP_AT.exec(text.slice(open))
+    if (group === null) {
+      // No complete simple group starts at this `{{`. A `}}` further on means
+      // a mangled reference (extra or nested braces) — fail loud. With no
+      // closing `}}` anywhere after, it is ordinary prose (shell, JSON) and
+      // passes through verbatim.
+      if (text.indexOf('}}', open + 2) >= 0) {
+        throw new Error(`malformed prompt variable reference at "${text.slice(open, open + 16)}…" in section "${section.name}" (references are complete simple {{name}} groups)`)
+      }
+      result += text.slice(last, open + 2)
+      last = open + 2
+      continue
+    }
+    // group[0] is the whole `{{...}}` match (a plain string, no optional
+    // index): the name is its interior. `{{}}` yields '' → the malformed path.
+    const name = group[0].slice(2, -2)
+    if (!VARIABLE_NAME.test(name)) {
+      throw new Error(`malformed prompt variable reference "{{${name}}}" in section "${section.name}" (variable names match ${String(VARIABLE_NAME)})`)
+    }
+    // Object.hasOwn, NOT `in`: `in` walks the prototype chain, so an
+    // unregistered `{{constructor}}` would resolve to Object.prototype's and
+    // splice a function's source text into the prompt instead of throwing.
+    if (!Object.hasOwn(variables, name)) {
+      const known = Object.keys(variables)
+      throw new Error(`unknown prompt variable "{{${name}}}" in section "${section.name}"; registered variables: ${known.length > 0 ? known.join(', ') : '(none)'}`)
+    }
+    const value = variables[name]
+    if (value === undefined) {
+      throw new Error(`prompt variable "{{${name}}}" has no value for this assembly (section "${section.name}")`)
+    }
+    result += text.slice(last, open) + value
+    last = open + group[0].length
+  }
+  return result + text.slice(last)
+}
+
 /**
  * Registry service (`ctx.systemPrompt`): plugins contribute ordered text
- * sections and tool-schema providers; the agent loop calls `assemble()` once
- * per step.
+ * sections, tool-schema providers, and named prompt variables; the agent loop
+ * calls `assemble(context)` once per step. Registers the harness-owned
+ * `harness:identity` and `deployment:persona` sections itself (see
+ * {@link Config.persona}).
  */
 export class SystemPrompt extends Service {
+  static Config: z<Config> = z.object({
+    persona: z.string().default(''),
+  })
+
   private sections: PromptSection[] = []
   private toolProviders: (() => ToolSchema[])[] = []
+  private variableProviders = new Map<string, (context: AssembleContext) => string | undefined>()
 
-  constructor(ctx: Context) {
+  constructor(ctx: Context, public config: Config) {
     super(ctx, 'systemPrompt')
+    // The harness-owned openers. They live HERE (not on the loop plugin) so a
+    // deployment that swaps in a different loop keeps them: the identity is a
+    // harness fact stated ahead of everything, and the persona is the
+    // deployment's config, one section of the full prompt, never the whole.
+    // An empty persona still RESERVES the section name (one owner — a plugin
+    // re-registering it throws); renderPrompt drops the empty text.
+    this.section({
+      name: 'harness:identity',
+      order: -100,
+      text: 'You are an AI agent powered by the DeepSeek Harness SDK.',
+    })
+    this.section({
+      name: 'deployment:persona',
+      order: 0,
+      // The schema already defaulted an omitted persona to ''; the ?? only
+      // narrows the optional-input TYPE, it never supplies a different value.
+      text: config.persona ?? '',
+    })
   }
 
   /**
    * Contribute a text section to the system prompt. Order is determined by
-   * `section.order` (ascending). The section is removed when the calling
+   * `section.order` (ascending). Throws if a section with the same name is
+   * already registered (a duplicate would silently double prompt text — e.g.
+   * a double-loaded tool plugin). The section is removed when the calling
    * fiber is disposed. Emits `system-prompt/change` on register/unregister.
    * @param section - the section to contribute (name, order, text or provider).
    * @returns the disposer that removes the section.
    */
   section(section: PromptSection): () => void {
     const dispose = this.ctx.effect(function* (this: SystemPrompt) {
+      if (this.sections.some(existing => existing.name === section.name)) {
+        throw new Error(`prompt section "${section.name}" is already registered`)
+      }
       this.sections.push(section)
       // Yield the rollback BEFORE emitting `system-prompt/change`: a generator
       // effect collects each yielded disposer before the next step runs, so a
@@ -130,25 +283,71 @@ export class SystemPrompt extends Service {
   }
 
   /**
-   * Assemble the current prompt (sections sorted by order, tools collected
-   * from all providers). Section records are top-level clones (the `text`
-   * provider may be a function and is intentionally shared); tool schemas are
-   * deep-cloned because adapters and request waterfalls may mutate schema
-   * objects. Runs through the `system-prompt/assemble` waterfall, giving
-   * listeners the opportunity to mutate or replace the assembly before it
-   * reaches the model. Await the result before reading the assembly values —
-   * waterfall listeners may be async.
+   * Contribute a named prompt variable, referenced from section text as
+   * `{{name}}`. The provider is evaluated at each assembly with that
+   * assembly's {@link AssembleContext}; returning `undefined` means "no value
+   * for this assembly" (a section referencing it then fails to render — a
+   * deployment must not claim facts it does not have). Throws on a name that
+   * does not match `[a-z][a-z0-9_]*` (it could never be referenced) or is
+   * already registered. Removed when the calling fiber is disposed; emits
+   * `system-prompt/change` on register/unregister.
+   * @param name - the reference name (matches `[a-z][a-z0-9_]*`).
+   * @param provider - evaluated at every {@link assemble} for the value.
+   * @returns the disposer that removes the variable.
+   */
+  variable(name: string, provider: (context: AssembleContext) => string | undefined): () => void {
+    const dispose = this.ctx.effect(function* (this: SystemPrompt) {
+      if (!VARIABLE_NAME.test(name)) {
+        throw new Error(`invalid prompt variable name "${name}" (must match ${String(VARIABLE_NAME)})`)
+      }
+      if (this.variableProviders.has(name)) {
+        throw new Error(`prompt variable "${name}" is already registered`)
+      }
+      this.variableProviders.set(name, provider)
+      // Yield the rollback BEFORE emitting `system-prompt/change` (see section()).
+      yield () => {
+        this.variableProviders.delete(name)
+        this.ctx.emit('system-prompt/change')
+      }
+      this.ctx.emit('system-prompt/change')
+    }.bind(this), 'systemPrompt.variable()')
+    // ctx.effect's disposer returns Promise<void>; our disposer API is
+    // synchronous fire-and-forget — discard the (always-resolved) promise.
+    return () => void dispose()
+  }
+
+  /**
+   * Assemble the current prompt for one caller: section texts are resolved
+   * against `context` and sorted by order, tools collected from all
+   * providers, and every registered variable resolved against `context` into
+   * `assembly.variables`. Tool schemas are deep-cloned because adapters and
+   * request waterfalls may mutate schema objects. Runs through the
+   * `system-prompt/assemble` waterfall, giving listeners the opportunity to
+   * mutate or replace the assembly before it reaches the model. Await the
+   * result before reading the assembly values — waterfall listeners may be
+   * async. Interpolation happens later, in {@link renderPrompt}.
+   * @param context - what this assembly is for (defaults to an empty context;
+   *   see {@link AssembleContext}).
    * @returns the assembly after the waterfall has run.
    */
-  assemble(): Promise<PromptAssembly> {
+  assemble(context: AssembleContext = {}): Promise<PromptAssembly> {
+    const variables: Record<string, string | undefined> = {}
+    for (const [name, provider] of this.variableProviders) {
+      variables[name] = provider(context)
+    }
     const assembly: PromptAssembly = {
       sections: this.sections
-        .map(section => ({ ...section }))
+        .map(section => ({
+          name: section.name,
+          order: section.order,
+          text: typeof section.text === 'function' ? section.text(context) : section.text,
+        }))
         .sort((a, b) => a.order - b.order),
       tools: this.toolProviders.flatMap(provider =>
         provider().map(tool => ({ ...tool, parameters: structuredClone(tool.parameters) }))),
+      variables,
     }
-    return this.ctx.waterfall(this, 'system-prompt/assemble', assembly, () => Promise.resolve(assembly))
+    return this.ctx.waterfall(this, 'system-prompt/assemble', assembly, context, () => Promise.resolve(assembly))
   }
 }
 

packages/core/system-prompt/tests/system-prompt.spec.ts

@@ -1,21 +1,81 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import SystemPrompt, { PromptAssembly, PromptSection, renderPrompt } from '@deepseek-ai/dsh-system-prompt'
+import SystemPrompt, { AssembleContext, PromptAssembly, renderPrompt } from '@deepseek-ai/dsh-system-prompt'
+
+/**
+ * Every assembly carries the plugin's own built-ins — `harness:identity`
+ * (order −100) and `deployment:persona` (order 0, from config). Tests about
+ * registry MECHANICS strip them with {@link contributed} to stay focused on
+ * their own sections; the built-ins' behavior is pinned by its own describe.
+ */
+const BUILT_IN = ['harness:identity', 'deployment:persona']
+const IDENTITY = 'You are an AI agent powered by the DeepSeek Harness SDK.'
+function contributed(assembly: PromptAssembly): PromptAssembly['sections'] {
+  return assembly.sections.filter(section => !BUILT_IN.includes(section.name))
+}
 
 describe('SystemPrompt', () => {
-  it('assembles sections in order with dynamic text and collected tools', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SystemPrompt)
+  describe('built-in sections', () => {
+    it('registers the harness identity and the configured deployment persona', async () => {
+      const ctx = new Context()
+      await ctx.plugin(SystemPrompt, { persona: 'You are DeepSeek Harness SDK.' })
+
+      const assembly = await ctx.systemPrompt.assemble()
+      expect(assembly.sections.map(s => [s.name, s.order])).toEqual([
+        ['harness:identity', -100],
+        ['deployment:persona', 0],
+      ])
+      expect(renderPrompt(assembly)).toBe(`${IDENTITY}\n\nYou are DeepSeek Harness SDK.`)
+      // The names are reserved by the plugin — one owner per section.
+      expect(() => ctx.systemPrompt.section({ name: 'deployment:persona', order: 0, text: 'imposter' }))
+        .toThrow('prompt section "deployment:persona" is already registered')
+    })
+
+    it('renders no persona section for a persona-less deployment (empty default)', async () => {
+      const ctx = new Context()
+      await ctx.plugin(SystemPrompt)
+      expect(renderPrompt(await ctx.systemPrompt.assemble())).toBe(IDENTITY)
+    })
+
+    it('tolerates a schema-bypassing direct construction (persona omitted)', async () => {
+      // ctx.plugin validates + defaults the config first; a direct construction
+      // skips the schema, so the ctor's `?? ''` narrowing is what fires.
+      const ctx = new Context()
+      const service = new SystemPrompt(ctx, {})
+      expect(renderPrompt(await service.assemble())).toBe(IDENTITY)
+    })
+  })
+
+  it('assembles sections in order with context-resolved text and collected tools', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt, { persona: 'You are DeepSeek Harness SDK.' })
 
-    ctx.systemPrompt.section({ name: 'persona', order: 0, text: 'You are DeepSeek Code.' })
     ctx.systemPrompt.section({ name: 'cwd', order: 20, text: () => 'cwd: /tmp' })
     ctx.systemPrompt.section({ name: 'rules', order: 10, text: 'Be precise.' })
     ctx.systemPrompt.tools(() => [{ name: 'echo', description: 'echo back', parameters: {} }])
 
     const assembly = await ctx.systemPrompt.assemble()
-    expect(assembly.sections.map(s => s.name)).toEqual(['persona', 'rules', 'cwd'])
+    expect(assembly.sections.map(s => s.name)).toEqual(['harness:identity', 'deployment:persona', 'rules', 'cwd'])
+    expect(assembly.sections.map(s => s.text)).toEqual([IDENTITY, 'You are DeepSeek Harness SDK.', 'Be precise.', 'cwd: /tmp'])
     expect(assembly.tools).toEqual([{ name: 'echo', description: 'echo back', parameters: {} }])
-    expect(renderPrompt(assembly)).toBe('You are DeepSeek Code.\n\nBe precise.\n\ncwd: /tmp')
+    expect(assembly.variables).toEqual({})
+    expect(renderPrompt(assembly)).toBe(`${IDENTITY}\n\nYou are DeepSeek Harness SDK.\n\nBe precise.\n\ncwd: /tmp`)
+  })
+
+  it('resolves section text providers against the assemble context, at each assemble call', async () => {
+    // The context is HOW per-agent sections work (the loop passes { agent });
+    // this spec stays agent-agnostic and smuggles a marker through a plain field.
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    let calls = 0
+    ctx.systemPrompt.section({
+      name: 'dynamic',
+      order: 0,
+      text: (context: AssembleContext) => `call ${++calls} for ${(context as { who?: string }).who ?? 'nobody'}`,
+    })
+
+    expect(contributed(await ctx.systemPrompt.assemble({ who: 'alice' } as AssembleContext))[0]!.text).toBe('call 1 for alice')
+    expect(contributed(await ctx.systemPrompt.assemble())[0]!.text).toBe('call 2 for nobody')
   })
 
   it('removes contributions when the contributing fiber is disposed (HMR safety)', async () => {
@@ -25,13 +85,30 @@ describe('SystemPrompt', () => {
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
       inner.systemPrompt.section({ name: 'scoped', order: 0, text: 'scoped section' })
       inner.systemPrompt.tools(() => [{ name: 'scoped-tool', description: '', parameters: {} }])
+      inner.systemPrompt.variable('scoped_var', () => 'v')
     }, { inject: ['systemPrompt'] }))
 
-    expect((await ctx.systemPrompt.assemble()).sections).toHaveLength(1)
+    const before = await ctx.systemPrompt.assemble()
+    expect(contributed(before)).toHaveLength(1)
+    expect(before.variables).toEqual({ scoped_var: 'v' })
     await fiber.dispose()
     const assembly = await ctx.systemPrompt.assemble()
-    expect(assembly.sections).toHaveLength(0)
+    expect(contributed(assembly)).toHaveLength(0)
+    // The built-ins belong to the service fiber, so they survive the plugin's disposal.
+    expect(assembly.sections.map(s => s.name)).toEqual(BUILT_IN)
     expect(assembly.tools).toHaveLength(0)
+    expect(assembly.variables).toEqual({})
+  })
+
+  it('rejects a duplicate section name (a double-loaded plugin must fail, not double its text)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    ctx.systemPrompt.section({ name: 'dup', order: 0, text: 'first' })
+    expect(() => ctx.systemPrompt.section({ name: 'dup', order: 1, text: 'second' }))
+      .toThrow('prompt section "dup" is already registered')
+    // The failed registration leaked nothing; the original stays intact.
+    const assembly = await ctx.systemPrompt.assemble()
+    expect(contributed(assembly).map(s => s.text)).toEqual(['first'])
   })
 
   it('rolls back a section when a system-prompt/change listener throws (P1-1)', async () => {
@@ -47,12 +124,12 @@ describe('SystemPrompt', () => {
     })
 
     expect(() => ctx.systemPrompt.section({ name: 'p', order: 0, text: 'persona' })).toThrow('boom change listener')
-    expect((await ctx.systemPrompt.assemble()).sections).toHaveLength(0) // nothing leaked
+    expect(contributed(await ctx.systemPrompt.assemble())).toHaveLength(0) // nothing leaked
 
     // Subsequent listener-free register contributes exactly once.
     off()
     ctx.systemPrompt.section({ name: 'p', order: 0, text: 'persona' })
-    expect((await ctx.systemPrompt.assemble()).sections.map(s => s.name)).toEqual(['p'])
+    expect(contributed(await ctx.systemPrompt.assemble()).map(s => s.name)).toEqual(['p'])
   })
 
   it('rolls back a tool provider when a system-prompt/change listener throws (P1-1)', async () => {
@@ -72,26 +149,47 @@ describe('SystemPrompt', () => {
     expect((await ctx.systemPrompt.assemble()).tools.map(t => t.name)).toEqual(['t'])
   })
 
-  it('composes multiple system-prompt/assemble waterfall listeners in order', async () => {
+  it('rolls back a variable when a system-prompt/change listener throws (P1-1)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+
+    let threw = false
+    const off = ctx.on('system-prompt/change', () => {
+      if (!threw) { threw = true; throw new Error('boom change listener') }
+    })
+
+    expect(() => ctx.systemPrompt.variable('v', () => 'x')).toThrow('boom change listener')
+    expect((await ctx.systemPrompt.assemble()).variables).toEqual({}) // nothing leaked
+
+    off()
+    ctx.systemPrompt.variable('v', () => 'x')
+    expect((await ctx.systemPrompt.assemble()).variables).toEqual({ v: 'x' })
+  })
+
+  it('composes multiple system-prompt/assemble waterfall listeners in order, with the context', async () => {
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
     ctx.systemPrompt.section({ name: 'base', order: 0, text: 'base' })
 
     // Listener A appends a section, then delegates.
-    ctx.on('system-prompt/assemble', async (assembly: PromptAssembly, next) => {
+    const contexts: AssembleContext[] = []
+    ctx.on('system-prompt/assemble', async (assembly: PromptAssembly, context, next) => {
+      contexts.push(context)
       assembly.sections.push({ name: 'from-a', order: 100, text: 'a' })
       return next()
     })
     // Listener B (registered later, runs after A) sees A's contribution.
     const seen: string[][] = []
-    ctx.on('system-prompt/assemble', async (assembly: PromptAssembly, next) => {
+    ctx.on('system-prompt/assemble', async (assembly: PromptAssembly, _context, next) => {
       seen.push(assembly.sections.map(s => s.name))
       return next()
     })
 
-    const assembly = await ctx.systemPrompt.assemble()
-    expect(seen).toEqual([['base', 'from-a']])
-    expect(assembly.sections.map(s => s.name)).toEqual(['base', 'from-a'])
+    const passed: AssembleContext = {}
+    const assembly = await ctx.systemPrompt.assemble(passed)
+    expect(seen).toEqual([['harness:identity', 'deployment:persona', 'base', 'from-a']])
+    expect(assembly.sections.map(s => s.name)).toEqual(['harness:identity', 'deployment:persona', 'base', 'from-a'])
+    expect(contexts[0]).toBe(passed) // the caller's context reaches listeners
   })
 
   it('lets a waterfall listener short-circuit by not calling next()', async () => {
@@ -100,7 +198,7 @@ describe('SystemPrompt', () => {
     ctx.systemPrompt.section({ name: 'real', order: 0, text: 'real' })
 
     ctx.on('system-prompt/assemble', async () => {
-      return { sections: [], tools: [] } satisfies PromptAssembly
+      return { sections: [], tools: [], variables: {} } satisfies PromptAssembly
     })
 
     const assembly = await ctx.systemPrompt.assemble()
@@ -115,40 +213,33 @@ describe('SystemPrompt', () => {
 
     const first = await ctx.systemPrompt.assemble()
     first.sections[0]!.name = 'mutated'
+    first.sections[0]!.text = 'mutated'
     first.tools[0]!.description = 'mutated'
     const firstParameters = first.tools[0]!.parameters as { properties: Record<string, unknown> }
     firstParameters.properties['leak'] = { type: 'string' }
 
     const second = await ctx.systemPrompt.assemble()
-    expect(second.sections.map(section => section.name)).toEqual(['base'])
+    expect(second.sections.map(section => section.name)).toEqual(['harness:identity', 'deployment:persona', 'base'])
+    expect(second.sections[0]!.text).toBe(IDENTITY)
     expect(second.tools).toEqual([{ name: 't', description: 'tool', parameters: { type: 'object', properties: {} } }])
   })
 
   it('filters out empty section text from renderPrompt', () => {
-    // Direct test of renderPrompt: function returning empty string, and empty static text
     const result = renderPrompt({
       sections: [
-        { name: 'empty-fn', order: 0, text: () => '' },
+        { name: 'empty', order: 0, text: '' },
         { name: 'real', order: 1, text: 'content' },
-        { name: 'empty-static', order: 2, text: '' },
       ],
       tools: [],
+      variables: {},
     })
     expect(result).toBe('content')
   })
 
-  it('evaluates dynamic function-text sections at each renderPrompt call', () => {
-    let counter = 0
-    const section: PromptSection = { name: 'dynamic', order: 0, text: () => `call ${++counter}` }
-    expect(renderPrompt({ sections: [section], tools: [] })).toBe('call 1')
-    expect(renderPrompt({ sections: [section], tools: [] })).toBe('call 2')
-  })
-
   it('emits system-prompt/change when a tool provider is registered and disposed', async () => {
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
 
-    const changes: number = 0
     let changeCount = 0
     ctx.on('system-prompt/change', () => void changeCount++)
 
@@ -159,7 +250,6 @@ describe('SystemPrompt', () => {
     dispose()
     // disposal emits change again
     expect(changeCount).toBe(2)
-    void changes // silence unused
   })
 
   it('cleans up tool providers on fiber dispose', async () => {
@@ -180,10 +270,10 @@ describe('SystemPrompt', () => {
     await ctx.plugin(SystemPrompt)
 
     const dispose = ctx.systemPrompt.section({ name: 'direct', order: 0, text: 'direct section' })
-    expect((await ctx.systemPrompt.assemble()).sections).toHaveLength(1)
+    expect(contributed(await ctx.systemPrompt.assemble())).toHaveLength(1)
 
     dispose()
-    expect((await ctx.systemPrompt.assemble()).sections).toHaveLength(0)
+    expect(contributed(await ctx.systemPrompt.assemble())).toHaveLength(0)
   })
 
   it('removes tool provider when returned disposer is called directly', async () => {
@@ -196,4 +286,133 @@ describe('SystemPrompt', () => {
     dispose()
     expect((await ctx.systemPrompt.assemble()).tools).toHaveLength(0)
   })
+
+  describe('prompt variables', () => {
+    it('resolves each variable against the assemble context and emits change on register/unregister', async () => {
+      const ctx = new Context()
+      await ctx.plugin(SystemPrompt)
+      let changeCount = 0
+      ctx.on('system-prompt/change', () => void changeCount++)
+
+      const dispose = ctx.systemPrompt.variable('who', context => (context as { who?: string }).who)
+      expect(changeCount).toBe(1)
+
+      expect((await ctx.systemPrompt.assemble({ who: 'alice' } as AssembleContext)).variables).toEqual({ who: 'alice' })
+      // A provider returning undefined records "registered but no value here".
+      expect((await ctx.systemPrompt.assemble()).variables).toEqual({ who: undefined })
+
+      dispose()
+      expect(changeCount).toBe(2)
+      expect((await ctx.systemPrompt.assemble()).variables).toEqual({})
+    })
+
+    it('rejects a duplicate variable name and an unreferenceable name', async () => {
+      const ctx = new Context()
+      await ctx.plugin(SystemPrompt)
+      ctx.systemPrompt.variable('model', () => 'm1')
+      expect(() => ctx.systemPrompt.variable('model', () => 'm2'))
+        .toThrow('prompt variable "model" is already registered')
+      expect(() => ctx.systemPrompt.variable('Not Valid', () => 'x'))
+        .toThrow('invalid prompt variable name "Not Valid"')
+      // Neither failed registration leaked.
+      expect((await ctx.systemPrompt.assemble()).variables).toEqual({ model: 'm1' })
+    })
+
+    it('interpolates {{name}} references in section text at render — the persona included', async () => {
+      const ctx = new Context()
+      await ctx.plugin(SystemPrompt, { persona: 'You run on {{model}} in {{cwd}}.' })
+      ctx.systemPrompt.variable('model', () => 'deepseek-v4')
+      ctx.systemPrompt.variable('cwd', () => '/work')
+
+      expect(renderPrompt(await ctx.systemPrompt.assemble())).toBe(`${IDENTITY}\n\nYou run on deepseek-v4 in /work.`)
+    })
+
+    it('lets a waterfall listener add or override variables before render', async () => {
+      const ctx = new Context()
+      await ctx.plugin(SystemPrompt)
+      ctx.systemPrompt.section({ name: 's', order: 0, text: '{{extra}}' })
+      ctx.on('system-prompt/assemble', async (assembly: PromptAssembly, _context, next) => {
+        assembly.variables['extra'] = 'from-waterfall'
+        return next()
+      })
+      expect(renderPrompt(await ctx.systemPrompt.assemble())).toBe(`${IDENTITY}\n\nfrom-waterfall`)
+    })
+
+    it('throws on a reference to an unregistered variable, listing what exists', async () => {
+      const ctx = new Context()
+      await ctx.plugin(SystemPrompt)
+      ctx.systemPrompt.section({ name: 'persona', order: 0, text: 'on {{modle}}' })
+      ctx.systemPrompt.variable('model', () => 'm')
+      await expect(async () => renderPrompt(await ctx.systemPrompt.assemble()))
+        .rejects.toThrow('unknown prompt variable "{{modle}}" in section "persona"; registered variables: model')
+    })
+
+    it('names "(none)" when no variables are registered at all', () => {
+      expect(() => renderPrompt({ sections: [{ name: 's', order: 0, text: '{{x}}' }], tools: [], variables: {} }))
+        .toThrow('unknown prompt variable "{{x}}" in section "s"; registered variables: (none)')
+    })
+
+    it('throws when a referenced variable has no value for this assembly', () => {
+      expect(() => renderPrompt({
+        sections: [{ name: 'persona', order: 0, text: 'in {{cwd}}' }],
+        tools: [],
+        variables: { cwd: undefined },
+      })).toThrow('prompt variable "{{cwd}}" has no value for this assembly (section "persona")')
+    })
+
+    it('throws on a malformed complete reference, e.g. inner spaces', () => {
+      expect(() => renderPrompt({
+        sections: [{ name: 's', order: 0, text: 'on {{ model }}' }],
+        tools: [],
+        variables: { model: 'm' },
+      })).toThrow('malformed prompt variable reference "{{ model }}" in section "s"')
+    })
+
+    it('leaves a lone {{ verbatim only when NO }} follows anywhere after it', () => {
+      const text = renderPrompt({
+        sections: [{ name: 's', order: 0, text: 'shell ${X:-{{fallback} stays' }],
+        tools: [],
+        variables: {},
+      })
+      expect(text).toBe('shell ${X:-{{fallback} stays')
+    })
+
+    it.each([
+      { text: '{{{model}}}', label: 'extra outer braces' },
+      { text: 'x {{a{b}} y {{model}}', label: 'nested brace inside a would-be group' },
+    ])('throws on a mangled reference with a }} still following ($label)', ({ text }) => {
+      expect(() => renderPrompt({
+        sections: [{ name: 's', order: 0, text }],
+        tools: [],
+        variables: { model: 'm' },
+      })).toThrow('malformed prompt variable reference at')
+    })
+
+    it('rejects {{constructor}} as UNKNOWN — prototype properties are not variables', () => {
+      // `in` would find Object.prototype.constructor and splice function
+      // source into the prompt; Object.hasOwn must reject it instead.
+      expect(() => renderPrompt({
+        sections: [{ name: 's', order: 0, text: 'on {{constructor}}' }],
+        tools: [],
+        variables: { model: 'm' },
+      })).toThrow('unknown prompt variable "{{constructor}}"')
+    })
+
+    it('a variable NAMED like a prototype property works once actually registered', async () => {
+      const ctx = new Context()
+      await ctx.plugin(SystemPrompt)
+      ctx.systemPrompt.section({ name: 's', order: 0, text: '{{constructor}}' })
+      ctx.systemPrompt.variable('constructor', () => 'own-value')
+      expect(renderPrompt(await ctx.systemPrompt.assemble())).toBe(`${IDENTITY}\n\nown-value`)
+    })
+
+    it('never re-scans substituted values (a value containing {{sneaky}} stays literal)', () => {
+      const text = renderPrompt({
+        sections: [{ name: 's', order: 0, text: 'v = {{model}}!' }],
+        tools: [],
+        variables: { model: 'literal {{sneaky}} inside' },
+      })
+      expect(text).toBe('v = literal {{sneaky}} inside!')
+    })
+  })
 })

packages/core/system-prompt/tsconfig.json

@@ -14,6 +14,9 @@
     {
       "path": "../../../vendor/cordis"
     },
+    {
+      "path": "../../../vendor/schemastery"
+    },
     {
       "path": "../../llm/llm"
     }

packages/core/tools/tests/gen-tool-catalog.spec.ts

@@ -93,10 +93,13 @@ describe('gen-tool-catalog render', () => {
       {
         pkg: '@deepseek-ai/dsh-tool-demo',
         source: 'packages/demo/tool-demo/src/index.ts',
+        requires: ['ctx.tools'],
+        writes: ['tool/result'],
         schemas: [{ name: 'demo', description: 'A demo tool.', parameters: { type: 'object', properties: {} } }],
       },
     ]
     const md = render(catalog)
+    expect(md).toContain('| `@deepseek-ai/dsh-tool-demo` | `demo` | `ctx.tools` | `tool/result` |')
     expect(md).toContain('## `@deepseek-ai/dsh-tool-demo`')
     expect(md).toContain('### `demo`')
     expect(md).toContain('A demo tool.')

packages/fs/fs-local/README.md

@@ -21,6 +21,6 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 
 ## `cwd` is not a sandbox
 
-`config.cwd` is a resolution default, not a containment boundary — absolute paths and `..` escape it. Enforce containment with a stricter `ctx.fs` backend or a permission plugin on the `tools/execute` waterfall. See [the filesystem capability-seam RFC's Risks section](../../../docs/rfc/implemented/architecture/2026-06-17-filesystem-capability-seam.md#risks).
+`config.cwd` is a resolution default, not a containment boundary — absolute paths and `..` escape it. Enforce containment with a stricter `ctx.fs` backend or a permission plugin on the `tools/execute` waterfall. See [the filesystem capability-seam RFC's Consequences section](../../../docs/rfc/implemented/architecture/2026-06-17-filesystem-capability-seam.md#consequences).
 
 The raw I/O lives in `src/fsio.ts` (Cordis-free, independently unit-tested); `src/index.ts` is the thin service wiring.

packages/fs/tool-fs/src/read.ts

@@ -72,7 +72,7 @@ export function applyReadTool(ctx: Context, caps: ReadToolCaps): void {
   ctx.systemPrompt.section({
     name: 'tool:read',
     order: 100,
-    text: 'Use the read tool to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.',
+    text: 'Use the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.',
   })
 
   ctx.tools.register(defineTool({

packages/fs/tool-fs/tests/fs-tools.e2e.ts

@@ -32,10 +32,10 @@ const SYSTEM = 'You are a coding assistant. Use the write tool to create files,
 describe.skipIf(!process.env.DEEPSEEK_API_KEY)('fs tools with-key smoke', () => {
   it('creates, reads, then edits a file — verified on disk', async () => {
     workdir = await mkdtemp(join(tmpdir(), 'dsh-fs-e2e-'))
-    ctx = await fsHarness(workdir)
+    ctx = await fsHarness(workdir, SYSTEM)
     // agentLoop.create prepares a session with no cwd, so the provider default
     // (config.cwd = workdir) is the workspace.
-    const agent = ctx.agentLoop.create(AgentId('fs-e2e'), { model: 'deepseek-v4-flash', systemPrompt: SYSTEM })
+    const agent = ctx.agentLoop.create(AgentId('fs-e2e'), { model: 'deepseek-v4-flash' })
 
     agent.send([{ type: 'text', text:
       'Create a file named note.txt containing exactly the line: status: draft. '
@@ -63,12 +63,12 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('fs tools with-key smoke', () =>
     workdir = configDir
     const sessionDir = await mkdtemp(join(tmpdir(), 'dsh-fs-e2e-session-'))
     try {
-      ctx = await fsHarness(configDir)
+      ctx = await fsHarness(configDir, SYSTEM)
       const handle = ctx.agents.create({
         agentId: AgentId('fs-e2e-cwd'),
         sessionId: SessionId(`fs-e2e-cwd-${Date.now()}`),
         meta: { cwd: sessionDir },
-        agentOptions: { model: 'deepseek-v4-flash', systemPrompt: SYSTEM },
+        agentOptions: { model: 'deepseek-v4-flash' },
       })
       handle.agent.send([{ type: 'text', text:
         'Use the write tool to create a file named where.txt containing exactly the line: here. Tell me when done.' }])

packages/fs/tool-fs/tests/harness.ts

@@ -18,13 +18,14 @@ import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
  *
  * `fsCwd` is the local backend's default base; a per-session cwd (set via a
  * session header) overrides it, but this harness creates agents without a
- * session cwd, so the provider default IS the workspace.
+ * session cwd, so the provider default IS the workspace. `persona` is the
+ * deployment persona (the system-prompt plugin's per-context config).
  */
-export async function fsHarness(fsCwd: string): Promise<Context> {
+export async function fsHarness(fsCwd: string, persona = ''): Promise<Context> {
   const ctx = new Context()
   await ctx.plugin(LlmService)
   await ctx.plugin(SessionStore)
-  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(SystemPrompt, { persona })
   await ctx.plugin(ToolRegistry)
   await ctx.plugin(AgentRegistry)
   await ctx.plugin(AgentLoop, { agents: [] })

packages/fs/tool-fs/tests/tools.spec.ts

@@ -133,10 +133,11 @@ describe('registration', () => {
     // withdraw both, not just the schemas.
     expect(ctx.tools.schemas()).toHaveLength(3)
     const sectionNames = (a: { sections: { name: string }[] }) => a.sections.map(s => s.name).sort()
-    expect(sectionNames(await ctx.systemPrompt.assemble())).toEqual(['tool:edit', 'tool:read', 'tool:write'])
+    expect(sectionNames(await ctx.systemPrompt.assemble())).toEqual(['deployment:persona', 'harness:identity', 'tool:edit', 'tool:read', 'tool:write'])
     await fiber.dispose()
     expect(ctx.tools.schemas()).toHaveLength(0)
-    expect((await ctx.systemPrompt.assemble()).sections).toHaveLength(0)
+    // Only the system-prompt plugin's own built-in sections remain.
+    expect(sectionNames(await ctx.systemPrompt.assemble())).toEqual(['deployment:persona', 'harness:identity'])
   })
 })
 

packages/subagent/subagent-acp/src/index.ts

@@ -90,6 +90,8 @@ type ResolvedConfig = Required<Omit<Config, 'cwd'>> & Pick<Config, 'cwd'>
  */
 class AcpProvider implements SubagentProvider {
   readonly capabilities: SubagentCapabilities = { outputSchema: false, depthLimit: false, toolFilter: false }
+  // Context contract: an out-of-process ACP child starts fresh — no parent conversation crosses the process boundary.
+  readonly inheritsParentContext = false
 
   constructor(readonly name: string, private readonly ctx: Context, private readonly config: ResolvedConfig) {}
 

packages/subagent/subagent-fork/src/index.ts

@@ -69,6 +69,8 @@ export function completedTurnPrefix(parent: Agent): SessionEvent[] {
  */
 class ForkProvider implements SubagentProvider {
   readonly capabilities: SubagentCapabilities = { outputSchema: true, depthLimit: true, toolFilter: false }
+  // Context contract: a forked child IS seeded with the parent's completed-turn prefix.
+  readonly inheritsParentContext = true
 
   constructor(
     readonly name: string,

packages/subagent/subagent-inprocess/README.md

@@ -9,7 +9,7 @@ The shared **in-process subagent run driver**. A pure library (no provider, no r
 Runs a child as a child [`Agent`](../../core/agent) on the same cordis context (`ctx.agents`):
 
 1. computes child depth = `depthOf(parent) + 1`; if `request.maxDepth` is set and exceeded, throws `SubagentDepthError` (the `depthLimit` capability); a `request.outputSchema` is asserted against the supported subset (`assertSupportedOutputSchema` from [dsh-tools](../../core/tools/README.md)) before any child exists;
-2. creates a child via `ctx.agents.create` with a fresh `AgentId`/`SessionId`, the parent's `cwd` + `parentSession` lineage, the optional `options.seed` (fork's completed-turn prefix; omitted for a fresh child), and `agentOptions` (the child inherits the **parent's model** by default — a child with no model can't run — overridable via `request.agentOptions.model`; the system prompt is NOT inherited; a structured run appends the `structured_output` instruction after the caller's prompt);
+2. creates a child via `ctx.agents.create` with a fresh `AgentId`/`SessionId`, the parent's `cwd` + `parentSession` lineage, the optional `options.seed` (fork's completed-turn prefix; omitted for a fresh child), and `agentOptions` (the child inherits the **parent's model** by default — a child with no model can't run — overridable via `request.agentOptions.model`; the deployment persona needs no inheritance — it is a context-wide prompt section);
 3. drives the one-shot: `child.send(prompt)` then `await child.whenIdle()` (ordering matters — `send` enqueues synchronously, so `whenIdle` observes the queued work and resolves on the child's `running → idle` transition, never before the turn starts); a structured child that finished a turn CLEANLY without calling `structured_output` is re-prompted (a nudge — a fresh turn) up to `options.structuredNudgeRetries` times;
 4. reads the result, scoped to the child's OWN events (everything at or after `seedLength`, so a seeded child that produced no message of its own never returns the seeded parent's last message): the last `assistant/message` content (deep-cloned — the log is frozen) and the last `turn/end.reason` mapped to a `SubagentStopReason`. A structured run surfaces the captured value as `result.structured`; a structured child that finished cleanly WITHOUT ever capturing settles `error` (a clean finish without the demanded result is a failure, not a success with a missing field).
 
@@ -23,7 +23,7 @@ Runs a child as a child [`Agent`](../../core/agent) on the same cordis context (
 
 The mechanism behind `outputSchema` for in-process children. One globally registered `structured_output` capture tool (its registered parameters are a placeholder) plus two listeners, registered once per root context and shared by every holder:
 
-- an `agent/request` waterfall listener registered `prepend: true` that post-processes `await next()` — **final-request enforcement**: the request that hits the wire never carries `structured_output` for an agent without a structured run, and always carries the run's OWN schema (as the tool's `parameters`) for one that has it. Per-agent shaping lives here because the tool registry and prompt assembly are context-global while schemas differ per concurrent child; cooperative mutate-then-`next()` would not survive a downstream listener returning a replacement request.
+- an `agent/request` waterfall listener registered `prepend: true` that post-processes `await next()` — **final-request enforcement**: the request that hits the wire never carries `structured_output` for an agent without a structured run, and for one that has it always carries the run's OWN schema (as the tool's `parameters`) plus the calling instruction appended to its `system` text (the demand travels with the tool — `AgentOptions` has no per-agent prompt field to carry it). Per-agent shaping lives here because the tool registry and prompt assembly are context-global while schemas differ per concurrent child; cooperative mutate-then-`next()` would not survive a downstream listener returning a replacement request.
 - an `agent/turn-continuation` listener (also `prepend: true` — an earlier-registered force-continue listener returning without `next()` must not decide the turn before the veto runs) that stops a child's turn once its output is captured, so a successful capture doesn't buy a wasted extra model step.
 
 The capture tool validates each call against the run's schema (`validateStructuredValue`) — violations become an `INVALID_ARGS` isError result the model retries in-turn; a valid call records the value.

packages/subagent/subagent-inprocess/src/index.ts

@@ -22,7 +22,6 @@ import { assertSupportedOutputSchema } from '@deepseek-ai/dsh-tools'
 import type { SubagentResult, SubagentRun, SubagentStartRequest, SubagentStopReason } from '@deepseek-ai/dsh-subagent'
 import {
   acquireStructuredRuntime,
-  STRUCTURED_OUTPUT_INSTRUCTION,
   STRUCTURED_OUTPUT_NUDGE,
   type StructuredAcquisition,
 } from './structured.ts'
@@ -133,18 +132,14 @@ export function startInProcessRun(
   const seedLength = options.seed?.length ?? 0
   const parentHeader = request.parent.session.header
   // Inherit the parent's model by default (a child with no model cannot run);
-  // an explicit `request.agentOptions.model` overrides it. The parent's
-  // systemPrompt is NOT inherited — a fresh child is a clean specialist unless
-  // the caller supplies one. A structured run appends the structured_output
-  // instruction after whatever prompt the caller supplied.
-  const callerPrompt = request.agentOptions?.systemPrompt
-  const systemPrompt = schema === undefined
-    ? callerPrompt
-    : [callerPrompt, STRUCTURED_OUTPUT_INSTRUCTION].filter(text => text !== undefined && text.length > 0).join('\n\n')
+  // an explicit `request.agentOptions.model` overrides it. The persona needs
+  // no inheritance: the deployment persona is a context-wide prompt section,
+  // so parent and child render the same one. A structured run's
+  // structured_output instruction is NOT prompt state either — the structured
+  // runtime's final-request listener appends it per request (see structured.ts).
   const agentOptions: AgentOptions = {
     ...request.parent.options.model !== undefined ? { model: request.parent.options.model } : {},
     ...request.agentOptions,
-    ...systemPrompt !== undefined ? { systemPrompt } : {},
     subagentDepth: childDepth,
   }
 

packages/subagent/subagent-inprocess/src/structured.ts

@@ -11,7 +11,10 @@
  * `prepend: true` listener that post-processes `await next()` — FINAL-REQUEST
  * enforcement: whatever downstream listeners mutated or replaced, the request
  * that hits the wire never carries `structured_output` for an agent without a
- * structured run, and always carries the run's OWN schema for one that has it.
+ * structured run, and for one that has it always carries the run's OWN schema
+ * plus the {@link STRUCTURED_OUTPUT_INSTRUCTION} appended to its `system`
+ * text (the demand travels with the tool — `AgentOptions` has no per-agent
+ * prompt field to carry it).
  * (Cooperative mutate-then-`next()` would not survive a downstream listener
  * returning a replacement request — see the waterfall composition caveat in
  * docs/architecture.md.)
@@ -42,7 +45,13 @@ import { ToolArgsError, validateStructuredValue, type StructuredOutputSchema } f
 /** The model-facing tool name a structured child must call to finish. */
 export const STRUCTURED_OUTPUT_TOOL = 'structured_output'
 
-/** The per-child instruction appended to a structured child's system prompt. */
+/**
+ * The instruction the request listener appends to a structured child's
+ * `system` on every request. Per-request wire state, NOT agent prompt state:
+ * `AgentOptions` has no prompt field (the persona is deployment config on the
+ * system-prompt plugin), so the same final-request enforcement that injects
+ * the schema'd tool carries the instruction that demands calling it.
+ */
 export const STRUCTURED_OUTPUT_INSTRUCTION
   = 'When you have your final answer, you MUST report it by calling the '
     + `\`${STRUCTURED_OUTPUT_TOOL}\` tool with arguments matching its parameter schema exactly. `
@@ -172,6 +181,12 @@ function registerRuntime(root: Context, runtime: StructuredRuntime): void {
         parameters: state.schema as unknown as Record<string, unknown>,
       }
       final.tools = [...(final.tools ?? []).filter(tool => tool.name !== STRUCTURED_OUTPUT_TOOL), schemaEntry]
+      // The demand travels WITH the tool: the instruction is appended to the
+      // final request's system text (the loop always assembles one; a bare
+      // direct dispatch may carry none).
+      final.system = final.system === undefined
+        ? STRUCTURED_OUTPUT_INSTRUCTION
+        : `${final.system}\n\n${STRUCTURED_OUTPUT_INSTRUCTION}`
       return final
     }
     // No structured run: strip the placeholder if present; leave an absent

packages/subagent/subagent-inprocess/tests/structured.spec.ts

@@ -187,23 +187,37 @@ describe('in-process structured output', () => {
     expect(ctx.agents.get(AgentId('parent'))).toBeDefined()
   })
 
-  it('appends the structured instruction to the child system prompt (caller prompt preserved)', async () => {
-    const { ctx, parent } = await setup([toolCallResponse('c1', STRUCTURED_OUTPUT_TOOL, { answer: 1 })])
-    const run = ctx.subagents.start('spawn', structuredRequest(parent, {
-      agentOptions: { systemPrompt: 'You are a counter.' },
-    }))
+  it('appends the structured instruction to the child REQUEST\'s system text (base prompt preserved)', async () => {
+    const { ctx, parent, adapter } = await setup([toolCallResponse('c1', STRUCTURED_OUTPUT_TOOL, { answer: 1 })])
+    // A context-wide section stands in for the deployment persona: the
+    // instruction must APPEND to whatever the prompt pipeline assembled, not
+    // replace it (AgentOptions has no prompt field — the instruction is
+    // per-request wire state added by the final-request listener).
+    ctx.systemPrompt.section({ name: 'test:persona', order: 10, text: 'You are a counter.' })
+    const run = ctx.subagents.start('spawn', structuredRequest(parent))
     await run.result
-    const child = ctx.agents.get(run.id)!
-    expect(child.options.systemPrompt).toBe(`You are a counter.\n\n${STRUCTURED_OUTPUT_INSTRUCTION}`)
+    const childRequest = adapter.requests.at(-1)!
+    expect(childRequest.system).toContain('You are a counter.')
+    expect(childRequest.system!.endsWith(STRUCTURED_OUTPUT_INSTRUCTION)).toBe(true)
+    expect(childRequest.system!.indexOf(STRUCTURED_OUTPUT_INSTRUCTION)).toBeGreaterThan(0)
     await run.dispose()
   })
 
-  it('a structured child WITHOUT a caller prompt gets exactly the instruction', async () => {
-    const { ctx, parent } = await setup([toolCallResponse('c1', STRUCTURED_OUTPUT_TOOL, { answer: 1 })])
+  it('the instruction rides ONLY structured requests: appended for the child, absent for a plain agent', async () => {
+    const { ctx, parent, adapter } = await setup([
+      textResponse('parent answer'),
+      toolCallResponse('c1', STRUCTURED_OUTPUT_TOOL, { answer: 1 }),
+    ])
+    parent.send([{ type: 'text', text: 'hello' }])
+    await parent.whenIdle()
+    expect(adapter.requests[0]!.system ?? '').not.toContain(STRUCTURED_OUTPUT_INSTRUCTION)
     const run = ctx.subagents.start('spawn', structuredRequest(parent))
     await run.result
-    const child = ctx.agents.get(run.id)!
-    expect(child.options.systemPrompt).toBe(STRUCTURED_OUTPUT_INSTRUCTION)
+    // The loop always assembles a base prompt (the harness identity section),
+    // so the instruction APPENDS — never replaces.
+    const childSystem = adapter.requests.at(-1)!.system!
+    expect(childSystem.endsWith(STRUCTURED_OUTPUT_INSTRUCTION)).toBe(true)
+    expect(childSystem.length).toBeGreaterThan(STRUCTURED_OUTPUT_INSTRUCTION.length)
     await run.dispose()
   })
 
@@ -314,6 +328,8 @@ describe('in-process structured output', () => {
       const bare2: GenerateOptions = { model: 'mock', messages: [] }
       const shaped = await ctx.waterfall('agent/request', parent, 1, 1, bare2, () => Promise.resolve(bare2))
       expect(shaped.tools!.map(tool => tool.name)).toEqual([STRUCTURED_OUTPUT_TOOL])
+      // A bare request carries no system text: the instruction IS the system.
+      expect(shaped.system).toBe(STRUCTURED_OUTPUT_INSTRUCTION)
       acquisition.detach(parent)
       acquisition.release()
     })

packages/subagent/subagent-spawn/src/index.ts

@@ -51,6 +51,8 @@ export const Config: z<Config> = z.object({
  */
 class SpawnProvider implements SubagentProvider {
   readonly capabilities: SubagentCapabilities = { outputSchema: true, depthLimit: true, toolFilter: false }
+  // Context contract: a spawned child starts fresh — it never sees the parent conversation.
+  readonly inheritsParentContext = false
 
   constructor(
     readonly name: string,

packages/subagent/subagent-spawn/tests/harness.ts

@@ -23,7 +23,10 @@ export async function spawnHarness(workdir: string): Promise<Context> {
   const ctx = new Context()
   await ctx.plugin(LlmService)
   await ctx.plugin(SessionStore)
-  await ctx.plugin(SystemPrompt)
+  // The deployment persona is context-wide (parent AND spawned children
+  // render it), so it stays neutral for both roles; the delegation nudge
+  // lives in the e2e's user prompt and the subagent tool's own description.
+  await ctx.plugin(SystemPrompt, { persona: 'You are a coding agent. Report only when the requested work is done.' })
   await ctx.plugin(ToolRegistry)
   await ctx.plugin(AgentRegistry)
   await ctx.plugin(AgentLoop, { agents: [] })

packages/subagent/subagent-spawn/tests/spawn.e2e.ts

@@ -29,11 +29,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('spawn backend with-key smoke', (
   it('a parent delegates to a child that writes a file on disk', async () => {
     workdir = await mkdtemp(join(tmpdir(), 'dsh-subagent-spawn-e2e-'))
     ctx = await spawnHarness(workdir)
-    const parent = ctx.agentLoop.create(AgentId('e2e-parent'), {
-      model: 'deepseek-v4-flash',
-      systemPrompt: 'You are an orchestrator. To do file work, delegate to a subagent with the `subagent` tool — '
-        + 'give it a complete, standalone instruction. Report only when done.',
-    })
+    const parent = ctx.agentLoop.create(AgentId('e2e-parent'), { model: 'deepseek-v4-flash' })
 
     parent.send([{ type: 'text', text:
       'Use the subagent tool to delegate this exact task: "Use the bash tool to write the text '

packages/subagent/subagent/README.md

@@ -28,11 +28,13 @@ Unlike the bash seam (one executor per context, second load throws), **multiple
 - **Start-time features** (`outputSchema`, `depthLimit`, `toolFilter`) are a static `provider.capabilities` descriptor, checked by the service BEFORE a run exists. A request that needs one the provider lacks is **rejected loud** (`UNSUPPORTED_CAPABILITY`), never accepted-then-ignored.
 - **Runtime features** (steering, resume) are **optional methods** on `SubagentRun` (`sendMessage?`, `resume?`). The method's presence IS the capability; TS narrowing is the discovery mechanism — a consumer cannot call an absent method without narrowing first, so there is no silent degradation path.
 
+Beside `capabilities` sits one DESCRIPTIVE fact, not validated by the service: `provider.inheritsParentContext` — whether a child sees the parent conversation (`fork`: true — seeded with the completed-turn prefix; `spawn`/`acp`: false). The model-facing consumer (`dsh-tool-subagent`) derives truthful tool wording from it.
+
 ## Run lifecycle
 
 `provider.start(request)` returns a `SubagentRun`: a handle with a `result` promise, `cancel()`, `dispose()`, and the optional runtime methods. `result` resolves with a `SubagentResult` (`output`, optional `structured`, `stopReason`) — it does **not** reject on a child-level failure (a model/transport failure resolves with `stopReason: 'error'`), so the consumer maps a non-`completed` reason to an `isError` tool result. The consumer MUST `dispose()` on every path (success, error, abort) to reach child quiescence and avoid leaking an idle child / session.
 
-The service emits `subagent/start` (payload `SubagentRunInfo`) and `subagent/end` (payload `SubagentRunEndInfo`) around the run — both **observe-only** (plain `emit`s; `subagent/end` fires from a detached `.then` and awaits no listener). `subagent/end` carries `lastAssistantMessage` (a deep clone of the child's final `output`) on the settle path, absent when the run rejected at the infrastructure level. The clone keeps the surface observe-only: the end emit fires from a detached `.then` before the caller's `await run.result` resumes, so a shared reference would let a mutating listener corrupt the caller's result. A `subagent/start` listener can still reach the live child via `ctx.agents.get(info.id)`; a `subagent/end` listener can only observe (the run has settled). Any run-affecting decision (continuation, injection that changes the run) is out of scope for this observe-only surface.
+The service also announces provider lifecycle: `subagent/provider-added` (the live provider) fires after a registration and `subagent/provider-removed` (the name) after an unregistration, so a consumer deriving state from a named provider (the model-facing tool wording) mirrors registry membership instead of assuming load order — the cordis Loader starts sibling plugins concurrently, so "listed earlier" does not mean "registered earlier". The service emits `subagent/start` (payload `SubagentRunInfo`) and `subagent/end` (payload `SubagentRunEndInfo`) around the run — both **observe-only** (plain `emit`s; `subagent/end` fires from a detached `.then` and awaits no listener). `subagent/end` carries `lastAssistantMessage` (a deep clone of the child's final `output`) on the settle path, absent when the run rejected at the infrastructure level. The clone keeps the surface observe-only: the end emit fires from a detached `.then` before the caller's `await run.result` resumes, so a shared reference would let a mutating listener corrupt the caller's result. A `subagent/start` listener can still reach the live child via `ctx.agents.get(info.id)`; a `subagent/end` listener can only observe (the run has settled). Any run-affecting decision (continuation, injection that changes the run) is out of scope for this observe-only surface.
 
 ## Scope (first cut)
 

packages/subagent/subagent/src/index.ts

@@ -60,6 +60,27 @@ declare module 'cordis' {
   }
 
   interface Events {
+    /**
+     * A provider became resolvable in the {@link SubagentService} registry.
+     * Consumers that derive state from a named provider (e.g. the model-facing
+     * tool wording in `dsh-tool-subagent`) react HERE instead of assuming load
+     * order — the cordis Loader starts sibling plugins concurrently, so
+     * "listed earlier in cordis.yml" does not mean "registered earlier".
+     * @param provider - the provider that just registered, live in the registry.
+     * @mode emit
+     */
+    'subagent/provider-added'(provider: SubagentProvider): void
+    /**
+     * A provider left the registry (its plugin's fiber was disposed — an
+     * unload or an HMR reload). Consumers holding provider-derived state drop
+     * it here; a reload re-fires `subagent/provider-added` with the fresh
+     * provider. Delivered with per-listener containment: a throwing
+     * subscriber is logged, never starves later subscribers, and never
+     * disrupts the provider's teardown.
+     * @param name - the registry name that no longer resolves.
+     * @mode emit
+     */
+    'subagent/provider-removed'(name: string): void
     /**
      * A subagent run started — emitted after the provider is resolved and its
      * capabilities validated, as the child run begins. Paired with
@@ -130,7 +151,9 @@ export class SubagentService extends Service {
   /**
    * Register a provider under its `provider.name`. Throws {@link SubagentError}
    * (`DUPLICATE_PROVIDER`) if the name is already taken. Effect-scoped: disposed
-   * with the calling fiber (HMR-safe).
+   * with the calling fiber (HMR-safe). Emits `subagent/provider-added` after
+   * the registration and `subagent/provider-removed` on unregistration, so
+   * consumers can mirror provider lifecycle instead of assuming load order.
    * @param provider - the provider; its `name` is the registry key.
    * @returns the disposer that unregisters the provider.
    */
@@ -140,9 +163,17 @@ export class SubagentService extends Service {
         throw new SubagentError(`a subagent provider named "${provider.name}" is already registered`, 'DUPLICATE_PROVIDER')
       }
       this.providers.set(provider.name, provider)
+      // Yield the rollback BEFORE emitting `subagent/provider-added`: a
+      // throwing added-listener then unregisters the provider (and announces
+      // the removal) instead of leaking it into the registry. The removal
+      // announcement itself is contained PER LISTENER ({@link emitLifecycle}):
+      // it runs inside this disposer, where a propagating subscriber would
+      // disrupt the backend fiber's teardown and starve later mirrors.
       yield () => {
         this.providers.delete(provider.name)
+        this.emitLifecycle('subagent/provider-removed', provider.name)
       }
+      this.ctx.emit('subagent/provider-added', provider)
     }.bind(this), 'subagents.registerProvider()')
     // ctx.effect's disposer returns Promise<void>; our disposer API is
     // synchronous fire-and-forget — discard the (always-resolved) promise.
@@ -239,10 +270,22 @@ export class SubagentService extends Service {
    * on the first throw — so this resolves the listener callbacks via
    * `ctx.events.dispatch` and contains each call, the same guarantee
    * `BashExecutor.notifyTaskDone` gives its own listener set.
+   *
+   * `subagent/provider-removed` routes through here too: it fires inside the
+   * provider registration's DISPOSER, where a propagating listener would
+   * disrupt the backend fiber's teardown (dispose must reach quiescence) and a
+   * starved later listener would leave a mirror consumer (`dsh-tool-subagent`)
+   * holding a tool for a provider that no longer exists. `subagent/provider-added`
+   * deliberately does NOT: it fires at registration time, where a throwing
+   * listener unwinds the yielded rollback — the same fail-loud register-time
+   * semantics as the system-prompt registries.
    */
+  private emitLifecycle(name: 'subagent/start', info: SubagentRunInfo): void
+  private emitLifecycle(name: 'subagent/end', info: SubagentRunEndInfo): void
+  private emitLifecycle(name: 'subagent/provider-removed', info: string): void
   private emitLifecycle(
-    name: 'subagent/start' | 'subagent/end',
-    info: SubagentRunInfo | SubagentRunEndInfo,
+    name: 'subagent/start' | 'subagent/end' | 'subagent/provider-removed',
+    info: SubagentRunInfo | SubagentRunEndInfo | string,
   ): void {
     for (const callback of this.ctx.events.dispatch('emit', [name, info])) {
       try {

packages/subagent/subagent/src/types.ts

@@ -167,6 +167,16 @@ export interface SubagentProvider {
   readonly name: string
   /** The start-time features this provider supports (see {@link SubagentCapabilities}). */
   readonly capabilities: SubagentCapabilities
+  /**
+   * The provider's context contract: `true` when a child SEES the parent
+   * conversation (fork — the child is seeded with the parent's completed-turn
+   * prefix), `false` when it starts fresh (spawn, ACP). A DESCRIPTIVE fact,
+   * not a start-time capability: the service validates nothing against it —
+   * the model-facing consumer (`dsh-tool-subagent`) derives truthful tool
+   * wording from it, so a tool bound to a fork provider stops telling the
+   * model the child "does not see this conversation".
+   */
+  readonly inheritsParentContext: boolean
   /**
    * Start a child run. The service has already validated that every requested
    * start-time capability is supported, so an implementation may assume e.g.

packages/subagent/subagent/tests/service.spec.ts

@@ -22,6 +22,7 @@ const NO_CAPS: SubagentCapabilities = { outputSchema: false, depthLimit: false,
 /** A scripted provider whose run settles immediately with a fixed result. */
 class StubProvider implements SubagentProvider {
   startCount = 0
+  readonly inheritsParentContext = false
   constructor(
     readonly name: string,
     readonly capabilities: SubagentCapabilities = ALL_CAPS,
@@ -44,6 +45,59 @@ function baseRequest(overrides: Partial<SubagentStartRequest> = {}): SubagentSta
 }
 
 describe('SubagentService', () => {
+  it('announces provider lifecycle: added on register, removed on dispose', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SubagentService)
+    const added: string[] = []
+    const removed: string[] = []
+    ctx.on('subagent/provider-added', provider => void added.push(provider.name))
+    ctx.on('subagent/provider-removed', name => void removed.push(name))
+
+    const dispose = ctx.subagents.registerProvider(new StubProvider('alpha'))
+    expect(added).toEqual(['alpha'])
+    expect(removed).toEqual([])
+
+    dispose()
+    expect(removed).toEqual(['alpha'])
+  })
+
+  it('rolls back the registration when a provider-added listener throws', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SubagentService)
+    let threw = false
+    const off = ctx.on('subagent/provider-added', () => {
+      if (!threw) { threw = true; throw new Error('boom added listener') }
+    })
+
+    expect(() => ctx.subagents.registerProvider(new StubProvider('alpha'))).toThrow('boom added listener')
+    expect(ctx.subagents.getProvider('alpha')).toBeUndefined() // nothing leaked
+
+    off()
+    ctx.subagents.registerProvider(new StubProvider('alpha'))
+    expect(ctx.subagents.getProvider('alpha')).toBeDefined()
+  })
+
+  it('contains a throwing provider-removed listener: later mirrors still hear it, teardown completes', async () => {
+    // provider-removed fires inside the registration's DISPOSER, so a
+    // propagating listener would disrupt the backend's teardown; and cordis
+    // emit halts on the first throw, so an uncontained one would starve every
+    // mirror registered after it (a stale model-facing tool). Both are
+    // prevented by per-listener containment.
+    const ctx = new Context()
+    await ctx.plugin(SubagentService)
+    const warnings: string[] = []
+    ctx.logger.warn = ((message: unknown) => void warnings.push(String(message))) as typeof ctx.logger.warn
+    ctx.on('subagent/provider-removed', () => { throw new Error('boom removed listener') })
+    const heard: string[] = []
+    ctx.on('subagent/provider-removed', name => void heard.push(name))
+
+    const dispose = ctx.subagents.registerProvider(new StubProvider('alpha'))
+    expect(() => { dispose() }).not.toThrow()
+    expect(heard).toEqual(['alpha']) // the listener AFTER the thrower still ran
+    expect(ctx.subagents.getProvider('alpha')).toBeUndefined() // teardown reached quiescence
+    expect(warnings.some(w => w.includes('boom removed listener'))).toBe(true)
+  })
+
   it('registers a provider and starts a run on it by name', async () => {
     const ctx = new Context()
     await ctx.plugin(SubagentService)
@@ -234,6 +288,7 @@ describe('SubagentService', () => {
     ctx.subagents.registerProvider({
       name: 'rej',
       capabilities: NO_CAPS,
+      inheritsParentContext: false,
       start: () => ({
         id: AgentId('rej-child'),
         result: Promise.reject(new Error('infra fault')),
@@ -267,6 +322,7 @@ describe('SubagentService', () => {
     ctx.subagents.registerProvider({
       name: 'unclone',
       capabilities: NO_CAPS,
+      inheritsParentContext: false,
       start: () => ({
         id: AgentId('unclone-child'),
         result: Promise.resolve({ output: uncloneable, stopReason: 'completed' } as SubagentResult),
@@ -296,6 +352,7 @@ describe('SubagentService', () => {
     ctx.subagents.registerProvider({
       name: 'rejecter',
       capabilities: NO_CAPS,
+      inheritsParentContext: false,
       start: () => ({
         id: AgentId('rej-child'),
         result: Promise.reject(new Error('infra fault')),

packages/subagent/tool-subagent/README.md

@@ -6,11 +6,15 @@ The model-facing `subagent` tool: delegate a self-contained task to a child agen
 
 This plugin binds to **exactly one** provider (`Config.provider`). The model sees only `{ description, prompt }` — there is no provider/type parameter in the schema. To expose more than one transport, load the plugin more than once, each bound to a different provider **and a distinct `toolName`** (the tool registry rejects a duplicate name, so a second load that kept the default `subagent` name would throw). Keeping selection in config (not the schema) is the deliberate split: the *service* holds a multi-provider registry; the *tool* picks one.
 
+## The description states the provider's context contract
+
+The tool description and the `prompt` parameter description are DERIVED from the bound provider's `inheritsParentContext` (`providerWording`): a fresh-context provider (spawn, ACP) gets the standalone-prompt wording ("it does not see this conversation"), an inheriting provider (fork) tells the model the child already sees the conversation's completed turns and its prompt should state only what is new. Because the description is fixed at tool registration, the tool **mirrors the provider's lifecycle** (`subagent/provider-added`/`-removed`): it registers when the bound provider is (or becomes) available and unregisters when the provider goes away — no load-order requirement (the cordis Loader starts sibling entries concurrently, so "listed first" never guaranteed "registered first"), and an HMR reload of the backend re-derives the wording from the fresh provider. While the provider is absent the tool simply does not exist (a `ctx.logger` note records the wait; a typo'd provider name shows up as a tool that never materializes).
+
 | Config key | Meaning |
 |---|---|
 | `provider` (required) | The `ctx.subagents` provider name to start runs on (`spawn`, `fork`, `acp`, …). |
 | `toolName` | The model-facing tool name to register (default `subagent`). Set a distinct value per load when exposing multiple providers, e.g. `subagent` + `subagent_acp`. |
-| `agentOptions` | Default per-child `{ model?, systemPrompt? }` applied to every spawned child. |
+| `agentOptions` | Default per-child `{ model? }` applied to every spawned child. (No per-child persona: the deployment persona is a context-wide section every agent shares.) |
 
 ## Lifecycle (synchronous collect)
 

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

@@ -11,6 +11,15 @@
  * — there is no provider/type parameter in the model-facing schema. The model
  * sees only `{ description, prompt }`.
  *
+ * The tool DESCRIPTION is derived from the bound provider's context contract
+ * ({@link providerWording}): a fresh-context provider (spawn, ACP) gets the
+ * standalone-prompt wording, an inheriting provider (fork) tells the model the
+ * child already sees the conversation's completed turns. The tool MIRRORS the
+ * provider's lifecycle via `subagent/provider-added`/`-removed` — it registers
+ * when the provider is (or becomes) available and unregisters when the
+ * provider goes away — so no load-order requirement exists and an HMR reload
+ * of the backend re-derives the wording from the fresh provider.
+ *
  * Collection is SYNCHRONOUS this cut: `execute` starts a run and awaits
  * `run.result` inside a `try/finally` that always disposes the run, so the
  * owned child agent/session is torn down on every path (success, error, abort)
@@ -26,7 +35,7 @@ import z from 'schemastery'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { AgentOptions } from '@deepseek-ai/dsh-agent'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
-import type { SubagentResult, SubagentRun, SubagentStartRequest } from '@deepseek-ai/dsh-subagent'
+import type { SubagentProvider, SubagentResult, SubagentRun, SubagentStartRequest } from '@deepseek-ai/dsh-subagent'
 
 export const name = 'tool-subagent'
 export const inject = ['tools', 'subagents']
@@ -44,8 +53,10 @@ export interface Config {
    */
   toolName?: string
   /**
-   * Default per-child agent options (model, system prompt) applied to every
-   * spawned child. Omitted fields fall back to the child loop's own defaults.
+   * Default per-child agent options (model) applied to every spawned child.
+   * Omitted fields fall back to the child loop's own defaults. There is no
+   * per-child persona: the deployment persona (the system-prompt plugin's
+   * `persona` config) is a context-wide section every agent shares.
    */
   agentOptions?: AgentOptions
 }
@@ -55,7 +66,6 @@ export const Config: z<Config> = z.object({
   toolName: z.string().default('subagent'),
   agentOptions: z.object({
     model: z.string(),
-    systemPrompt: z.string(),
   }),
 })
 
@@ -92,70 +102,140 @@ function stopReasonError(result: SubagentResult): string | undefined {
   }
 }
 
-export function apply(ctx: Context, config: Config): void {
-  ctx.tools.register(defineTool({
-    name: config.toolName ?? 'subagent',
+/**
+ * Model-facing wording per context contract ({@link SubagentProvider.inheritsParentContext}).
+ * A fresh child needs a standalone prompt; a forked child already sees the
+ * conversation's completed turns — telling the model to restate everything
+ * (or, worse, that the child "does not see this conversation") would be false
+ * for a fork. Exported for tests.
+ * @param inherits - the bound provider's context contract.
+ * @returns the tool `description` and the `prompt` parameter description.
+ */
+export function providerWording(inherits: boolean): { description: string; promptDescription: string } {
+  if (inherits) {
+    return {
+      description:
+        'Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all '
+        + 'completed turns so far (it does not see the current in-flight turn), returning only its final '
+        + 'result. Use this when the subtask builds on this conversation\'s context — a follow-up analysis, '
+        + 'a review, a continuation — without consuming this conversation\'s context for the work itself. '
+        + 'You receive only its final answer, not its intermediate steps.',
+      promptDescription:
+        'The task for the subagent. It already sees this conversation\'s completed turns, so build on them '
+        + 'freely and state only what is new.',
+    }
+  }
+  return {
     description:
       'Delegate a self-contained task to a subagent (a separate agent that works in its own context) '
       + 'and return its final result. Use this to offload focused, independent work — research, a scoped '
       + 'implementation, an analysis — so it does not consume this conversation\'s context. The subagent '
       + 'runs to completion and you receive only its final answer, not its intermediate steps. Give it a '
       + 'complete, standalone prompt: it does not see this conversation.',
-    parameters: {
-      description: {
-        type: 'string',
-        required: true,
-        description: 'A short (3-5 word) description of the delegated task, for display.',
-      },
-      prompt: {
-        type: 'string',
-        required: true,
-        description: 'The complete, self-contained task for the subagent. It does not share this '
-          + 'conversation\'s context, so include everything it needs.',
-      },
-    },
-    async execute(args, exec): Promise<ContentBlock[]> {
-      const parent = exec.agent
-      if (!parent) {
-        // The loop sets `exec.agent` for every model-driven call; its absence
-        // means a non-agent caller invoked the tool directly, which has no
-        // parent to attribute the child to. Fail loud rather than guess.
-        throw new Error('subagent tool requires a calling agent (exec.agent was undefined)')
-      }
-
-      const request: SubagentStartRequest = {
-        prompt: [{ type: 'text', text: args.prompt }],
-        parent,
-        ...exec.signal ? { signal: exec.signal } : {},
-        ...config.agentOptions ? { agentOptions: config.agentOptions } : {},
-      }
-
-      const run: SubagentRun = ctx.subagents.start(config.provider, request)
-
-      // Bridge the tool's abort signal to the run: if the parent step is
-      // aborted while the child is in flight, cancel the child too.
-      const onAbort = (): void => { run.cancel('parent step aborted') }
-      exec.signal?.addEventListener('abort', onAbort, { once: true })
-      // `addEventListener` does NOT fire for a signal already aborted before this
-      // line, so a step cancelled before the tool ran would never reach the
-      // child. Cancel explicitly in that case — the bridge must honor an
-      // already-aborted signal, not lean on each provider re-checking it.
-      if (exec.signal?.aborted) run.cancel('parent step aborted')
-
-      try {
-        const result = await run.result
-        const error = stopReasonError(result)
-        if (error !== undefined) {
-          // Map a non-clean finish to an isError result (the registry turns a
-          // throw into an isError). Report the reason, not partial output.
-          throw new Error(error)
-        }
-        return [{ type: 'text', text: outputText(result.output) }]
-      } finally {
-        exec.signal?.removeEventListener('abort', onAbort)
-        // Always reach child quiescence — never leak a live idle child/session.
-        await run.dispose()
-      }
-    },
-  }))
+    promptDescription:
+      'The complete, self-contained task for the subagent. It does not share this '
+      + 'conversation\'s context, so include everything it needs.',
+  }
+}
+
+export function apply(ctx: Context, config: Config): void {
+  // The tool MIRRORS its provider's lifecycle instead of assuming load order:
+  // the cordis Loader starts sibling entries concurrently, so "backend listed
+  // first in cordis.yml" does not guarantee "provider registered first", and
+  // an HMR reload of the backend replaces the provider while this fiber stays
+  // loaded. Register the tool when the bound provider is (or becomes)
+  // available — deriving the wording from THAT provider — and unregister it
+  // when the provider goes away, so the description can never outlive or
+  // predate the provider it describes.
+  let disposeTool: (() => void) | undefined
+  const mount = (provider: SubagentProvider): void => {
+    const wording = providerWording(provider.inheritsParentContext)
+    disposeTool = ctx.tools.register(defineTool({
+      name: config.toolName ?? 'subagent',
+      description: wording.description,
+      parameters: {
+        description: {
+          type: 'string',
+          required: true,
+          description: 'A short (3-5 word) description of the delegated task, for display.',
+        },
+        prompt: {
+          type: 'string',
+          required: true,
+          description: wording.promptDescription,
+        },
+      },
+      async execute(args, exec): Promise<ContentBlock[]> {
+        const parent = exec.agent
+        if (!parent) {
+          // The loop sets `exec.agent` for every model-driven call; its absence
+          // means a non-agent caller invoked the tool directly, which has no
+          // parent to attribute the child to. Fail loud rather than guess.
+          throw new Error('subagent tool requires a calling agent (exec.agent was undefined)')
+        }
+
+        const request: SubagentStartRequest = {
+          prompt: [{ type: 'text', text: args.prompt }],
+          parent,
+          ...exec.signal ? { signal: exec.signal } : {},
+          ...config.agentOptions ? { agentOptions: config.agentOptions } : {},
+        }
+
+        const run: SubagentRun = ctx.subagents.start(config.provider, request)
+
+        // Bridge the tool's abort signal to the run: if the parent step is
+        // aborted while the child is in flight, cancel the child too.
+        const onAbort = (): void => { run.cancel('parent step aborted') }
+        exec.signal?.addEventListener('abort', onAbort, { once: true })
+        // `addEventListener` does NOT fire for a signal already aborted before this
+        // line, so a step cancelled before the tool ran would never reach the
+        // child. Cancel explicitly in that case — the bridge must honor an
+        // already-aborted signal, not lean on each provider re-checking it.
+        if (exec.signal?.aborted) run.cancel('parent step aborted')
+
+        try {
+          const result = await run.result
+          const error = stopReasonError(result)
+          if (error !== undefined) {
+            // Map a non-clean finish to an isError result (the registry turns a
+            // throw into an isError). Report the reason, not partial output.
+            throw new Error(error)
+          }
+          return [{ type: 'text', text: outputText(result.output) }]
+        } finally {
+          exec.signal?.removeEventListener('abort', onAbort)
+          // Always reach child quiescence — never leak a live idle child/session.
+          await run.dispose()
+        }
+      },
+    }))
+  }
+
+  // Listeners first, then the presence check: both run synchronously, so no
+  // registration can slip between them; the `disposeTool === undefined` guard
+  // makes a same-tick added-event after a successful mount a no-op.
+  // TODO(subagent-dup-toolname): two WAITING fibers configured with the same
+  // toolName collide only when their provider finally arrives — the duplicate
+  // tool-name throw then propagates through `subagent/provider-added` and
+  // rolls back the PROVIDER registration, so an invalid config blasts the
+  // backend's fiber instead of the misconfigured tool's. Config-time detection
+  // would need a cross-fiber registry of intended tool names; revisit if a
+  // real deployment ever hits it.
+  ctx.on('subagent/provider-added', (provider) => {
+    if (provider.name === config.provider && disposeTool === undefined) mount(provider)
+  })
+  ctx.on('subagent/provider-removed', (name) => {
+    if (name !== config.provider || disposeTool === undefined) return
+    disposeTool()
+    disposeTool = undefined
+  })
+  const present = ctx.subagents.getProvider(config.provider)
+  if (present !== undefined) {
+    mount(present)
+  } else {
+    // Not an error: the backend's fiber may simply activate after this one.
+    // The tool appears the moment the provider registers; a typo'd provider
+    // name shows up as this note plus a tool that never materializes.
+    ctx.logger.info(`subagent provider "${config.provider}" not registered yet; the "${config.toolName ?? 'subagent'}" tool will register when it appears`)
+  }
 }

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

@@ -112,6 +112,7 @@ describe('dsh-tool-subagent', () => {
     ctx.subagents.registerProvider({
       name: 'weird',
       capabilities: { outputSchema: false, depthLimit: false, toolFilter: false },
+      inheritsParentContext: false,
       start: () => ({
         id: AgentId('weird-child'),
         result: Promise.resolve({ output: [{ type: 'text', text: 'partial' }], stopReason: 'frobnicated' as never }),
@@ -137,6 +138,7 @@ describe('dsh-tool-subagent', () => {
     ctx.subagents.registerProvider({
       name: 'capture',
       capabilities: { outputSchema: false, depthLimit: false, toolFilter: false },
+      inheritsParentContext: false,
       start: (request) => {
         seen = request
         return {
@@ -147,10 +149,10 @@ describe('dsh-tool-subagent', () => {
         }
       },
     })
-    await ctx.plugin(tool, { provider: 'capture', agentOptions: { model: 'child-model', systemPrompt: 'be terse' } })
+    await ctx.plugin(tool, { provider: 'capture', agentOptions: { model: 'child-model' } })
 
     await callSubagent(ctx, { description: 'd', prompt: 'p' })
-    expect(seen?.agentOptions).toEqual({ model: 'child-model', systemPrompt: 'be terse' })
+    expect(seen?.agentOptions).toEqual({ model: 'child-model' })
   })
 
   it('defaults toolName and omits agentOptions when apply() is called directly (schema bypass)', async () => {
@@ -166,6 +168,7 @@ describe('dsh-tool-subagent', () => {
     ctx.subagents.registerProvider({
       name: 'bare',
       capabilities: { outputSchema: false, depthLimit: false, toolFilter: false },
+      inheritsParentContext: false,
       start: (request) => {
         seen = request
         return {
@@ -192,14 +195,96 @@ describe('dsh-tool-subagent', () => {
     expect(text(result)).toContain('requires a calling agent')
   })
 
-  it('surfaces an UNSUPPORTED_CAPABILITY rejection as an isError result is NOT applicable here '
-    + '(the tool requests no capabilities) — a missing provider IS surfaced', async () => {
-    // Bind the tool to a provider name that is not registered: the service throws
-    // NO_PROVIDER, the registry turns it into an isError result.
-    const ctx = await setup({ provider: 'does-not-exist' })
+  it('registers when the provider appears LATER — no load-order requirement (Loader starts siblings concurrently)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(SubagentService)
+    // Tool first: no provider yet — the tool must be absent, not broken.
+    // Direct apply (schema bypass): also covers the waiting-note's default
+    // toolName fallback, which validated config pre-fills.
+    tool.apply(ctx, { provider: 'mock' })
+    expect(ctx.tools.schemas().some(s => s.name === 'subagent')).toBe(false)
+    // Backend arrives (as a delayed sibling fiber would): the tool appears.
+    await ctx.plugin(mock, { name: 'mock', reply: 'late but fine' })
+    expect(ctx.tools.schemas().some(s => s.name === 'subagent')).toBe(true)
     const result = await callSubagent(ctx, { description: 'd', prompt: 'p' })
-    expect(result.isError).toBe(true)
-    expect(text(result)).toContain('no subagent provider')
+    expect(text(result)).toBe('late but fine')
+  })
+
+  it('mirrors the provider lifecycle: gone on backend dispose, re-derived wording on re-registration', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(SubagentService)
+    const backend = await ctx.plugin(mock, { name: 'mock' }) // spawn-shaped (inherits: false)
+    await ctx.plugin(tool, { provider: 'mock' })
+    expect(ctx.tools.schemas().find(s => s.name === 'subagent')!.description).toContain('does not see this conversation')
+
+    // Backend unloads (HMR shape): the tool must not outlive its provider.
+    await backend.dispose()
+    expect(ctx.tools.schemas().some(s => s.name === 'subagent')).toBe(false)
+
+    // Backend reloads with a DIFFERENT contract: the wording is re-derived
+    // from the fresh provider, not served stale from the first mount.
+    await ctx.plugin(mock, { name: 'mock', inheritsParentContext: true })
+    expect(ctx.tools.schemas().find(s => s.name === 'subagent')!.description).toContain('INHERITS this conversation')
+  })
+
+  it('the tool PLUGIN fiber owns its lifecycle listeners: disposal unmounts, and a disposed fiber never zombie-mounts', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(SubagentService)
+
+    // Arm 1: a mounted tool dies with its plugin fiber; the provider survives.
+    await ctx.plugin(mock, { name: 'mock' })
+    const mounted = await ctx.plugin(tool, { provider: 'mock' })
+    expect(ctx.tools.schemas().some(s => s.name === 'subagent')).toBe(true)
+    await mounted.dispose()
+    expect(ctx.tools.schemas().some(s => s.name === 'subagent')).toBe(false)
+    expect(ctx.subagents.getProvider('mock')).toBeDefined()
+
+    // Arm 2: a fiber disposed while WAITING must not react to the provider
+    // arriving later — a surviving listener would re-register a tool that no
+    // live plugin owns (the zombie mount).
+    const waiting = await ctx.plugin(tool, { provider: 'later', toolName: 'subagent_later' })
+    await waiting.dispose()
+    await ctx.plugin(mock, { name: 'later' })
+    expect(ctx.tools.schemas().some(s => s.name === 'subagent_later')).toBe(false)
+  })
+
+  it('ignores lifecycle events for OTHER providers', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(SubagentService)
+    await ctx.plugin(mock, { name: 'mock' })
+    await ctx.plugin(tool, { provider: 'mock' })
+    // An unrelated provider registering (added-event with another name) and
+    // unregistering (removed-event with another name) must not touch the tool.
+    const other = await ctx.plugin(mock, { name: 'other', inheritsParentContext: true })
+    expect(ctx.tools.schemas().filter(s => s.name === 'subagent')).toHaveLength(1)
+    expect(ctx.tools.schemas().find(s => s.name === 'subagent')!.description).toContain('does not see this conversation')
+    await other.dispose()
+    expect(ctx.tools.schemas().some(s => s.name === 'subagent')).toBe(true)
+  })
+
+  it('derives spawn-shaped wording from a fresh-context provider (default mock)', async () => {
+    const ctx = await setup({ provider: 'mock' })
+    const schema = ctx.tools.schemas().find(s => s.name === 'subagent')!
+    expect(schema.description).toContain('does not see this conversation')
+    const props = (schema.parameters as { properties: Record<string, { description: string }> }).properties
+    expect(props['prompt']!.description).toContain('include everything it needs')
+  })
+
+  it('derives fork-shaped wording from an inheriting provider (the description stops lying)', async () => {
+    const ctx = await setup({ provider: 'mock', toolName: 'subagent' }, { inheritsParentContext: true })
+    const schema = ctx.tools.schemas().find(s => s.name === 'subagent')!
+    expect(schema.description).toContain('INHERITS this conversation')
+    expect(schema.description).not.toContain('does not see this conversation')
+    const props = (schema.parameters as { properties: Record<string, { description: string }> }).properties
+    expect(props['prompt']!.description).toContain('completed turns')
   })
 
   it('disposes the run on the success path (no leaked child)', async () => {
@@ -213,6 +298,7 @@ describe('dsh-tool-subagent', () => {
     ctx.subagents.registerProvider({
       name: 'spy',
       capabilities: { outputSchema: false, depthLimit: false, toolFilter: false },
+      inheritsParentContext: false,
       start: () => ({
         id: AgentId('spy-child'),
         result: Promise.resolve({ output: [{ type: 'text', text: 'ok' }], stopReason: 'completed' as const }),
@@ -235,6 +321,7 @@ describe('dsh-tool-subagent', () => {
     ctx.subagents.registerProvider({
       name: 'spy',
       capabilities: { outputSchema: false, depthLimit: false, toolFilter: false },
+      inheritsParentContext: false,
       start: () => ({
         id: AgentId('spy-child'),
         result: Promise.resolve({ output: [], stopReason: 'error' as const }),
@@ -258,6 +345,7 @@ describe('dsh-tool-subagent', () => {
     ctx.subagents.registerProvider({
       name: 'spy',
       capabilities: { outputSchema: false, depthLimit: false, toolFilter: false },
+      inheritsParentContext: false,
       start: () => {
         let resolveResult: (r: { output: never[]; stopReason: 'aborted' }) => void
         const result = new Promise<{ output: never[]; stopReason: 'aborted' }>((res) => { resolveResult = res })
@@ -304,6 +392,7 @@ describe('dsh-tool-subagent', () => {
     ctx.subagents.registerProvider({
       name: 'spy',
       capabilities: { outputSchema: false, depthLimit: false, toolFilter: false },
+      inheritsParentContext: false,
       start: () => {
         let resolveResult: (r: { output: never[]; stopReason: 'aborted' }) => void
         const result = new Promise<{ output: never[]; stopReason: 'aborted' }>((res) => { resolveResult = res })

packages/support/subagent-mock/README.md

@@ -14,6 +14,7 @@ Load it as a plugin (functional shape: `name`/`inject`/`Config`/`apply`, no defa
 | `reply` | `mock subagent reply` | The scripted child's final answer text. |
 | `stopReason` | `completed` | The stop reason `result` settles with. |
 | `capabilities` | all `true` | Which start-time capabilities (`outputSchema`/`depthLimit`/`toolFilter`) the provider advertises. |
+| `inheritsParentContext` | `false` | The context contract to declare; `true` exercises the fork-shaped tool wording in consumer tests. |
 | `structured` | `{ reply }` | Structured value surfaced when a request carries an `outputSchema` and the capability is on. |
 
 A `cancel()` issued before `result` settles flips the stop reason to `aborted`, so the cancellation path is observable.

packages/support/subagent-mock/src/index.ts

@@ -37,12 +37,14 @@ const DEFAULT_CAPS: SubagentCapabilities = { outputSchema: true, depthLimit: tru
  */
 class MockSubagentProvider implements SubagentProvider {
   readonly capabilities: SubagentCapabilities
+  readonly inheritsParentContext: boolean
 
   constructor(
     readonly name: string,
     private readonly config: Config,
   ) {
     this.capabilities = { ...DEFAULT_CAPS, ...config.capabilities }
+    this.inheritsParentContext = config.inheritsParentContext ?? false
   }
 
   start(request: SubagentStartRequest): SubagentRun {
@@ -88,6 +90,12 @@ export interface Config {
   stopReason?: SubagentStopReason
   /** Which start-time capabilities to advertise (default: all `true`). */
   capabilities?: Partial<SubagentCapabilities>
+  /**
+   * The context contract to declare ({@link SubagentProvider.inheritsParentContext});
+   * default `false` (spawn-like). Set `true` to exercise the fork-shaped tool
+   * wording in consumer tests.
+   */
+  inheritsParentContext?: boolean
   /**
    * Structured value surfaced when a request carries an `outputSchema` and the
    * `outputSchema` capability is on (default: `{ reply }`).
@@ -104,6 +112,7 @@ export const Config: z<Config> = z.object({
     depthLimit: z.boolean(),
     toolFilter: z.boolean(),
   }),
+  inheritsParentContext: z.boolean(),
   structured: z.any(),
 })
 

packages/ui/acp-agent/README.md

@@ -23,7 +23,7 @@ Because the package wires no logger entry, an ACP leaf has **nothing to get wron
 | Key | Default | Routed to |
 |---|---|---|
 | `model` | (required) | the per-session agent template the bridge creates agents from |
-| `systemPrompt` | (required) | the per-session agent's system prompt |
+| `persona` | — | the deployment persona template (may reference `{{model}}`/`{{cwd}}`), routed to `dsh-system-prompt` |
 | `persistenceRoot` | `./.sessions` | the JSONL backend's root directory |
 
 The leaf supplies the swappable backends: an LLM adapter (`llm-deepseek` for the real model, `llm-replay` for keyless snapshot replay) and a bash executor (`bash-local`).

packages/ui/acp-agent/src/index.ts

@@ -39,35 +39,38 @@ import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 export const name = 'acp-agent'
 
 /**
- * App config: the swappable per-deployment values. `model`/`systemPrompt`
- * configure the agent template the ACP bridge creates each session's agent from
- * (NOT a pre-created agent — ACP creates agents at `session/new`);
+ * App config: the swappable per-deployment values. `model` configures the
+ * agent template the ACP bridge creates each session's agent from (NOT a
+ * pre-created agent — ACP creates agents at `session/new`); `persona` is the
+ * deployment persona (forwarded to the system-prompt plugin);
  * `persistenceRoot` is the JSONL backend's directory.
  */
 export interface Config {
   /** Model name for ACP-created agents (must have a registered adapter). */
   model: string
-  /** Per-agent system prompt for ACP-created agents. */
-  systemPrompt: string
+  /** Deployment persona (the system-prompt plugin's `persona` config). */
+  persona?: string
   /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
   persistenceRoot?: string
 }
 
 export const Config: z<Config> = z.object({
   model: z.string().required(),
-  systemPrompt: z.string().required(),
+  persona: z.string(),
   persistenceRoot: z.string().default('./.sessions'),
 })
 
 /**
  * Compose the spine with the ACP front door. The agent-core bundle pre-creates
- * NO agents (its `agents` list defaults to `[]`); the JSONL backend persists
- * under `persistenceRoot`; the ACP bridge owns stdout for JSON-RPC and creates
- * one agent per `session/new` from `model`/`systemPrompt`. No logger, no `hmr` —
- * stdout stays pure.
+ * NO agents (its `agents` list defaults to `[]`) and carries the deployment
+ * `persona`; the JSONL backend persists under `persistenceRoot`; the ACP
+ * bridge owns stdout for JSON-RPC and creates one agent per `session/new`
+ * from `model`. No logger, no `hmr` — stdout stays pure.
  */
 export function apply(ctx: Context, config: Config): void {
-  ctx.plugin(agentCore)
+  ctx.plugin(agentCore, {
+    ...config.persona !== undefined ? { persona: config.persona } : {},
+  })
   ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' })
-  ctx.plugin(acp, { model: config.model, systemPrompt: config.systemPrompt })
+  ctx.plugin(acp, { model: config.model })
 }

packages/ui/acp-agent/tests/acp-agent.spec.ts

@@ -24,7 +24,7 @@ async function mount(config: acpAgent.Config): Promise<Context> {
 
 describe('dsh-acp-agent composition', () => {
   it('brings up the spine + persistence + the ACP bridge', async () => {
-    const ctx = await mount({ model: 'mock', systemPrompt: 'hi', persistenceRoot: '/tmp/dsh-acp-agent-test' })
+    const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-acp-agent-test' })
     expect(ctx.get('agents')).toBeDefined()
     expect(ctx.get('sessions')).toBeDefined()
     expect(ctx.get('sessionPersistence')).toBeDefined()
@@ -40,7 +40,8 @@ describe('dsh-acp-agent composition', () => {
     // `ctx.plugin`, which validates+defaults the config first) with no
     // persistenceRoot, so the runtime fallback is the one that fires.
     const ctx = new Context()
-    acpAgent.apply(ctx, { model: 'mock', systemPrompt: 'hi' })
+    // No persona: covers the omitted-persona forwarding branch too.
+    acpAgent.apply(ctx, { model: 'mock' })
     await new Promise(resolve => setTimeout(resolve, 50))
     expect(ctx.get('sessionPersistence')).toBeDefined()
     await ctx.fiber.dispose()

packages/ui/acp/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-acp
 
-The **Agent Client Protocol (ACP)** bridge: exposes the DeepSeek Harness coding agent as an ACP server over JSON-RPC stdio, so editors (Zed and other ACP clients) can drive it — streaming render, tool-call display, and resumable sessions. Zed is the current target client: baseline ACP behavior should remain reasonable for other clients, but bridge capabilities and compatibility decisions are evaluated against Zed first. **N concurrent sessions per connection** (see [ACP multi-session](../../../docs/rfc/proposed/feature/2026-06-14-acp-multi-session.md)): each maps to its own `ReactLoopAgent`, and every event is demuxed strictly by session id so two sessions streaming at once never interleave.
+The **Agent Client Protocol (ACP)** bridge: exposes DeepSeek Harness SDK agents as an ACP server over JSON-RPC stdio, so editors (Zed and other ACP clients) can drive them — streaming render, tool-call display, and resumable sessions. Zed is the current target client: baseline ACP behavior should remain reasonable for other clients, but bridge capabilities and compatibility decisions are evaluated against Zed first. **N concurrent sessions per connection** (see [ACP multi-session](../../../docs/rfc/proposed/feature/2026-06-14-acp-multi-session.md)): each maps to its own `ReactLoopAgent`, and every event is demuxed strictly by session id so two sessions streaming at once never interleave.
 
 It is a **client-driver / UI plugin**, the structured analogue of the readline `stdio-chat` plugin — NOT a loop change and NOT a [capability seam](../../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md). It consumes the existing `agent/*` event taxonomy, the `dsh-agent` create/resume factory, and `dsh-session-persistence`.
 
@@ -15,7 +15,8 @@ It is a **client-driver / UI plugin**, the structured analogue of the readline `
 | Key | Default | Meaning |
 |---|---|---|
 | `model` | — | Model name for created agents (must have a registered adapter). |
-| `systemPrompt` | — | Per-agent system prompt. |
+
+(No persona key: the deployment persona is `dsh-system-prompt`'s own `persona` config — a context-wide section, so ACP-created agents render it without the bridge carrying prompt text.)
 
 The `initialize` handshake reports a fixed server identity (`agentInfo: { name: 'deepseek-harness-acp', version: '0.0.1' }`) — branding is a literal at the `initialize` site, not config.
 

packages/ui/acp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-acp",
-  "description": "Agent Client Protocol (ACP) bridge: drive the DeepSeek Harness coding agent from an ACP editor over JSON-RPC stdio",
+  "description": "Agent Client Protocol (ACP) bridge: drive DeepSeek Harness SDK agents from an ACP editor over JSON-RPC stdio",
   "version": "0.0.1",
   "private": true,
   "type": "module",

packages/ui/acp/snapshot-replay.md

@@ -0,0 +1,27 @@
+<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
+     Run `pnpm run gen-doc-graphs` to regenerate. -->
+
+# ACP Snapshot Replay
+
+This graph explains what a snapshot scenario proves: recorded real-model session logs are replayed keylessly, ACP stdout is normalized and diffed, and scenario workspaces preserve tool side effects that the UI stream alone cannot prove.
+
+```mermaid
+sequenceDiagram
+  participant Recorder as Real API recording
+  participant Fixture as snapshot fixture
+  participant Workspace
+  participant Replay as llm-replay adapter
+  participant ACP as acp-agent subprocess
+  participant Golden as stdout golden
+  Recorder->>Fixture: session.jsonl + workspace inputs
+  Fixture->>Workspace: seed files and hook configs
+  Fixture->>Replay: recorded StreamChunk script
+  Replay->>ACP: deterministic <code>llm/stream</code> chunks
+  ACP->>Workspace: bash, fs, and hook side effects
+  ACP->>Golden: normalized sessionUpdate stream
+  Golden-->>ACP: diff must be empty
+```
+
+The fs and hook snapshot matrix is valuable because it proves world state, hook decisions, and failed tool-card rendering, not just that replay returns text.
+
+Maintenance mode: curated Mermaid sequence based on the snapshot test harness.

packages/ui/acp/src/index.ts

@@ -115,8 +115,6 @@ function sameWorkspaceCwd(left: string, right: string): boolean {
 export interface AcpConfig {
   /** Model name for created agents (must have a registered adapter). */
   model?: string
-  /** Per-agent system prompt. */
-  systemPrompt?: string
   /**
    * Transport stream override. Production omits this (the plugin wires
    * `process.stdin`/`process.stdout` via `ndJsonStream`). Tests inject an
@@ -129,7 +127,6 @@ export interface AcpConfig {
 
 export const Config: Schema<AcpConfig> = Schema.object({
   model: Schema.string(),
-  systemPrompt: Schema.string(),
 })
 
 /**
@@ -705,10 +702,9 @@ export function apply(ctx: Context, config: AcpConfig): void {
  * (exactOptionalPropertyTypes: never assign `undefined` to an optional key).
  * Exported for unit coverage of both the present and absent branches.
  */
-export function agentOptions(config: AcpConfig): { model?: string; systemPrompt?: string } {
+export function agentOptions(config: AcpConfig): { model?: string } {
   return {
     ...config.model !== undefined ? { model: config.model } : {},
-    ...config.systemPrompt !== undefined ? { systemPrompt: config.systemPrompt } : {},
   }
 }
 

packages/ui/acp/tests/bridge.spec.ts

@@ -148,15 +148,15 @@ describe('acp bridge', () => {
     await expect(harness.client.authenticate({ methodId: 'whatever' })).resolves.toBeDefined()
   })
 
-  it('honors systemPrompt config', async () => {
+  it('renders the deployment persona into ACP-created agents\' requests', async () => {
     harness = await makeBridgeHarness({
       storageDir,
       script: [textResponse('ok')],
-      config: { systemPrompt: 'be terse' },
+      persona: 'be terse',
     })
     await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
-    // Create + prompt so the systemPrompt config flows through agentOptions and
-    // reaches the model request.
+    // Create + prompt so the system-prompt plugin's persona section reaches
+    // the model request of an agent the BRIDGE created (session/new).
     const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
     await harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'hi' }] })
     expect(harness.adapter.requests[0]?.system).toContain('be terse')

packages/ui/acp/tests/harness.ts

@@ -153,6 +153,8 @@ export interface BridgeHarness {
 export async function makeBridgeHarness(options: {
   script?: (StreamChunk[] | 'hang')[]
   config?: Partial<AcpConfig>
+  /** Deployment persona for the tree (the system-prompt plugin's config). */
+  persona?: string
   storageDir: string
   /**
    * Plug the REAL `dsh-bash-local` executor + `dsh-tool-bash` tools (instead of
@@ -183,7 +185,7 @@ export async function makeBridgeHarness(options: {
   const ctx = new Context()
   await ctx.plugin(LlmService)
   await ctx.plugin(SessionStore)
-  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(SystemPrompt, { persona: options.persona ?? '' })
   await ctx.plugin(ToolRegistry)
   await ctx.plugin(AgentRegistry)
   await ctx.plugin(AgentLoop, { agents: [] })

packages/ui/acp/tests/stream-update.spec.ts

@@ -818,7 +818,5 @@ describe('agentOptions', () => {
   it('includes only the fields present in config', () => {
     expect(agentOptions({})).toEqual({})
     expect(agentOptions({ model: 'm' })).toEqual({ model: 'm' })
-    expect(agentOptions({ systemPrompt: 'sp' })).toEqual({ systemPrompt: 'sp' })
-    expect(agentOptions({ model: 'm', systemPrompt: 'sp' })).toEqual({ model: 'm', systemPrompt: 'sp' })
   })
 })

packages/ui/stdio-agent/README.md

@@ -11,7 +11,7 @@ A terminal chat always wants the same cluster, so the package owns it rather tha
 | Plugin | Why it is here |
 |---|---|
 | `@cordisjs/plugin-logger-console` | the console logger — stdout is just the terminal here, so logging to it is correct (the ACP app must NOT have this) |
-| `@deepseek-ai/dsh-agent-core` | the spine, pre-creating a `main` agent from this app's `model`/`systemPrompt` |
+| `@deepseek-ai/dsh-agent-core` | the spine, pre-creating a `main` agent from this app's `model` and carrying its `persona` |
 | `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log under `persistenceRoot` |
 | `stdio-chat` (in-package module) | the readline UI, bound to the `main` agent |
 
@@ -24,7 +24,7 @@ The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapte
 | Key | Default | Routed to |
 |---|---|---|
 | `model` | (required) | the pre-created `main` agent's model |
-| `systemPrompt` | (required) | the `main` agent's system prompt |
+| `persona` | — | the deployment persona template (may reference `{{model}}`), routed to `dsh-system-prompt` |
 | `persistenceRoot` | `./.sessions` | the JSONL backend's root directory |
 | `welcome` | `ready.` | the stdin-chat banner |
 | `resumeSessionId` | — | resume a persisted session id instead of starting fresh (sourced from an env var in the leaf) |
@@ -54,7 +54,7 @@ The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapte
   name: '@deepseek-ai/dsh-stdio-agent'
   config:
     model: deepseek-v4-flash
-    systemPrompt: 'You are a CLI coding assistant. Your only tools are bash…'
+    persona: 'You are a coding assistant powered by the {{model}} model.'
 ```
 
 Swap `llm-deepseek` for a `mock-llm` leaf plugin and you have the echo demo — "swap the backend, keep the app".

packages/ui/stdio-agent/src/index.ts

@@ -51,15 +51,16 @@ export const name = 'stdio-agent'
 
 /**
  * App config: the swappable per-demo values, each routed to where the app wires
- * it. `model`/`systemPrompt`/`resumeSessionId` configure the pre-created `main`
- * agent (through {@link @deepseek-ai/dsh-agent-core}'s forwarded `agents` list);
+ * it. `model`/`resumeSessionId` configure the pre-created `main` agent (through
+ * {@link @deepseek-ai/dsh-agent-core}'s forwarded `agents` list); `persona` is
+ * the deployment persona (forwarded to the system-prompt plugin);
  * `persistenceRoot` is the JSONL backend's directory; `welcome` is the UI banner.
  */
 export interface Config {
   /** Model name for the `main` agent (must have a registered adapter). */
   model: string
-  /** System prompt for the `main` agent. */
-  systemPrompt: string
+  /** Deployment persona (the system-prompt plugin's `persona` config). */
+  persona?: string
   /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
   persistenceRoot?: string
   /** stdin-chat banner printed once on start. Defaults to `'ready.'`. */
@@ -74,7 +75,7 @@ export interface Config {
 
 export const Config: z<Config> = z.object({
   model: z.string().required(),
-  systemPrompt: z.string().required(),
+  persona: z.string(),
   persistenceRoot: z.string().default('./.sessions'),
   welcome: z.string().default('ready.'),
   resumeSessionId: z.string(),
@@ -83,17 +84,17 @@ export const Config: z<Config> = z.object({
 /**
  * Compose the spine with the stdio front door. The console logger comes first
  * (infra), then the agent-core bundle pre-creating the `main` agent from this
- * app's `model`/`systemPrompt`/`resumeSessionId`, then the JSONL backend, then
- * the readline UI bound to `main`. The `hmr` dev-reload plugin is a leaf
- * concern (see the module doc), so it is not mounted here.
+ * app's `model`/`resumeSessionId` with the deployment `persona`, then the JSONL
+ * backend, then the readline UI bound to `main`. The `hmr` dev-reload plugin is
+ * a leaf concern (see the module doc), so it is not mounted here.
  */
 export function apply(ctx: Context, config: Config): void {
   ctx.plugin(ConsoleExporter)
   ctx.plugin(agentCore, {
+    ...config.persona !== undefined ? { persona: config.persona } : {},
     agents: [{
       id: AgentId('main'),
       model: config.model,
-      systemPrompt: config.systemPrompt,
       ...config.resumeSessionId !== undefined ? { resumeSessionId: SessionId(config.resumeSessionId) } : {},
     }],
   })

packages/ui/stdio-agent/tests/stdio-agent.spec.ts

@@ -8,8 +8,9 @@ import * as stdioAgent from '../src/index.ts'
  * Unit coverage for the @deepseek-ai/dsh-stdio-agent app plugin: mounting it
  * composes the console logger, the agent-core spine (pre-creating the `main`
  * agent from the app config), the JSONL backend, and the readline UI in one
- * `ctx.plugin`. The forwarded `model`/`systemPrompt` reach the pre-created
- * agent; `persistenceRoot`/`welcome`/`resumeSessionId` route to their backends.
+ * `ctx.plugin`. The forwarded `model` reaches the pre-created agent and
+ * `persona` the system-prompt plugin; `persistenceRoot`/`welcome`/
+ * `resumeSessionId` route to their backends.
  *
  * `hmr` is NOT part of this plugin (it is a leaf entry — a Loader-only dev
  * plugin the in-process tier cannot import); the keyless echo smoke in
@@ -30,7 +31,7 @@ async function mount(config: stdioAgent.Config): Promise<Context> {
 
 describe('dsh-stdio-agent app', () => {
   it('composes the spine + front-door cluster and pre-creates the main agent', async () => {
-    const ctx = await mount({ model: 'mock', systemPrompt: 'hi', persistenceRoot: '/tmp/dsh-stdio-agent-spec' })
+    const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-stdio-agent-spec' })
     // The spine services (brought up by the agent-core bundle) are all present.
     expect(ctx.get('agents')).toBeDefined()
     expect(ctx.get('agentLoop')).toBeDefined()
@@ -46,7 +47,8 @@ describe('dsh-stdio-agent app', () => {
     // apply()'s last two lines are the ones that fire — covering a
     // schema-bypassing direct-mount caller.
     const ctx = new Context()
-    stdioAgent.apply(ctx, { model: 'mock', systemPrompt: 'hi' })
+    // No persona: covers the omitted-persona forwarding branch too.
+    stdioAgent.apply(ctx, { model: 'mock' })
     await new Promise(resolve => setTimeout(resolve, 80))
     expect(ctx.get('sessionPersistence')).toBeDefined()
     expect(ctx.get('agents')?.get(AgentId('main'))).toBeDefined()
@@ -59,7 +61,7 @@ describe('dsh-stdio-agent app', () => {
     // the branch that maps resumeSessionId through is what this covers.
     const ctx = await mount({
       model: 'mock',
-      systemPrompt: 'hi',
+      persona: 'hi',
       persistenceRoot: '/tmp/dsh-stdio-agent-spec-resume',
       resumeSessionId: 'no-such-session',
     })

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

@@ -200,7 +200,7 @@ describe('tool-web registration', () => {
   it('contributes prompt sections for the enabled tools', async () => {
     const { fiber, ctx } = await mountTools()
     const prompt = await ctx.systemPrompt.assemble()
-    const text = prompt.sections.map(s => (typeof s.text === 'function' ? s.text() : s.text)).join('\n')
+    const text = prompt.sections.map(s => s.text).join('\n')
     expect(text).toContain('web_search')
     expect(text).toContain('web_fetch')
     await fiber.dispose()

packages/web/web-search-deepseek/tests/deepseek.e2e.ts

@@ -28,7 +28,7 @@ maybe('DeepSeekSearchProvider real API', () => {
       maxTokens: DEEPSEEK_DEFAULT_MAX_TOKENS,
       maxUses: DEEPSEEK_DEFAULT_MAX_USES,
     })
-    const result = await provider.search({ query: 'What is the DeepSeek coding agent?', maxResults: 5 })
+    const result = await provider.search({ query: 'What is the DeepSeek Harness SDK?', maxResults: 5 })
     expect(result.providerId).toBe('deepseek')
     expect(result.sources.length).toBeGreaterThan(0)
     for (const source of result.sources) expect(source.url).toMatch(/^https?:\/\//)

packages/web/web-search-exa/tests/exa.e2e.ts

@@ -16,7 +16,7 @@ maybe('ExaSearchProvider real API', () => {
       searchType: EXA_DEFAULT_SEARCH_TYPE,
       highlightsPerResult: EXA_DEFAULT_HIGHLIGHTS_PER_RESULT,
     })
-    const result = await provider.search({ query: 'DeepSeek coding agent', maxResults: 5 })
+    const result = await provider.search({ query: 'DeepSeek Harness SDK', maxResults: 5 })
     expect(result.providerId).toBe('exa')
     expect(result.sources.length).toBeGreaterThan(0)
     for (const source of result.sources) expect(source.url).toMatch(/^https?:\/\//)

packages/web/web-search-perplexity/tests/perplexity.e2e.ts

@@ -16,7 +16,7 @@ maybe('PerplexitySearchProvider real API', () => {
       model: process.env.PERPLEXITY_MODEL ?? PERPLEXITY_DEFAULT_MODEL,
       maxTokens: PERPLEXITY_DEFAULT_MAX_TOKENS,
     })
-    const result = await provider.search({ query: 'What is the DeepSeek coding agent?', maxResults: 5 })
+    const result = await provider.search({ query: 'What is the DeepSeek Harness SDK?', maxResults: 5 })
     expect(result.providerId).toBe('perplexity')
     expect(result.content ?? '').not.toBe('')
     for (const source of result.sources) expect(source.url).toMatch(/^https?:\/\//)

packages/workflow/tool-workflow/README.md

@@ -4,7 +4,7 @@ The model-facing **`workflow` tool**: run a JavaScript orchestration script that
 
 ## What the model sees
 
-Two parameters: `script` (required — the full `export const meta = {...}` + body text; the tool DESCRIPTION carries the complete authoring contract: hooks, semantics, determinism bans, the supported schema subset) and `args` (optional JSON object exposed to the script as the `args` global; a bare list is wrapped as a field, a deliberate deviation from Claude Code's any-JSON `args` so the wire schema stays honest).
+Two parameters: `script` (required — the full `export const meta = {...}` + body text; the tool DESCRIPTION carries the complete authoring contract: hooks, semantics, determinism bans, the supported schema subset) and `args` (optional JSON object exposed to the script as the `args` global; a bare list is wrapped as a field, a deliberate deviation from Claude Code's any-JSON `args` so the wire schema stays honest). The plugin also contributes a `tool:<toolName>` system-prompt section carrying the usage policy — use the tool only on an explicit user ask for a workflow / large orchestration; prefer plain subagent calls for one or two delegations — per the convention that tool guidance ships with the tool plugin, never in the deployment persona.
 
 ## Lifecycle
 

packages/workflow/tool-workflow/package.json

@@ -24,6 +24,7 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-agent": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
     "@deepseek-ai/dsh-workflow": "^0.0.1",
     "cordis": "^4.0.0-rc.6"

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

@@ -17,6 +17,10 @@
  * the args — presentation must be a pure function of `args`, so it cannot ask
  * the engine to parse.
  *
+ * Usage policy ships with the tool as a `tool:<toolName>` system-prompt
+ * section (explicit-ask-only guidance) — tool guidance lives in tool plugins,
+ * never in the deployment persona.
+ *
  * @module @deepseek-ai/dsh-tool-workflow
  */
 
@@ -26,9 +30,11 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { WorkflowResult, WorkflowRun } from '@deepseek-ai/dsh-workflow'
+// Declaration merge only: makes ctx.systemPrompt visible for the section registration.
+import type {} from '@deepseek-ai/dsh-system-prompt'
 
 export const name = 'tool-workflow'
-export const inject = ['tools', 'workflows']
+export const inject = ['tools', 'workflows', 'systemPrompt']
 
 /** Config: the model-facing tool name plus result rendering caps. */
 export interface Config {
@@ -115,8 +121,16 @@ function renderResult(run: WorkflowRun, result: WorkflowResult, maxChars: number
 
 export function apply(ctx: Context, config: Config): void {
   const maxResultChars = config.maxResultChars ?? 50_000
+  const toolName = config.toolName ?? 'workflow'
+  // Usage policy ships with the tool (the master convention: tool guidance
+  // lives in tool plugins as prompt sections, not in the deployment persona).
+  ctx.systemPrompt.section({
+    name: `tool:${toolName}`,
+    order: 115,
+    text: `Use the ${toolName} tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.`,
+  })
   ctx.tools.register(defineTool({
-    name: config.toolName ?? 'workflow',
+    name: toolName,
     description: DESCRIPTION,
     parameters: {
       script: {

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

@@ -217,7 +217,7 @@ describe('dsh-tool-workflow', () => {
   it('has the namespace-plugin export shape (no stray default)', () => {
     expect('default' in toolWorkflow).toBe(false)
     expect(toolWorkflow.name).toBe('tool-workflow')
-    expect(toolWorkflow.inject).toEqual(['tools', 'workflows'])
+    expect(toolWorkflow.inject).toEqual(['tools', 'workflows', 'systemPrompt'])
     const loader = Object.create(Loader.prototype) as Loader
     const unwrapped = loader.unwrapExports(toolWorkflow) as Record<string, unknown>
     expect(unwrapped).toBe(toolWorkflow)

packages/workflow/tool-workflow/tsconfig.json

@@ -26,6 +26,9 @@
     {
       "path": "../../core/tools"
     },
+    {
+      "path": "../../core/system-prompt"
+    },
     {
       "path": "../workflow"
     }

packages/workflow/workflow-vm/tests/workflow-vm.spec.ts

@@ -31,6 +31,8 @@ interface ControlledRun {
  */
 class StubProvider implements SubagentProvider {
   readonly capabilities: SubagentCapabilities = { outputSchema: true, depthLimit: true, toolFilter: true }
+  // Context contract: stub children start fresh, mirroring the spawn backend.
+  readonly inheritsParentContext = false
   readonly runs: ControlledRun[] = []
 
   constructor(
@@ -460,6 +462,7 @@ describe('dsh-workflow-vm', () => {
       const provider: SubagentProvider = {
         name: 'rejecting',
         capabilities: { outputSchema: true, depthLimit: true, toolFilter: true },
+        inheritsParentContext: false,
         start: () => ({
           id: AgentId('reject-child'),
           result: Promise.reject(new Error('backend exploded')),