docs: align scoped runtime contracts

packages/core/agent-loop/README.md

@@ -40,7 +40,7 @@ interface Config {
 }
 ```
 
-Agents listed in config are auto-created at startup. `cwd` applies only to fresh config-created sessions; `resumeSessionId` keeps the persisted session header. Config agents have no per-agent persona field: they use `dsh-system-prompt`'s deployment default, while programmatic factory callers can register an agent-scoped `deployment:persona` shadow in `setup`. 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` and default `deployment:persona` sections, which live on `dsh-system-prompt` so they survive a swapped loop plugin.
+Agents listed in config are auto-created at startup. `cwd` applies only to fresh config-created sessions; `resumeSessionId` keeps the persisted session header. Config agents have no per-agent persona field: they use `dsh-system-prompt`'s deployment default, while programmatic factory callers can register an agent-scoped `deployment:persona` shadow in `setup`. The plugin registers the built-in `model`/`cwd` prompt variables on `ctx.systemPrompt`, resolved per step from `assembleContextFor(agent)` — the helper couples the typed agent with its matching scope selector. These are runtime facts of the agents THIS loop drives, unlike the `harness:identity` and default `deployment:persona` sections, which live on `dsh-system-prompt` so they survive a swapped loop plugin.
 
 ### Exported concrete class
 
@@ -63,7 +63,8 @@ forever:
     if every prompt blocked: 'turn/end'(rejected), no step  ⟵ zero-step turn
     STEP loop:
       drain steering
-      assembly = systemPrompt.assemble({agent})  ⟵ renderPrompt(assembly) IS the full prompt
+      assembly = await systemPrompt.assemble(assembleContextFor(agent))
+                                                ⟵ renderPrompt(assembly) IS the full prompt
       prefix ??= waterfall agent/session-prefix   ⟵ once per instance (first step): frozen
                                                 session prefix; on the header, never history
       await serial agent/pre-step(…, prefix)  ⟵ surface mutation (compaction) outside the step;

packages/core/agent/src/types.ts

@@ -82,9 +82,9 @@ declare module '@deepseek-ai/dsh-system-prompt' {
 }
 
 /**
- * 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.
+ * Options an agent is created with. The persona is NOT here: the
+ * dsh-system-prompt config supplies the global default, and a scoped
+ * `deployment:persona` section may override it for one agent.
  * Merge-extensible: plugins declare extra fields via declaration merging.
  */
 export interface AgentOptions {

packages/core/session/src/index.ts

@@ -363,8 +363,7 @@ export class Session {
    * @returns the logged event — its assigned `seq`/`time` plus the SNAPSHOT of
    *   `data` that entered the log, so reading `event.data` back sees the logged
    *   value, never the caller's still-mutable input.
-   * @throws if `type` is not a string, or if `data` or surface metadata is not
-   *   losslessly JSON-serializable
+   * @throws if `data` or surface metadata is not losslessly JSON-serializable
    *   (BigInt, function, symbol, undefined, negative zero, non-finite number,
    *   circular reference, sparse array, or an exotic object such as
    *   Map/Set/Date/class instance). One recursive pass reads, validates, and

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

@@ -23,9 +23,10 @@ export async function spawnHarness(workdir: string): Promise<Context> {
   const ctx = new Context()
   await ctx.plugin(LlmService)
   await ctx.plugin(SessionStore)
-  // 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.
+  // This harness installs only the global default persona, so both parent and
+  // spawned children render it. 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)

packages/subagent/subagent/src/types.ts

@@ -57,7 +57,7 @@ export interface SubagentStartRequest {
    * afterward.
    */
   readonly signal: AbortSignal
-  /** Per-child agent options (model, system prompt). */
+  /** Per-child agent options (model and plugin-defined extension fields). */
   readonly agentOptions?: AgentOptions
   /**
    * Optional structured-output schema — an object-rooted JSON Schema within the

packages/subagent/tool-subagent/README.md

@@ -10,7 +10,7 @@ The description is derived from `provider.inheritsParentContext`: spawn and ACP
 
 ## Lifecycle
 
-`execute` passes the tool execution's abort signal directly as the required `SubagentStartRequest.signal`, awaits `ctx.subagents.start(...)`, then awaits `run.result` inside a `try/finally` that always calls `run.dispose()`. The same signal therefore covers startup and live execution, while disposal guarantees quiescence on success, failure, and abort.
+`execute` passes the tool execution's abort signal when present, otherwise supplies an inert signal to satisfy the required `SubagentStartRequest.signal`. It awaits `ctx.subagents.start(...)`, then awaits `run.result` inside a `try/finally` that always calls `run.dispose()`. The selected signal therefore covers startup and live execution, while disposal guarantees quiescence on success, failure, and abort.
 
 A non-`completed` stop reason becomes an `isError` tool result; partial child output is never reported as success. The current tool blocks the parent turn until collection finishes; background and polling modes are deferred.
 

packages/ui/acp/README.md

@@ -16,7 +16,7 @@ It is a **client-driver / UI plugin**, the structured analogue of the readline `
 |---|---|---|
 | `model` | — | Model name for created agents (must have a registered adapter). |
 
-(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.)
+(No persona key: `dsh-system-prompt`'s own `persona` config supplies the global default section, so ACP-created agents render it without the bridge carrying prompt text. An agent-scoped same-name section may still shadow that default.)
 
 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.