feat(subagent): persona + toolFilter become real; structured runtime collapses to scoped registrations

SubagentStartRequest gains persona (capability-gated like toolFilter); the
in-process driver composes the child's scoped world in the factory's setup
window — persona as a scoped shadowing deployment:persona section,
toolFilter as a scoped tools.restrict() (loud unknown-name validation),
outputSchema as the scoped structured runtime. spawn/fork now advertise
every start-time capability; ACP stays all-false. A parent-scope teardown
effect links each child to its parent through the memoized handle, so a
disposed parent reaches its whole subtree even if the delegating tool's
finally never runs; subagent/start|end dispatch in the delegating parent's
scope.

structured.ts loses the placeholder schema, the final-assembly swap/strip,
the refcounted root runtime, and the WeakMap state: each child registers
its OWN capture tool (real schema), instruction section, and enforcement
listeners on child.ctx, riding the child's fiber. The commit listener is
call-keyed (a stale stage from a short-circuited post-execute chain is
dropped, never promoted on a later call), and one scoped prepend re-assert
listener preserves the final-assembly guarantee against a stripping global
listener.

tool-subagent gains persona/toolFilter/maxDepth passthrough config —
deny-listing the delegation tool (or maxDepth) is how a deployment bounds
recursion; the omitted-toolFilter schema key is forced absent (a
materialized {} would mean an empty allow-list, i.e. deny-everything).

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

@@ -43,13 +43,14 @@ export const Config: z<Config> = z.object({
 })
 
 /**
- * The spawn provider. Supports `depthLimit` (it constructs the child, so it can
- * enforce a recursion cap) and `outputSchema` (via the shared in-process
- * structured runtime); NOT `toolFilter` in this cut — a request that needs it
- * is rejected by the service before `start` runs.
+ * The spawn provider. Supports every start-time capability: `depthLimit` (it
+ * constructs the child, so it can enforce a recursion cap), `outputSchema`
+ * (the scoped structured runtime), and `toolFilter`/`persona` (scoped
+ * `restrict()` and a scoped shadowing persona section, applied in the child's
+ * creation window).
  */
 class SpawnProvider implements SubagentProvider {
-  readonly capabilities: SubagentCapabilities = { outputSchema: true, depthLimit: true, toolFilter: false }
+  readonly capabilities: SubagentCapabilities = { outputSchema: true, depthLimit: true, toolFilter: true, persona: true }
   // Context contract: a spawned child starts fresh — it never sees the parent conversation.
   readonly inheritsParentContext = false
 

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

@@ -241,10 +241,10 @@ describe('dsh-subagent-spawn', () => {
     await parentHandle.dispose()
   })
 
-  it('advertises depthLimit and outputSchema but not toolFilter', async () => {
+  it('advertises every start-time capability (depthLimit, outputSchema, toolFilter, persona)', async () => {
     const { ctx } = await setup([])
     const provider = ctx.subagents.getProvider('spawn')!
-    expect(provider.capabilities).toEqual({ outputSchema: true, depthLimit: true, toolFilter: false })
+    expect(provider.capabilities).toEqual({ outputSchema: true, depthLimit: true, toolFilter: true, persona: true })
   })
 
   it('unregisters the provider when its fiber is disposed (HMR safety)', async () => {
@@ -316,4 +316,65 @@ describe('dsh-subagent-spawn', () => {
     expect(unwrapped.inject).toEqual(['subagents', 'agents'])
     expect(typeof unwrapped.apply).toBe('function')
   })
+
+  describe('persona and toolFilter (the scoped child world)', () => {
+    it('a per-child persona shadows the deployment persona in the child request only', async () => {
+      const { ctx, parent, adapter } = await setup([
+        textResponse('parent answer'),
+        textResponse('child answer'),
+      ])
+      parent.send([{ type: 'text', text: 'hi' }])
+      await parent.whenIdle()
+
+      const run = ctx.subagents.start('spawn', {
+        prompt: [{ type: 'text', text: 'do X' }],
+        parent,
+        persona: 'You are the tersest test runner.',
+      })
+      await run.result
+      const childRequest = adapter.requests.at(-1)!
+      expect(childRequest.system).toContain('You are the tersest test runner.')
+      // The parent's earlier request carried no such persona.
+      expect(adapter.requests[0]!.system ?? '').not.toContain('tersest test runner')
+      await run.dispose()
+    })
+
+    it('toolFilter hides denied tools from the child prompt AND refuses their execution', async () => {
+      const { ctx, parent, adapter } = await setup([
+        // The child tries the denied tool anyway, then answers.
+        toolCallResponse('c1', 'forbidden_tool', {}),
+        textResponse('done'),
+      ])
+      ctx.tools.register({
+        name: 'forbidden_tool', description: 'global', parameters: {},
+        execute: () => Promise.resolve([{ type: 'text', text: 'ran' }]),
+      })
+      const run = ctx.subagents.start('spawn', {
+        prompt: [{ type: 'text', text: 'do X' }],
+        parent,
+        toolFilter: { deny: ['forbidden_tool'] },
+      })
+      const result = await run.result
+      expect(result.stopReason).toBe('completed')
+      // Not advertised…
+      const childRequest = adapter.requests[0]!
+      expect((childRequest.tools ?? []).map(t => t.name)).not.toContain('forbidden_tool')
+      // …and the attempted call executed as UNKNOWN_TOOL (visible in the log).
+      const child = ctx.agents.get(run.id)!
+      const toolResult = child.session.events.find(e => e.type === 'tool/result')!
+      expect(JSON.stringify(toolResult.data)).toContain('unknown tool')
+      await run.dispose()
+    })
+
+    it('an unknown toolFilter name fails the spawn loudly with no orphaned child', async () => {
+      const { ctx, parent } = await setup([])
+      const before = ctx.agents.list().length
+      expect(() => ctx.subagents.start('spawn', {
+        prompt: [{ type: 'text', text: 'do X' }],
+        parent,
+        toolFilter: { deny: ['no_such_tool'] },
+      })).toThrow(/unknown tool "no_such_tool"/)
+      expect(ctx.agents.list().length).toBe(before)
+    })
+  })
 })