fix(core): enforce agent-scoped ownership boundaries

packages/subagent/subagent/src/index.ts

@@ -34,6 +34,8 @@
 
 import { Context, Service } from 'cordis'
 import { scopeTarget } from '@deepseek-ai/dsh-scope'
+import { assertSupportedOutputSchema } from '@deepseek-ai/dsh-tools'
+import type { Scoped } from '@deepseek-ai/dsh-scope'
 import { HarnessError } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { Agent, AgentId } from '@deepseek-ai/dsh-agent'
@@ -93,7 +95,7 @@ declare module 'cordis' {
      * @param info - which provider started which child agent.
      * @mode emit
      */
-    'subagent/start'(info: SubagentRunInfo): void
+    'subagent/start'(this: Scoped<SubagentService>, info: SubagentRunInfo): void
     /**
      * A subagent run settled — emitted when {@link SubagentRun.result}
      * resolves (any stop reason). Paired with {@link Events['subagent/start']}.
@@ -104,7 +106,7 @@ declare module 'cordis' {
      * @param info - the run identity plus stop reason and final output.
      * @mode emit
      */
-    'subagent/end'(info: SubagentRunEndInfo): void
+    'subagent/end'(this: Scoped<SubagentService>, info: SubagentRunEndInfo): void
   }
 }
 
@@ -224,13 +226,32 @@ export class SubagentService extends Service {
    * @returns the live run (its `result` resolves when the child settles).
    */
   start(name: string, request: SubagentStartRequest): SubagentRun {
+    // Parent is the lifecycle scope identity accepted at start. Never reread it
+    // from the caller-owned request after the provider/result async boundary,
+    // or start/end could be dispatched into different agent scopes.
+    const parent = request.parent
     const provider = this.providers.get(name)
     if (!provider) {
       throw new SubagentError(`no subagent provider registered for "${name}"`, 'NO_PROVIDER')
     }
     this.assertCapabilities(provider, request)
+    if (request.outputSchema !== undefined) assertSupportedOutputSchema(request.outputSchema)
 
-    const run = provider.start(request)
+    // Detach every data field before crossing into a provider. Parent/signal
+    // are live identity capabilities and stay exact; the mutable request record
+    // and its arrays/objects are never retained, so every backend (including an
+    // async out-of-process one) observes the request accepted at start.
+    const accepted: SubagentStartRequest = {
+      prompt: structuredClone(request.prompt),
+      parent,
+      ...request.signal !== undefined ? { signal: request.signal } : {},
+      ...request.agentOptions !== undefined ? { agentOptions: structuredClone(request.agentOptions) } : {},
+      ...request.outputSchema !== undefined ? { outputSchema: structuredClone(request.outputSchema) } : {},
+      ...request.maxDepth !== undefined ? { maxDepth: request.maxDepth } : {},
+      ...request.toolFilter !== undefined ? { toolFilter: structuredClone(request.toolFilter) } : {},
+      ...request.persona !== undefined ? { persona: request.persona } : {},
+    }
+    const run = provider.start(accepted)
     // Emit `subagent/start` with PER-LISTENER containment (see {@link emitLifecycle}):
     // the run is already live, so neither a throwing subscriber escaping
     // `start()` (the caller would never receive the run to dispose it — a leaked
@@ -238,7 +259,7 @@ export class SubagentService extends Service {
     // acceptable. `ctx.emit` halts the dispatch on the first throw, so a single
     // surrounding try/catch is not enough — each listener is invoked and
     // contained individually.
-    this.emitLifecycle('subagent/start', { provider: name, id: run.id }, request.parent)
+    this.emitLifecycle('subagent/start', { provider: name, id: run.id }, parent)
     // Emit `subagent/end` when the run settles. The result promise does not
     // reject on a child-level failure (it resolves with stopReason 'error'),
     // so a rejection here is an infrastructure fault — surface its stop reason
@@ -268,9 +289,9 @@ export class SubagentService extends Service {
         } catch (error: unknown) {
           this.ctx.logger.warn(`subagent: could not clone ${name} output for subagent/end: ${String(error)}`)
         }
-        this.emitLifecycle('subagent/end', { provider: name, id: run.id, stopReason: result.stopReason, ...lastAssistantMessage !== undefined ? { lastAssistantMessage } : {} }, request.parent)
+        this.emitLifecycle('subagent/end', { provider: name, id: run.id, stopReason: result.stopReason, ...lastAssistantMessage !== undefined ? { lastAssistantMessage } : {} }, parent)
       },
-      () => { this.emitLifecycle('subagent/end', { provider: name, id: run.id, stopReason: 'error' }, request.parent) },
+      () => { this.emitLifecycle('subagent/end', { provider: name, id: run.id, stopReason: 'error' }, parent) },
     )
     return run
   }

