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