fix(scope): align trust and input boundaries

Rewrite the agent-scope RFC with executable examples and an explicit security non-goal. Harden subagent scalar and depth validation, and pin live tool-filter semantics across code, tests, and generated docs.

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -189,7 +189,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
   },
   {
     key: 'systemPrompt',
-    summary: 'Registry service (`ctx.systemPrompt`): plugins contribute ordered text sections, tool-schema providers, named prompt variables, and authoritative contribution protections; the agent loop calls `assemble(context)` once per step.',
+    summary: 'Registry service (`ctx.systemPrompt`): plugins contribute ordered text sections, tool-schema providers, named prompt variables, and owner-final contribution protections; the agent loop calls `assemble(context)` once per step.',
     methods: [
       'section(section: PromptSection): () => Promise<void> | void',
       'tools(provider: (context: AssembleContext) => ToolProviderResult): () => Promise<void> | void',

packages/core/scope/README.md

@@ -16,6 +16,6 @@ Scoped-context registration primitive. `createScope(ctx, key)` mints a Cordis co
 
 ## Design contract
 
-Ownership and visibility derive from ONE fact — which context a registration went through. An explicit `{ scope }` registration parameter could express "visible to X, disposed with Y", which is almost always a bug; the scoped context makes it unrepresentable. Rationale and alternatives: [the agent-scope RFC](../../../docs/rfc/implemented/architecture/2026-07-08-agent-scope-contexts.md).
+Ownership and visibility derive from ONE fact — which context a registration went through. An explicit `{ scope }` registration parameter could express "visible to X, disposed with Y", which is almost always a bug; the scoped context makes it unrepresentable. This is trusted registration and listener routing, not sandboxing or an authority hierarchy: a same-process plugin is not confined, and a child scope need not be a subset of its parent's view. Rationale, alternatives, and the security non-goal: [the agent-scope RFC](../../../docs/rfc/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals).
 
-Handing out a scoped context hands out the minting plugin's service-resolution capability (resolution walks the minting fiber's dependency chain, not the holder's) — mint scopes from a plugin whose `inject` surface is what scope holders should reach.
+Handing out a scoped context hands out the minting plugin's service-resolution surface (resolution walks the minting fiber's dependency chain, not the holder's) — mint it from the plugin whose dependencies the scoped registrations need to resolve.

packages/core/scope/src/index.ts

@@ -27,8 +27,8 @@ import { Context as CordisContext } from 'cordis'
 
 // Capture the invocation primordials once. A carrier holder can reach the
 // composed Context.filter function, so neither that function's mutable
-// property surface nor a base filter's own `.call` may choose how isolation
-// predicates are invoked.
+// property surface nor a base filter's own `.call` may choose how listener-
+// selection predicates are invoked.
 const reflectApply = Reflect.apply
 // eslint-disable-next-line @typescript-eslint/unbound-method
 const functionCall = Function.prototype.call
@@ -131,7 +131,7 @@ function scope(): void {}
  * Service resolution through the scoped context flows through the minting
  * plugin's dependency chain (the fiber walk), regardless of what the eventual
  * holder's own fiber injected — handing out the scoped context hands out that
- * capability; see `Agent.ctx` in `@deepseek-ai/dsh-agent` for the harness's
+ * dependency surface; see `Agent.ctx` in `@deepseek-ai/dsh-agent` for the harness's
  * contract.
  * @param ctx - the context to mount the scope under; its fiber must be active
  *   (a disposing owner throws Cordis's INACTIVE_EFFECT), and its plugin's
@@ -201,7 +201,7 @@ function isConstructable(value: (...args: unknown[]) => unknown): boolean {
  *   compatibility default: plain plugin listeners see every subject), or
  * - its tag IS `key` (a scoped listener seeing exactly its own subject),
  *
- * AND `base`'s own filter (a Cordis `Service`'s isolation check) also admits
+ * AND `base`'s own filter (a Cordis `Service`'s listener-filter check) also admits
  * it. Both the captured base filter and the composed filter are invoked
  * through captured JavaScript primordials, so mutating either function's
  * public `.call` property cannot bypass either predicate. Dispatching with
@@ -263,7 +263,7 @@ export function scopeTarget<T extends object>(base: T, key: ScopeKey | undefined
   // construction, a base-target proxy would therefore silently replace the
   // composed scope predicate with the caller's filter. The surrogate owns the
   // two immutable overlay slots, so later descriptor changes on `base` cannot
-  // affect isolation. It shares the base prototype and delegates ordinary
+  // affect listener selection. It shares the base prototype and delegates ordinary
   // reads/writes/keys to preserve the supported transparent shape. Callable
   // targets use native bound built-ins so V8 contributes no user-code surface;
   // the chosen built-in matches whether `base` has [[Construct]], and the traps

packages/core/system-prompt/README.md

@@ -1,6 +1,6 @@
 # dsh-system-prompt
 
-System prompt assembly registry. Plugins contribute ordered text sections, tool-schema providers, named prompt variables, and authoritative named protections; 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.
+System prompt assembly registry. Plugins contribute ordered text sections, tool-schema providers, named prompt variables, and owner-final named protections; 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
 
@@ -16,7 +16,7 @@ System prompt assembly registry. Plugins contribute ordered text sections, tool-
 - `ctx.systemPrompt.section(section: PromptSection): () => Promise<void> | void` Contribute a section. The registry reads `name`, `order`, and the text value/callback once, validates their fixed string/finite-number/string-or-function types, and stores only that accepted record; later caller-object mutation cannot rename or reshape it. The layer is the CALLING context's scope: `agent.ctx` contributes to that agent alone, SHADOWING a same-named global section there (the per-agent persona mechanism — a scoped `deployment:persona`). Duplicate names within one layer throw, and a globally protected section name cannot be shadowed. Disposed with the calling fiber.
 - `ctx.systemPrompt.tools(provider: (context: AssembleContext) => ToolProviderResult): () => Promise<void> | void` Contribute tool schemas, evaluated at each assembly with that assembly's context; a non-function provider rejects before effect storage. `ToolProviderResult` = `{ schemas, knownNames? }`: `schemas` is the post-restriction visible set for `context.scope`; `knownNames` (defaulting to the same captured schemas' names) is the pre-restriction universe `toolOrder` validates against. Assembly reads the result, each schema field, and the optional known-name list once before detaching them, rejects non-string schema names/descriptions or known names, and uses those same accepted strings for validation and the model-visible collection. A provider must not return a schema named `TOOL_ORDER_REST`. Scoped providers are consulted only for their scope's assemblies. Disposed with the calling fiber.
 - `ctx.systemPrompt.variable(name: string, provider: (context) => string | undefined): () => Promise<void> | void` Contribute a prompt variable, referenced from section text as `{{name}}`. The fixed string name and function provider types reject before effect storage. Scoped variables (via `agent.ctx`) shadow a same-named global for that agent. Duplicate-in-layer or unreferenceable names throw; `undefined` means "no value for this assembly". Disposed with the calling fiber.
-- `ctx.systemPrompt.protect(protection: PromptProtection): () => Promise<void> | void` Make named section/tool contributions authoritative after the assembly waterfall. Protection restores canonical registry/provider presence and definition; restored entries keep canonical order with one another and anchor before their first surviving later unprotected canonical neighbor (or at the end), without undoing listener reordering of unprotected entries. Canonical absence is authoritative too, so a mode-hidden tool cannot be fabricated by a listener. Calling through `agent.ctx` protects only that agent's assemblies. A global section protection additionally reserves its name against scoped shadows; registering either side of that conflict fails loudly instead of treating the shadow as canonical. Each optional field and array slot is read once, non-array fields or non-string names reject before effect storage, and the accepted arrays are deduplicated and frozen. Finalization materializes each waterfall-produced entry name once, so a stateful getter cannot evade canonical replacement. Empty protections throw, and disposal removes the protection.
+- `ctx.systemPrompt.protect(protection: PromptProtection): () => Promise<void> | void` Make named section/tool contributions owner-final after the assembly waterfall. Protection restores canonical registry/provider presence and definition; restored entries keep canonical order with one another and anchor before their first surviving later unprotected canonical neighbor (or at the end), without undoing listener reordering of unprotected entries. Canonical absence is owner-final too, so a mode-hidden tool cannot be fabricated by a listener. Calling through `agent.ctx` protects only that agent's assemblies. A global section protection additionally reserves its name against scoped shadows; registering either side of that conflict fails loudly instead of treating the shadow as canonical. Each optional field and array slot is read once, non-array fields or non-string names reject before effect storage, and the accepted arrays are deduplicated and frozen. Finalization materializes each waterfall-produced entry name once, so a stateful getter cannot evade canonical replacement. Empty protections throw, and disposal removes the protection.
 - `ctx.systemPrompt.assemble(context?: AssembleContext): Promise<PromptAssembly>` Assemble the prompt for one caller: the global layer merged with `context.scope`'s layer (scoped shadows global). Provider output becomes one coherent detached snapshot before `toolOrder` validation. Runs through the scope-filtered `system-prompt/assemble` waterfall, then restores protected contributions from the pre-waterfall canonical assembly. Rejects when a configured `toolOrder` names a tool outside the providers' `knownNames` universe (a restricted-away KNOWN tool is a normal absence), or when a provider returns the reserved rest-entry name.
 
 ### Live events

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

@@ -1,6 +1,6 @@
 /**
  * System prompt assembly registry. Plugins contribute ordered text sections,
- * tool schema providers, named prompt variables, and authoritative named
+ * tool schema providers, named prompt variables, and owner-final named
  * protections; `assemble(context)` collates them through a waterfall that
  * runs once per step, restores protected contributions, and `renderPrompt`
  * interpolates `{{variable}}` references into the final text.
@@ -138,9 +138,9 @@ export interface ToolProviderResult {
  * off the wire in Code Mode).
  */
 export interface PromptProtection {
-  /** Section names whose canonical registry output is authoritative. */
+  /** Section names whose canonical presence and definition are restored after the waterfall. */
   sections?: readonly string[]
-  /** Tool names whose canonical provider output is authoritative. */
+  /** Tool names whose canonical presence and definition are restored after the waterfall. */
   tools?: readonly string[]
 }
 
@@ -422,7 +422,7 @@ function interpolate(section: AssembledSection, variables: Record<string, string
 
 /**
  * Registry service (`ctx.systemPrompt`): plugins contribute ordered text
- * sections, tool-schema providers, named prompt variables, and authoritative
+ * sections, tool-schema providers, named prompt variables, and owner-final
  * contribution protections; the agent loop calls `assemble(context)` once per
  * step. Registers the harness-owned `harness:identity` and
  * `deployment:persona` sections itself (see {@link Config.persona}).
@@ -682,7 +682,7 @@ export class SystemPrompt extends Service {
    * registration/unregistration. A global section protection also reserves the
    * name against scoped section shadows; registering protection when such a
    * shadow already exists fails loudly instead of protecting the wrong owner.
-   * @param protection - section and/or tool names whose canonical presence and definitions are authoritative.
+   * @param protection - section and/or tool names whose canonical presence and definitions are restored after the waterfall.
    * @returns the exact Cordis effect disposer that removes the protection.
    */
   protect(protection: PromptProtection): () => Promise<void> | void {
@@ -736,7 +736,7 @@ export class SystemPrompt extends Service {
     return dispose
   }
 
-  /** Resolve the authoritative names registered for one assembly scope. */
+  /** Resolve the owner-final names registered for one assembly scope. */
   private protectedNames(scope: ScopeKey | undefined): { sections: Set<string>; tools: Set<string> } {
     const records = [
       ...this.protections,

packages/core/tools/README.md

@@ -16,7 +16,7 @@ tools:
 ### Public API
 
 - `ctx.tools.register(definition: ToolDefinition): () => Promise<void> | void` Register a tool as a frozen snapshot. Every top-level caller field is read once into one coherent acceptance record; `name`/`description` must be strings and `timeoutMs`, when present, must be positive and finite before the snapshot can own them. Parameters are validated and detached by one recursive lossless-JSON traversal, so a stateful getter cannot show one value to a check and another to a prototype-erasing clone. Execute/presentation callbacks are bound once to the original definition as their method receiver, so later caller mutation cannot change the executable definition. The layer is the CALLING context's scope (`dsh-scope`): a plain plugin context registers globally; an agent's `agent.ctx` registers for that agent alone, SHADOWING a same-named global tool there (per-agent tool variants). Duplicate names within one layer throw; non-native modes also reject the reserved `run_code` transport name. Disposed with the calling fiber (= the agent, for scoped registrations).
-- `ctx.tools.restrict(filter: ToolRestriction): () => Promise<void> | void` Scoped-only (throws on a plain context): mask the GLOBAL end-capability surface for the calling agent — `allow` keeps only the listed tools, `deny` removes them; multiple restrictions intersect; scoped registrations bypass restriction as explicit grants. The registry reads `allow`/`deny` once, so the values checked for an empty filter and unknown names are exactly the values enforced. The reserved `run_code` transport remains available automatically and cannot be named explicitly. Snapshot-at-registration, loud unknown-name validation, `restrict({})` rejects (the materialized-empty-config trap).
+- `ctx.tools.restrict(filter: ToolRestriction): () => Promise<void> | void` Scoped-only (throws on a plain context): mask the GLOBAL end-capability surface for the calling agent — `allow` keeps only the listed tools, `deny` removes them; multiple restrictions intersect; scope-local registrations are merged after the global filter. The registry reads `allow`/`deny` once, so the values checked for an empty filter and unknown names are exactly the values enforced. A deny-list admits a later global tool unless it names that tool; an allow-list excludes later names; neither filters a later scope-local registration. The reserved `run_code` transport remains available automatically and cannot be named explicitly. Filter-value snapshot at registration, loud unknown-name validation, `restrict({})` rejects (the materialized-empty-config trap). This is live registration composition, not a parent-derived authority ceiling; see the [agent-scope security non-goal](../../../docs/rfc/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals).
 - `ctx.tools.get(name: string, scope?: ScopeKey): ToolDefinition | undefined` Resolution as one scope sees it (shadowing applied; a restricted-away global reads as absent) — presenters pass the calling agent so the card matches what executed. Returned definitions are the registry's frozen snapshots.
 - `ctx.tools.visible(scope?: ScopeKey): ToolDefinition[]` The canonical executable view — restricted global layer ∪ the scope's own layer, plus the reserved transport in non-native modes — feeding prompt assembly, `get`, and `execute`, so presentation and dispatch resolve the same frozen definitions.
 - `ctx.tools.knownNames(scope?: ScopeKey): string[]` The PRE-restriction end-capability name universe `restrict` validates against: a typo fails loud while a restricted-away tool stays a normal absence. Presentation providers add reserved transport names separately when validating `toolOrder`.

packages/core/tools/src/index.ts

@@ -115,8 +115,8 @@ declare module 'cordis' {
      * set or replace the one mutable field, `exec.signal` (e.g. with a per-call
      * deadline), BEFORE `next()`, restore/delete it afterward, and inspect the result AFTER. Call identity
      * (`token`, `callId`, `name`, `arguments`, `agent`, and `parent`) is immutable throughout the
-     * pipeline so a wrapper cannot change which capability or scope was
-     * authorized. (Cordis `next()` ignores passed arguments and re-invokes
+     * pipeline so a wrapper cannot change which tool and scope the pipeline
+     * accepted. (Cordis `next()` ignores passed arguments and re-invokes
      * downstream with the shared payload, so a wrapper changes `exec.signal` in
      * place rather than passing a new object to `next()`.)
      * Multiple listeners compose by registration order — an outer one wraps the
@@ -429,8 +429,11 @@ export interface Config {
  * {@link ToolRegistry.restrict}. `allow` keeps only the listed global tools;
  * `deny` removes the listed ones; both present = allow first, then deny.
  * Restrictions never touch scoped registrations — a tool registered through
- * the same scope is an explicit grant that bypasses them (which is what keeps
- * e.g. a structured-output capture tool alive under an allow-list). The
+ * the same scope is merged after the global filter (which is what keeps e.g. a
+ * structured-output capture tool alive under an allow-list). The filter values
+ * are snapshotted at registration, but resolution uses the live global registry:
+ * a later global name passes a deny-only filter unless explicitly denied and
+ * fails an allow-list unless explicitly allowed. The
  * reserved `run_code` presentation transport is likewise outside capability
  * filtering, and naming it explicitly is rejected. Multiple restrictions on
  * one scope compose by intersection: every one must admit.
@@ -705,11 +708,14 @@ export class ToolRegistry extends Service {
    * this). A non-native mode's reserved `run_code` presentation transport is
    * not a filterable capability; naming it explicitly throws, while omitting
    * it from an allow-list cannot remove it. `allow` and `deny` are each read
-   * once, then the filter is SNAPSHOT at registration: the values checked are
-   * the values enforced, and later caller mutation of the arrays changes nothing.
-   * Multiple restrictions compose by intersection. Scoped registrations
-   * bypass restrictions (explicit grants win). Disposed with the calling
-   * fiber (revocable independently); emits `tools/change`.
+   * once, then the filter VALUES are snapshotted at registration: the values
+   * checked are the values enforced, and later caller mutation of the arrays
+   * changes nothing. Resolution still uses the live global registry, so a later
+   * global name passes a deny-only filter unless named and fails an allow-list
+   * unless named. Multiple restrictions compose by intersection. Scoped
+   * registrations are merged after restrictions and therefore remain visible.
+   * Disposed with the calling fiber (revocable independently); emits
+   * `tools/change`.
    * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).
    * @returns the disposer that lifts this restriction. The exact
    *   Cordis effect disposer (single-shot): composite (generator) effects may
@@ -863,7 +869,7 @@ export class ToolRegistry extends Service {
       if (this.admits(scope, name)) result.set(name, definition)
     }
     // Scoped layer second: same-name entries REPLACE (shadow) the global ones,
-    // and grants bypass restrictions by construction (never filtered above).
+    // and scope-local registrations are never part of the global filter above.
     for (const [name, definition] of layer ?? []) result.set(name, definition)
     // Presentation infrastructure is resolved last and outside capability
     // filtering. Registration rejects this reserved name, so this set is an

packages/core/tools/tests/scoped.spec.ts

@@ -101,7 +101,7 @@ describe('scoped tool registration', () => {
 })
 
 describe('restrict()', () => {
-  it('masks global tools for the scope; grants bypass; assembly and execute agree', async () => {
+  it('masks global tools, merges scope-local tools afterward, and keeps assembly with execution', async () => {
     const ctx = await mount()
     const { scope, key } = await mintAgentScope(ctx, 'a')
     ctx.tools.register(tool('read'))
@@ -109,7 +109,7 @@ describe('restrict()', () => {
     scope.ctx.tools.register(tool('capture'))
     scope.ctx.tools.restrict({ allow: ['read'] })
 
-    // The scoped grant survives the allow-list; the unlisted global is gone.
+    // The scope-local registration survives the allow-list; the unlisted global is gone.
     expect(ctx.tools.schemas(key).map(t => t.name).sort()).toEqual(['capture', 'read'])
     expect(await run(ctx, 'bash', key)).toBe('Error: unknown tool "bash"')
     expect(await run(ctx, 'read', key)).toBe('ran:read')
@@ -118,6 +118,29 @@ describe('restrict()', () => {
     expect(ctx.tools.schemas().map(t => t.name).sort()).toEqual(['bash', 'read'])
   })
 
+  it('applies snapshotted filters to the live global registry before merging later scope-local tools', async () => {
+    const ctx = await mount()
+    const denied = await mintAgentScope(ctx, 'denied')
+    const allowed = await mintAgentScope(ctx, 'allowed')
+    ctx.tools.register(tool('read'))
+    ctx.tools.register(tool('bash'))
+    denied.scope.ctx.tools.restrict({ deny: ['bash'] })
+    allowed.scope.ctx.tools.restrict({ allow: ['read'] })
+
+    ctx.tools.register(tool('web'))
+    denied.scope.ctx.tools.register(tool('denied-local'))
+    allowed.scope.ctx.tools.register(tool('allowed-local'))
+
+    expect(ctx.tools.schemas(denied.key).map(t => t.name).sort())
+      .toEqual(['denied-local', 'read', 'web'])
+    expect(ctx.tools.schemas(allowed.key).map(t => t.name).sort())
+      .toEqual(['allowed-local', 'read'])
+    expect(await run(ctx, 'web', denied.key)).toBe('ran:web')
+    expect(await run(ctx, 'web', allowed.key)).toBe('Error: unknown tool "web"')
+    expect(await run(ctx, 'denied-local', denied.key)).toBe('ran:denied-local')
+    expect(await run(ctx, 'allowed-local', allowed.key)).toBe('ran:allowed-local')
+  })
+
   it('composes multiple restrictions by intersection and lifts each independently', async () => {
     const ctx = await mount()
     const { scope, key } = await mintAgentScope(ctx, 'a')

packages/subagent/subagent-fork/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-subagent-fork
 
-The in-process **fork** subagent backend: a [`SubagentProvider`](../subagent/README.md) that runs each child as a child [`Agent`](../../core/agent) **seeded with a prefix of the parent's session log** — so the child inherits the parent's conversation context instead of starting fresh. Shares the run driver (`startInProcessRun`) with [`dsh-subagent-spawn`](../subagent-spawn/README.md); the only difference is the seed. The shared `run.started` boundary resolves only after the seeded child is published, so `subagent/start` observers see a live registry entry.
+The in-process **fork** subagent backend: a [`SubagentProvider`](../subagent/README.md) that runs each child as a child [`Agent`](../../core/agent) **seeded with a prefix of the parent's session log** instead of starting with an empty conversation. The seed affects conversation history only. Tool registrations and restrictions follow the child's fresh flat scope; no parent/child authority relation is defined. Fork shares the run driver (`startInProcessRun`) with [`dsh-subagent-spawn`](../subagent-spawn/README.md); the only difference is the seed. The shared `run.started` boundary resolves only after the seeded child is published, so `subagent/start` observers see a live registry entry.
 
 ## The seed boundary (the crux)
 

packages/subagent/subagent-inprocess/README.md

@@ -8,13 +8,15 @@ The shared **in-process subagent run driver**. A library with no provider or imp
 
 Runs a child as a child [`Agent`](../../core/agent) on the same cordis context (`ctx.agents`):
 
-1. reads every public request and seed field once before asynchronous owner setup: the parent and signal remain identity capabilities, while tool filter, seed, agent options, output schema, and prompt are each materialized by the shared one-pass lossless-JSON snapshot. It rejects a malformed `request.maxDepth`, validates the parent's `subagentDepth`, computes child depth = `depthOf(parent) + 1`, rejects cap overflow with `SubagentDepthError`, reports an invalid schema as `OutputSchemaError`, and derives both the child prefix and `seedLength` from the same detached seed;
+1. reads every public request and seed field once before asynchronous owner setup: the parent and signal remain identity capabilities, while tool filter, seed, agent options, output schema, and prompt are each materialized by the shared one-pass lossless-JSON snapshot. It rejects malformed `request.maxDepth` and `persona` values, validates the parent's `subagentDepth`, computes child depth = `depthOf(parent) + 1`, rejects a child depth outside the safe-integer domain with `RangeError`, rejects a defined `maxDepth` cap breach with `SubagentDepthError`, reports an invalid schema as `OutputSchemaError`, and derives both the child prefix and `seedLength` from the same detached seed;
 2. first installs provider ownership, then attaches the request abort listener and creates one run-owner Cordis fiber under `parent.ctx`; an already-unloading provider therefore leaves no child or orphaned listener. Async child creation goes through that fiber's `ctx.agents` service with fresh IDs, lineage/seed, inherited model, and an unpublished setup transaction for persona, tool restriction, and structured output. Parent teardown, provider teardown, manual `run.dispose()`, and cancellation before readiness all dispose this exact node, preventing publication after it becomes inactive and sharing the same quiescence boundary. `startInProcessRun` still returns its `SubagentRun` immediately: `run.started` resolves only after `ctx.agents.create()` has published the child and rejects when pre-readiness cancellation rolls the transaction back;
 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); there is deliberately NO re-prompt for a structured child that finished cleanly without calling `structured_output` — the shortfall maps to an `error` result for the parent;
 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).
 
 `SubagentService` waits for `run.started` before emitting `subagent/start`, so a synchronous start observer can resolve the published child with `ctx.agents.get(run.id)`; the result driver awaits the same boundary before sending the prompt. An attempt that never publishes rejects readiness and emits no false start/end pair; its result reports a deliberate cancel/dispose as `aborted` and propagates an infrastructure fault. `dispose()` awaits creation or rollback and then delegates to `AgentHandle.dispose()` (stop and drain → remove agent → detach session → unwind scope). Before readiness, `cancel()` deactivates the creation owner: before creation notification begins, no agent/session lifecycle edge escapes; if cancellation is triggered synchronously by a creation observer, every begun edge is paired by rollback and the driver never unlocks or starts. After readiness, cancellation reaches the live child immediately. Either path records the cancellation, so a cancel landing before any `turn/end` settles `aborted`, honoring the cancel contract rather than the generic no-turn `error`.
 
+The child receives a fresh flat registration scope. Its `toolFilter` masks the live global tool layer and scope-local registrations are merged afterward; parent ownership does not import the parent's tool restrictions or establish an authority subset. The [agent-scope RFC](../../../docs/rfc/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals) owns that explicit non-goal.
+
 ### `InProcessRunOptions`
 
 `{ seed?: SessionEvent[] }` — the optional child-session seed: absent for spawn, or the parent's balanced completed-turn prefix for fork.
@@ -32,8 +34,8 @@ Runs a child as a child [`Agent`](../../core/agent) on the same cordis context (
 
 ### `depthOf(agent): number`
 
-Delegation depth rides on a merge-extensible `AgentOptions.subagentDepth` field (0 for a top-level agent, parent + 1 for a child), so a nested spawn reads its parent's depth from `parent.options.subagentDepth`. `depthOf` reads it (absent ⇒ 0).
+Delegation depth rides on a merge-extensible `AgentOptions.subagentDepth` field (0 for a top-level agent, parent + 1 for a child), so a nested spawn reads its parent's depth from `parent.options.subagentDepth`. `depthOf` treats only `undefined` as absent (top-level depth 0) and rejects every malformed present value instead of letting it disable the cap comparison.
 
 ### `SubagentDepthError`
 
-Thrown by `startInProcessRun` when a spawn would exceed the request's `maxDepth` cap; carries `attemptedDepth` and `maxDepth`.
+Thrown by `startInProcessRun` when a spawn would exceed the request's defined `maxDepth` cap; carries `attemptedDepth` and `maxDepth`. A valid parent at `Number.MAX_SAFE_INTEGER` instead produces `RangeError`, because its child depth cannot be represented within the stored safe-integer domain even when `maxDepth` is omitted.

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

@@ -58,7 +58,8 @@ declare module '@deepseek-ai/dsh-agent' {
  * @returns 0 for a top-level agent, its parent's depth + 1 for a subagent.
  */
 export function depthOf(agent: Agent): number {
-  const depth = agent.options.subagentDepth ?? 0
+  const depth = agent.options.subagentDepth
+  if (depth === undefined) return 0
   if (!Number.isSafeInteger(depth) || depth < 0 || Object.is(depth, -0)) {
     throw new TypeError('agent subagentDepth must be a non-negative safe integer')
   }
@@ -123,7 +124,8 @@ async function quiesceFiber(fiber: Fiber): Promise<void> {
  * resolves `aborted`.
  *
  * Throws {@link SubagentDepthError} before creating anything when the child's
- * depth (parent depth + 1) would exceed `request.maxDepth`.
+ * depth (parent depth + 1) would exceed `request.maxDepth`, and throws a
+ * `RangeError` when a valid parent depth has no safe-integer successor.
  * @param ctx - the provider context that owns the live run as a second
  *   structured-concurrency boundary alongside the parent agent.
  * @param request - the start request (prompt, parent, signal, per-child options).
@@ -147,6 +149,9 @@ export function startInProcessRun(
   const inputAgentOptions = request.agentOptions
   const inputSeed = options.seed
   assertSubagentMaxDepth(inputMaxDepth)
+  if (persona !== undefined && typeof persona !== 'string') {
+    throw new TypeError('subagent persona must be a string')
+  }
   const toolFilter = inputToolFilter === undefined ? undefined : snapshotJsonValue(inputToolFilter)
   if (inputToolFilter !== undefined && toolFilter === undefined) {
     throw new TypeError('subagent tool filter must be losslessly JSON-serializable')
@@ -156,6 +161,9 @@ export function startInProcessRun(
     throw new TypeError('subagent seed must be losslessly JSON-serializable')
   }
   const childDepth = depthOf(parent) + 1
+  if (!Number.isSafeInteger(childDepth)) {
+    throw new RangeError('subagent child depth exceeds the safe-integer range')
+  }
   if (inputMaxDepth !== undefined && childDepth > inputMaxDepth) {
     throw new SubagentDepthError(childDepth, inputMaxDepth)
   }

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

@@ -36,7 +36,7 @@ const SCHEMA: StructuredOutputSchema = {
 }
 
 /**
- * Real loop + scripted mock model + an INLINE spawn-shaped provider over the
+ * Real loop + scripted mock model + an INLINE fresh-conversation provider over the
  * shared driver. The concrete backend plugins are deliberately NOT loaded —
  * they would devDep-cycle this package (spawn/fork already depend on the
  * driver), and the runtime under test is the driver's; plugin-level structured

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

@@ -48,6 +48,7 @@ describe('depthOf', () => {
   })
 
   it.each([
+    { label: 'null', value: null as unknown as number },
     { label: 'a string', value: '1' as unknown as number },
     { label: 'NaN', value: Number.NaN },
     { label: 'positive infinity', value: Number.POSITIVE_INFINITY },
@@ -64,6 +65,7 @@ describe('depthOf', () => {
 
 describe('startInProcessRun', () => {
   it.each([
+    { label: 'null', value: null as unknown as number },
     { label: 'a string', value: '1' as unknown as number },
     { label: 'NaN', value: Number.NaN },
     { label: 'positive infinity', value: Number.POSITIVE_INFINITY },
@@ -81,6 +83,27 @@ describe('startInProcessRun', () => {
     }, {})).toThrow('subagent maxDepth must be a non-negative safe integer')
   })
 
+  it('rejects a non-string persona before acquiring run ownership', async () => {
+    const { ctx, parent } = await setup([])
+    expect(() => startInProcessRun(ctx, {
+      prompt: [{ type: 'text', text: 'must never start' }],
+      parent,
+      persona: 42 as unknown as string,
+    }, {})).toThrow('subagent persona must be a string')
+  })
+
+  it('rejects a child depth with no safe-integer representation before acquiring run ownership', async () => {
+    const { ctx } = await setup([])
+    const parent = {
+      options: { subagentDepth: Number.MAX_SAFE_INTEGER },
+    } as unknown as Agent
+
+    expect(() => startInProcessRun(ctx, {
+      prompt: [{ type: 'text', text: 'must never start' }],
+      parent,
+    }, {})).toThrow(RangeError)
+  })
+
   it('rejects a non-JSON prompt before acquiring any run ownership', async () => {
     const { ctx, parent } = await setup([])
     expect(() => startInProcessRun(ctx, {

packages/subagent/subagent/README.md

@@ -29,7 +29,7 @@ Unlike the bash seam (one executor per context, second load throws), **multiple
 - **Start-time features** (`outputSchema`, `depthLimit`, `toolFilter/persona`) 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: `provider.inheritsParentContext` — whether a child sees the parent conversation (`fork`: true — seeded with the completed-turn prefix; `spawn`/`acp`: false). The service validates that the descriptor is a boolean but does not interpret or enforce its meaning; the model-facing consumer (`dsh-tool-subagent`) derives truthful tool wording from it.
+Beside `capabilities` sits one DESCRIPTIVE fact: `provider.inheritsParentContext` — whether a child sees the parent conversation (`fork`: true — seeded with the completed-turn prefix; `spawn`/`acp`: false). “Context” here means conversation history only; it says nothing about tool registrations, injected services, or authority inheritance. The service validates that the descriptor is a boolean but does not interpret or enforce its meaning; the model-facing consumer (`dsh-tool-subagent`) derives truthful tool wording from it.
 
 ## Run lifecycle
 

packages/subagent/subagent/src/types.ts

@@ -69,9 +69,10 @@ export interface SubagentStartRequest {
    */
   outputSchema?: StructuredOutputSchema
   /**
-   * Optional recursion cap (max delegation depth below this child). Must be a
-   * non-negative safe integer. Requires {@link SubagentCapabilities.depthLimit};
-   * rejected at start otherwise.
+   * Optional absolute delegation-depth cap for the child being started: its
+   * computed depth must be less than or equal to this non-negative safe
+   * integer. Requires {@link SubagentCapabilities.depthLimit}; rejected at
+   * start otherwise.
    */
   maxDepth?: number
   /**
@@ -195,13 +196,15 @@ export interface SubagentProvider {
   /** 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
+   * The provider's conversation-history descriptor: `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".
+   * model the child "does not see this conversation". This descriptor concerns
+   * conversation history only; it says nothing about tool registrations,
+   * injected services, or authority inheritance.
    */
   readonly inheritsParentContext: boolean
   /**

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

@@ -226,7 +226,7 @@ describe('SubagentService', () => {
       patch: { capabilities: { ...NO_CAPS, persona: 'yes' } },
       message: 'capability "persona" must be a boolean',
     },
-    { label: 'a non-boolean context descriptor', patch: { inheritsParentContext: 'yes' }, message: 'inheritsParentContext must be a boolean' },
+    { label: 'a non-boolean conversation-history descriptor', patch: { inheritsParentContext: 'yes' }, message: 'inheritsParentContext must be a boolean' },
     { label: 'a non-callable start field', patch: { start: 42 }, message: 'start must be a function' },
   ])('rejects a provider registration with $label before entering the registry', async ({ patch, message }) => {
     const ctx = new Context()
@@ -431,6 +431,7 @@ describe('SubagentService', () => {
     })
 
     it.each([
+      { label: 'null', value: null as unknown as number },
       { label: 'a string', value: '1' as unknown as number },
       { label: 'NaN', value: Number.NaN },
       { label: 'positive infinity', value: Number.POSITIVE_INFINITY },

packages/subagent/tool-subagent/README.md

@@ -6,9 +6,9 @@ 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 description states the provider's conversation-history descriptor
 
-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).
+The tool description and the `prompt` parameter description are DERIVED from the bound provider's `inheritsParentContext` (`providerWording`): a fresh-conversation provider (spawn, ACP) gets the standalone-prompt wording ("it does not see this conversation"), while fork tells the model the child is seeded with the conversation's completed turns and its prompt should state only what is new. The descriptor concerns conversation history only, not tool or authority inheritance. 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 plugins 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 |
 |---|---|
@@ -17,7 +17,9 @@ The tool description and the `prompt` parameter description are DERIVED from the
 | `agentOptions` | Default per-child `{ model? }` applied to every spawned child. |
 | `persona` | Per-child persona that shadows the deployment persona; requires the provider's `persona` capability. |
 | `toolFilter` | Per-child `{ allow?, deny? }` restriction over global tools; requires the provider's `toolFilter` capability. |
-| `maxDepth` | Maximum delegation depth; a non-negative safe integer validated when this plugin loads. Requires the provider's `depthLimit` capability. |
+| `maxDepth` | Maximum absolute delegation-tree depth for every child this tool starts; a non-negative safe integer validated when this plugin loads. Requires the provider's `depthLimit` capability. |
+
+`toolFilter` uses [`ToolRegistry.restrict()`](../../core/tools/README.md)'s live global-view semantics and is not a parent-derived authority ceiling; see the [agent-scope security non-goal](../../../docs/rfc/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals).
 
 ## Lifecycle (synchronous collect)
 

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

@@ -11,10 +11,12 @@
  * — 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
+ * The tool DESCRIPTION is derived from the bound provider's conversation-history
+ * descriptor ({@link providerWording}): a fresh-conversation provider (spawn,
+ * ACP) gets the standalone-prompt wording, while a seeded-conversation provider
+ * (fork) tells the model the child already sees the conversation's completed
+ * turns. This descriptor says nothing about Cordis scope, services, tools, or
+ * authority. 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
@@ -154,16 +156,19 @@ function stopReasonError(result: SubagentResult): string | undefined {
 }
 
 /**
- * Model-facing wording per context contract ({@link SubagentProvider.inheritsParentContext}).
+ * Model-facing wording from the provider's conversation-history descriptor
+ * ({@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.
+ * @param inheritsConversation - whether the child's conversation is seeded
+ *   with the parent's completed turns; this says nothing about tool, service,
+ *   scope, or authority inheritance.
  * @returns the tool `description` and the `prompt` parameter description.
  */
-export function providerWording(inherits: boolean): { description: string; promptDescription: string } {
-  if (inherits) {
+export function providerWording(inheritsConversation: boolean): { description: string; promptDescription: string } {
+  if (inheritsConversation) {
     return {
       description:
         'Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all '

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

@@ -220,7 +220,7 @@ describe('dsh-tool-subagent', () => {
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(SubagentService)
-    const backend = await ctx.plugin(mock, { name: 'mock' }) // spawn-shaped (inherits: false)
+    const backend = await ctx.plugin(mock, { name: 'mock' }) // fresh conversation (descriptor: false)
     await ctx.plugin(tool, { provider: 'mock' })
     expect(ctx.tools.schemas().find(s => s.name === 'subagent')!.description).toContain('does not see this conversation')
 
@@ -228,7 +228,7 @@ describe('dsh-tool-subagent', () => {
     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
+    // Backend reloads with a DIFFERENT conversation-history descriptor: 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')
@@ -273,7 +273,7 @@ describe('dsh-tool-subagent', () => {
     expect(ctx.tools.schemas().some(s => s.name === 'subagent')).toBe(true)
   })
 
-  it('derives spawn-shaped wording from a fresh-context provider (default mock)', async () => {
+  it('derives spawn-shaped wording from a fresh-conversation 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')
@@ -281,7 +281,7 @@ describe('dsh-tool-subagent', () => {
     expect(props['prompt']!.description).toContain('include everything it needs')
   })
 
-  it('derives fork-shaped wording from an inheriting provider (the description stops lying)', async () => {
+  it('derives fork-shaped wording from a seeded-conversation 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')
@@ -494,6 +494,8 @@ describe('dsh-tool-subagent', () => {
   })
 
   it.each([
+    { label: 'null', value: null as unknown as number },
+    { label: 'a string', value: '1' as unknown as number },
     { label: 'NaN', value: Number.NaN },
     { label: 'positive infinity', value: Number.POSITIVE_INFINITY },
     { label: 'negative infinity', value: Number.NEGATIVE_INFINITY },
@@ -506,6 +508,16 @@ describe('dsh-tool-subagent', () => {
       .rejects.toThrow()
   })
 
+  it('validates maxDepth when apply() is invoked directly without Schemastery', () => {
+    const ctx = new Context()
+    expect(() => {
+      tool.apply(ctx, {
+        provider: 'unused',
+        maxDepth: Number.NaN,
+      })
+    }).toThrow('subagent maxDepth must be a non-negative safe integer')
+  })
+
   it('a partial toolFilter (deny only) does not materialize an empty allow-list (deny-all trap)', async () => {
     let seen: { toolFilter?: { allow?: string[]; deny?: string[] } } | undefined
     const ctx = new Context()

packages/support/subagent-mock/README.md

@@ -14,7 +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. |
+| `inheritsParentContext` | `false` | Conversation-history descriptor: `false` means fresh, while `true` exercises seeded/fork wording. It says nothing about tool, service, scope, or authority inheritance. |
 | `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

@@ -94,9 +94,11 @@ export interface Config {
   /** 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.
+   * The conversation-history descriptor to declare
+   * ({@link SubagentProvider.inheritsParentContext}); default `false` (fresh
+   * conversation). Set `true` to exercise seeded/fork wording in consumer
+   * tests. This flag says nothing about tool, service, scope, or authority
+   * inheritance.
    */
   inheritsParentContext?: boolean
   /**