packages/subagent/subagent/src/types.ts

@@ -120,9 +120,11 @@ export interface SubagentResult {
   /** The child's final assistant output (the last assistant message's content). */
   output: ContentBlock[]
   /**
-   * The structured result, present IFF the request carried an `outputSchema`
-   * AND the provider honored it. Shape is validated against the request schema
-   * by the provider; `unknown` here because the seam is schema-agnostic.
+   * The structured result after a requested `outputSchema` was successfully
+   * satisfied. Requesting a schema does not guarantee presence: a provider can
+   * end with `stopReason: 'error'` when the child fails or finishes without a
+   * valid capture. Shape is validated against the request schema by the
+   * provider; `unknown` here because the seam is schema-agnostic.
    */
   structured?: unknown
   /** Why the run ended. A non-`completed` reason means `output` may be partial. */

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

@@ -2,6 +2,7 @@ import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import { AgentId, type Agent } from '@deepseek-ai/dsh-agent'
 import { HarnessError } from '@deepseek-ai/dsh-llm'
+import { carrierKeyOf } from '@deepseek-ai/dsh-scope'
 import SubagentService, {
   SubagentError,
   type SubagentCapabilities,
@@ -227,6 +228,45 @@ describe('SubagentService', () => {
     expect(ended).toHaveBeenCalledWith(expect.objectContaining({ provider: 'events', id: run.id, stopReason: 'completed' }))
   })
 
+  it('pins start and end to the parent accepted at start despite caller mutation', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SubagentService)
+    const gate = Promise.withResolvers<SubagentResult>()
+    let acceptedRequest: SubagentStartRequest | undefined
+    ctx.subagents.registerProvider({
+      name: 'deferred',
+      capabilities: NO_CAPS,
+      inheritsParentContext: false,
+      start: (accepted) => {
+        acceptedRequest = accepted
+        return {
+          id: AgentId('deferred-child'),
+          result: gate.promise,
+          cancel() {},
+          async dispose() {},
+        }
+      },
+    })
+    const accepted = fakeParent('accepted-parent')
+    const replacement = fakeParent('replacement-parent')
+    const keys: unknown[] = []
+    ctx.on('subagent/start', function () { keys.push(carrierKeyOf(this)) })
+    ctx.on('subagent/end', function () { keys.push(carrierKeyOf(this)) })
+    const request = baseRequest({ parent: accepted })
+
+    const run = ctx.subagents.start('deferred', request)
+    request.parent = replacement
+    request.prompt[0] = { type: 'text', text: 'mutated prompt' }
+    expect(acceptedRequest?.parent).toBe(accepted)
+    expect(acceptedRequest?.prompt).toEqual([{ type: 'text', text: 'do a thing' }])
+    expect(acceptedRequest?.prompt).not.toBe(request.prompt)
+    gate.resolve({ output: [], stopReason: 'completed' })
+    await run.result
+    await Promise.resolve()
+
+    expect(keys).toEqual([accepted, accepted])
+  })
+
   it('carries lastAssistantMessage (the child output) onto the end event', async () => {
     const ctx = new Context()
     await ctx.plugin(SubagentService)