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/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')