Merge remote-tracking branch 'origin/master' into xtr/react-loop-simplification

# Conflicts: # .agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml # .agents/notes/implemented/architecture/2026-07-31-goal-owned-durable-events.i18n.yaml # .agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml # .agents/notes/implemented/feature/2026-07-22-docked-web-goal-bar.i18n.yaml # docs/architecture.i18n.yaml # docs/architecture.md # docs/architecture.zh.md # docs/config-catalog.md # docs/cordis-catalog/events.md # docs/cordis-catalog/services.md # docs/core-data-structures/core.i18n.yaml # docs/core-data-structures/core.md # docs/core-data-structures/core.zh.md # docs/event-producer-consumer.md # docs/module-graph.md # docs/persistence-catalog.md # examples/acp-agent/tests/snapshots/advanced-toolchain/session.1.jsonl # examples/acp-agent/tests/snapshots/advanced-toolchain/session.2.jsonl # examples/acp-agent/tests/snapshots/code-mode-workspace-context/session.jsonl # examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl # examples/acp-agent/tests/snapshots/skill-load/session.jsonl # examples/acp-agent/tests/snapshots/subagent-depth-two-rejection/session.1.jsonl # examples/acp-agent/tests/snapshots/subagent-depth-two-rejection/session.2.jsonl # examples/acp-agent/tests/snapshots/subagent-fork/session.1.jsonl # examples/acp-agent/tests/snapshots/subagent-mixed/session.1.jsonl # examples/acp-agent/tests/snapshots/subagent-mixed/session.2.jsonl # examples/acp-agent/tests/snapshots/subagent-multi/session.1.jsonl # examples/acp-agent/tests/snapshots/subagent-multi/session.2.jsonl # examples/acp-agent/tests/snapshots/subagent-spawn/session.1.jsonl # examples/acp-agent/tests/snapshots/workflow-run/session.1.jsonl # examples/acp-agent/tests/snapshots/workspace-context/session.jsonl # examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl # examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl # examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl # examples/headless-agent/tests/snapshots/pty-tools/session.jsonl # examples/headless-agent/tests/subagent-inheritance-snapshots/parent-override/child.expected.jsonl # examples/jsonrpc-agent/tests/snapshots/subagent-spawn/notifications.expected.jsonl # examples/jsonrpc-agent/tests/snapshots/subagent-spawn/session.1.jsonl # packages/acp/acp/README.i18n.yaml # packages/acp/acp/src/index.ts # packages/client/connection/src/client/index.ts # packages/client/runtime/README.i18n.yaml # packages/client/runtime/README.md # packages/client/runtime/README.zh.md # packages/client/runtime/src/client/sessions/conversation.ts # packages/client/runtime/src/client/sessions/session.ts # packages/client/runtime/tests/queue-store.spec.ts # packages/client/ui-conversation/src/client/input/contract.ts # packages/client/ui-goal/README.i18n.yaml # packages/compact/compact-basic/src/index.ts # packages/context/time-context/tests/time-context.spec.ts # packages/context/tmux-context/tests/tmux-context.spec.ts # packages/context/workspace-context/tests/workspace-context.spec.ts # packages/cordis/tool-cordis/src/api-catalog.ts # packages/core/agent-loop/README.i18n.yaml # packages/core/agent-loop/README.md # packages/core/agent-loop/README.zh.md # packages/core/agent-loop/src/agent.ts # packages/core/agent-loop/tests/agent.spec.ts # packages/core/agent-loop/tests/loop.spec.ts # packages/core/agent/README.i18n.yaml # packages/core/agent/README.md # packages/core/agent/README.zh.md # packages/core/agent/src/types.ts # packages/core/session/README.i18n.yaml # packages/core/session/README.md # packages/core/session/README.zh.md # packages/goal/command-goal/tests/command-goal.spec.ts # packages/goal/goal/tests/goal.spec.ts # packages/goal/tool-goal/README.i18n.yaml # packages/goal/tool-goal/README.md # packages/goal/tool-goal/README.zh.md # packages/host/apiproxy/README.i18n.yaml # packages/host/apiproxy/README.md # packages/host/apiproxy/README.zh.md # packages/host/apiproxy/src/api-proxy.ts # packages/host/apiproxy/src/api/events.schema.ts # packages/host/apiproxy/src/api/events.ts # packages/host/apiproxy/src/api/rpc.ts # packages/host/apiproxy/tests/api-proxy-commands.spec.ts # packages/host/apiproxy/tests/api-proxy-projections.spec.ts # packages/host/apiproxy/tests/rpc-schemas.spec.ts # packages/pty/pty-local/tests/index.spec.ts # packages/pty/pty-local/tests/local.spec.ts # packages/pty/tool-pty/tests/loader-composition.spec.ts # packages/pty/tool-pty/tests/tools.spec.ts # packages/session-persistence/session-checkpoint-policy/src/index.ts # packages/session-persistence/session-persistence/tests/coordinator-contract.ts # packages/skill/tool-skill/tests/tool-skill.spec.ts # packages/subagent/subagent-inprocess/README.i18n.yaml # packages/subagent/subagent-inprocess/README.md # packages/subagent/subagent-inprocess/README.zh.md # packages/subagent/subagent-inprocess/src/index.ts # packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts # packages/support/acp-snapshot/src/harness.ts # packages/ui/tui/tests/tui.spec.ts
2026-08-03 10:56:09 +08:00
parent b4258a2c4a 8bf606ba80
commit dc1d542092
605 changed files with 25740 additions and 2265 deletions
--- a/packages/core/agent-loop/src/index.ts
+++ b/packages/core/agent-loop/src/index.ts
@@ -547,7 +547,10 @@ export class AgentLoop extends Service implements AgentFactory {
    const prepared = this.prepare(ownerCtx, options.sessionId, options.agentOptions ?? {}, session, options.signal)
    const published = (async () => {
      try {
-        await raceAbort(options.setup?.(prepared.agent.ctx), prepared.signal, options.sessionId)
+        const setupCommit = await raceAbort(
+          options.setup?.(prepared.agent.ctx), prepared.signal, options.sessionId,
+        )
+        setupCommit?.commit()
        return prepared.publish('startup')
      } catch (error: unknown) {
        await prepared.dispose()
@@ -606,7 +609,8 @@ export class AgentLoop extends Service implements AgentFactory {
      })
      const prepared = this.prepare(ownerCtx, id, options.agentOptions ?? {}, session, options.signal)
      try {
-        await raceAbort(options.setup?.(prepared.agent.ctx), prepared.signal, id)
+        const setupCommit = await raceAbort(options.setup?.(prepared.agent.ctx), prepared.signal, id)
+        setupCommit?.commit()
        return prepared.publish('resume')
      } catch (error: unknown) {
        await prepared.dispose()
--- a/packages/core/agent-loop/tests/contract-regressions.spec.ts
+++ b/packages/core/agent-loop/tests/contract-regressions.spec.ts
@@ -103,6 +103,106 @@ describe('addressable inbox operations', () => {
      .toEqual(['first', 'edited'])
    expect(agent.inbox.splice('next-turn', 0, 1, [])).toEqual([])
  })
+
+  it('strictly transfers a queued occurrence into the open turn', async () => {
+    const adapter = new MockAdapter([textResponse('done')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('queue-to-steer'), { provider: 'mock', model: 'mock' })
+    const entered = Promise.withResolvers<undefined>()
+    const decision = Promise.withResolvers<{ kind: 'allow' }>()
+    ctx.on('agent/prompt-submit', async () => {
+      entered.resolve(undefined)
+      return decision.promise
+    })
+
+    const enqueued: InboxItem[] = []
+    const discarded: InboxItem[] = []
+    ctx.on('agent/inbox/enqueue', (subject, item) => {
+      if (subject === agent) enqueued.push(item)
+    })
+    ctx.on('agent/inbox/discard', (subject, items) => {
+      if (subject === agent) discarded.push(...items)
+    })
+
+    const idle = waitForIdle(ctx, agent)
+    send(agent, 'open the turn')
+    const receipt = agent.steer(createUserMessage({
+      content: [{ type: 'text', text: 'steer this message' }],
+      source: { kind: 'user' },
+    }))
+    await entered.promise
+    const queued = enqueued.find(item => inboxText(item) === 'steer this message')!
+
+    expect(agent.updateInbox(queued.id, { kind: 'steer' })).toBe('applied')
+    const steering = enqueued.find(item => item.placement === 'steering')!
+    expect(steering.id).not.toBe(queued.id)
+    expect(steering.message).toBe(queued.message)
+    expect(discarded).toEqual([queued])
+
+    decision.resolve({ kind: 'allow' })
+    await idle
+    expect(agent.session.events.flatMap(event =>
+      event.type === 'steering/message' ? [event.data.message] : [],
+    )).toEqual([queued.message])
+    expect(await receipt.outcome).toEqual({ status: 'admitted', turn: 1, step: 1 })
+    expect(agent.updateInbox(queued.id, { kind: 'steer' })).toBe('not-found')
+  })
+
+  it('keeps a queued occurrence when the next-step window is closed', () => {
+    const ctx = new Context()
+    const session = new Session(SessionId('queue-to-steer-closed'))
+    const agent = new ReactLoopAgent(ctx, session.id, {}, session)
+    const enqueued: InboxItem[] = []
+    const discarded: InboxItem[] = []
+    ctx.on('agent/inbox/enqueue', (_subject, item) => { enqueued.push(item) })
+    ctx.on('agent/inbox/discard', (_subject, items) => { discarded.push(...items) })
+
+    agent.send(
+      createUserMessage({ content: [{ type: 'text', text: 'stay queued' }], source: { kind: 'user' } }),
+      { target: 'next-turn', wakeup: false },
+    )
+    const queued = enqueued[0]!
+    expect(agent.updateInbox(queued.id, { kind: 'steer' })).toBe('steer-unavailable')
+    expect(discarded).toEqual([])
+    expect(agent.updateInbox(queued.id, { kind: 'remove' })).toBe('applied')
+  })
+
+  it('accounts for both occurrences when steering enqueue cancels reentrantly', async () => {
+    const adapter = new MockAdapter([textResponse('unused')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('queue-to-steer-cancel'), { provider: 'mock', model: 'mock' })
+    const entered = Promise.withResolvers<undefined>()
+    const decision = Promise.withResolvers<{ kind: 'allow' }>()
+    ctx.on('agent/prompt-submit', async () => {
+      entered.resolve(undefined)
+      return decision.promise
+    })
+
+    const enqueued: InboxItem[] = []
+    const discarded: InboxItem[] = []
+    ctx.on('agent/inbox/enqueue', (subject, item) => {
+      if (subject !== agent) return
+      enqueued.push(item)
+      if (item.placement === 'steering') agent.cancel({ kind: 'user' })
+    })
+    ctx.on('agent/inbox/discard', (subject, items) => {
+      if (subject === agent) discarded.push(...items)
+    })
+
+    const idle = waitForIdle(ctx, agent)
+    send(agent, 'open the turn')
+    await entered.promise
+    send(agent, 'cancel during conversion')
+    const queued = enqueued.find(item => inboxText(item) === 'cancel during conversion')!
+
+    expect(agent.updateInbox(queued.id, { kind: 'steer' })).toBe('applied')
+    const steering = enqueued.find(item => item.placement === 'steering')!
+    expect(discarded).toEqual([steering, queued])
+
+    decision.resolve({ kind: 'allow' })
+    await idle
+    expect(agent.session.events.some(event => event.type === 'steering/message')).toBe(false)
+  })
 })

 describe('assistant replay provenance', () => {
--- a/packages/core/agent-loop/tests/resume.spec.ts
+++ b/packages/core/agent-loop/tests/resume.spec.ts
@@ -291,6 +291,13 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
        setupStarted.resolve(undefined)
        await gate.promise
        order.push('setup:end')
+        return {
+          commit: () => {
+            expect(ctx.agents.get(sessionId)).toBeUndefined()
+            expect(ctx.sessions.get(sessionId)).toBeUndefined()
+            order.push('setup:commit')
+          },
+        }
      },
    })

@@ -304,6 +311,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
    expect(order).toEqual([
      'setup:start',
      'setup:end',
+      'setup:commit',
      'session/created',
      'setup-listener:session/created',
      'agent/created',
@@ -359,6 +367,33 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
    await ctx.fiber.dispose()
  })

+  it('resume setup commit rejection publishes nothing and releases the identity', async () => {
+    const sessionId = SessionId('resume-setup-commit-reject')
+    const root = await persistSession(sessionId)
+    const ctx = await mountPersistentHarness(root, new MockAdapter([textResponse('next')]))
+    const published: string[] = []
+    ctx.on('session/created', () => void published.push('session/created'))
+    ctx.on('agent/created', () => void published.push('agent/created'))
+
+    await expect(ctx.agents.resume({
+      resumeSessionId: sessionId,
+      agentOptions: { provider: 'mock', model: 'mock' },
+      setup: () => ({
+        commit: () => { throw new Error('resume setup commit failed') },
+      }),
+    })).rejects.toThrow('resume setup commit failed')
+
+    expect(published).toEqual([])
+    expect(ctx.agents.get(sessionId)).toBeUndefined()
+    expect(ctx.sessions.get(sessionId)).toBeUndefined()
+    const retry = await ctx.agents.resume({
+      resumeSessionId: sessionId,
+      agentOptions: { provider: 'mock', model: 'mock' },
+    })
+    await retry.dispose()
+    await ctx.fiber.dispose()
+  })
+
  it('owner unload aborts resume setup and cannot publish after the callback settles', async () => {
    const sessionId = SessionId('resume-setup-owner-unload')
    const root = await persistSession(sessionId)
--- a/packages/core/agent-loop/tests/scope-lifecycle.spec.ts
+++ b/packages/core/agent-loop/tests/scope-lifecycle.spec.ts
@@ -264,6 +264,13 @@ describe('agent scope lifecycle', () => {
        setupStarted.resolve(undefined)
        await gate.promise
        order.push('setup:end')
+        return {
+          commit: () => {
+            expect(ctx.agents.get(SessionId('atomic'))).toBeUndefined()
+            expect(ctx.sessions.get(SessionId('atomic'))).toBeUndefined()
+            order.push('setup:commit')
+          },
+        }
      },
    })
    await setupStarted.promise
@@ -276,6 +283,7 @@ describe('agent scope lifecycle', () => {
    expect(order).toEqual([
      'setup:start',
      'setup:end',
+      'setup:commit',
      'session/created',
      'setup-listener:session/created',
      'agent/created',
--- a/packages/core/agent/src/index.ts
+++ b/packages/core/agent/src/index.ts
@@ -36,6 +36,27 @@ declare module 'cordis' {
  }
 }

+/**
+ * Synchronous finalizer returned by unpublished Agent setup when its
+ * contributions need validation at the exact publication commit point.
+ */
+export interface AgentSetupCommit {
+  /**
+   * Validate and commit the prepared setup immediately before publication.
+   * @throws when publication must roll the unpublished Agent back.
+   */
+  commit(): void
+}
+
+/**
+ * Compose an unpublished Agent scope and optionally return its publication commit.
+ * @param agentCtx - unpublished Agent scope.
+ * @returns an optional synchronous commit invoked after setup awaits settle and immediately before publication.
+ */
+export type AgentSetup = (
+  agentCtx: Context,
+) => AgentSetupCommit | Promise<AgentSetupCommit | void> | void
+
 /**
 * Options for programmatically creating an agent through the registry factory
 * ({@link AgentRegistry.create}). The caller supplies the single live
@@ -48,9 +69,9 @@ export interface CreateAgentOptions {
  readonly sessionId: SessionId
  /**
   * Session creation metadata: validated absolute `cwd`, `parentSession`
-   * fork lineage, the `seedLength` seed boundary, and the `delegationDepth`
-   * recursion budget. Mirrors the
-   * `cwd`/`parentSession`/`seedLength`/`delegationDepth` fields of
+   * fork lineage, the `seedLength` seed boundary, the coarse `origin`
+   * classification, and the `delegationDepth` recursion budget. Mirrors the
+   * `cwd`/`parentSession`/`seedLength`/`origin`/`delegationDepth` fields of
   * {@link CreateSessionOptions.meta} in dsh-session (the internal-only
   * `createdAt`, used when reconstructing a persisted session, is deliberately
   * excluded — a factory caller never sets it). This is durable session data,
@@ -61,6 +82,7 @@ export interface CreateAgentOptions {
    readonly cwd?: string
    readonly parentSession?: SessionId
    readonly seedLength?: number
+    readonly origin?: 'subagent'
    readonly delegationDepth?: number
  }
  /**
@@ -79,17 +101,21 @@ export interface CreateAgentOptions {
   * Creation-time composition of the agent's scoped world. The factory awaits
   * setup after minting `agentCtx` but BEFORE inserting or announcing either
   * the session or agent, so observers can never see a partially configured
-   * world. Everything registered through `agentCtx` (scoped tools, prompt
-   * sections/variables, `restrict()`, listeners, awaited child plugins) exists
-   * before `session/created`, `agent/created`, `agent/session-start`, and the
-   * first prompt assembly. A throw/rejection or owner disposal rolls the scope
-   * back without publishing either id.
+   * world. Setup may return an {@link AgentSetupCommit}; the factory invokes its
+   * synchronous `commit()` after every setup await settles and immediately
+   * before registry publication. This lets mutable provisioning revalidate at
+   * the exact publication boundary. Everything registered through `agentCtx`
+   * (scoped tools, prompt sections/variables, `restrict()`, listeners, awaited
+   * child plugins) exists before `session/created`, `agent/created`,
+   * `agent/session-start`, and the first prompt assembly. A setup
+   * throw/rejection, commit throw, or owner disposal rolls the scope back
+   * without publishing either id.
   *
   * **Setup composes, it never drives**: the callback is trusted same-process
   * code and receives the full scoped context, so this is a contract rather
   * than a runtime restriction. Drive the agent only after creation resolves.
   */
-  readonly setup?: (agentCtx: Context) => Promise<void> | void
+  readonly setup?: AgentSetup
 }

 /**
@@ -107,12 +133,12 @@ export interface ResumeAgentOptions {
   * Resume-time composition of the agent's fresh scoped world. Persistence is
   * loaded first; the factory then mints `agentCtx` and awaits setup while the
   * reconstructed session and agent remain unpublished. The callback has the
-   * same trusted composition-only contract as
-   * {@link CreateAgentOptions.setup}: all registrations exist before either
-   * creation announcement, and rejection or owner disposal rolls the
-   * transaction back without publishing either id.
+   * same trusted composition-only contract and optional synchronous
+   * publication commit as {@link CreateAgentOptions.setup}: all registrations
+   * exist before either creation announcement, and rejection, commit failure,
+   * or owner disposal rolls the transaction back without publishing either id.
   */
-  readonly setup?: (agentCtx: Context) => Promise<void> | void
+  readonly setup?: AgentSetup
 }

 /**
@@ -143,9 +169,9 @@ export interface AgentHandle {
 export interface AgentFactory {
  /**
   * Create a new agent on a caller-supplied session id. Async because creation
-   * awaits unpublished setup, inserts both session and agent, emits their
-   * creation notifications in order, emits `agent/session-start`, and only
-   * then starts the loop. The sequence is
+   * awaits unpublished setup, invokes its optional synchronous commit, inserts
+   * both session and agent, emits their creation notifications in order, emits
+   * `agent/session-start`, and only then starts the loop. The sequence is
   * rollback-covered, but notifications delivered before a later listener
   * failure remain observable; every agent or session creation announcement
   * that began is paired by `agent/disposed` or `session/disposed` during
@@ -164,8 +190,8 @@ export interface AgentFactory {
   * Load a persisted session and resume an agent on it. Async because it awaits
   * both `ctx.sessionPersistence.load` and the optional unpublished setup
   * transaction; must be called after that service exists (consumers inject
-   * `sessionPersistence`). Publication follows the same ordered boundary as
-   * {@link createAgent}.
+   * `sessionPersistence`). Publication follows the same setup-commit and
+   * ordered boundary as {@link createAgent}.
   * @param ownerCtx - caller-bound context that owns load, setup, and the live handle.
   * @param options - persisted identity, configuration, and optional setup.
   * @returns the owned handle after setup, both announcements, and loop start complete.
--- a/packages/core/agent/tests/agent.spec.ts
+++ b/packages/core/agent/tests/agent.spec.ts
@@ -27,7 +27,7 @@ function stubAgent(rawId: string, overrides: Partial<Agent> = {}): Agent {
    ctx: new Context(),
    send: () => {},
    followup: () => {},
-    steer: () => {},
+    steer: () => ({ outcome: Promise.resolve({ status: 'rejected' as const }) }),
    inject: () => {},
    cancel() {},
    whenIdle: () => Promise.resolve(),
--- a/packages/core/session/src/index.ts
+++ b/packages/core/session/src/index.ts
@@ -72,8 +72,7 @@ declare module 'cordis' {
    'session/event'(this: Scoped<Session>, session: Session, event: SessionEvent): void
    /**
     * Awaited parallel durability checkpoint: every listener runs and the
-     * caller awaits all of them, with no waterfall veto. Dispatch through
-     * {@link SessionStore.flush}. Scope-filtered dispatch
+     * caller awaits all of them, with no waterfall veto. Scope-filtered dispatch
     * (`@deepseek-ai/dsh-scope`) reuses the session's owner scope.
     * @param session - the session whose buffered events must reach durable storage.
     * @dshScopeScan unsupported
@@ -118,6 +117,9 @@ function snapshotSessionHeader(id: SessionId, source?: SessionHeader): SessionHe
    && (typeof record.seedLength !== 'number' || !Number.isSafeInteger(record.seedLength) || record.seedLength < 0)) {
    throw new Error('session header seedLength must be a non-negative safe integer')
  }
+  if (record.origin !== undefined && record.origin !== 'subagent') {
+    throw new Error('session header origin must be "subagent"')
+  }
  if (record.delegationDepth !== undefined
    && (typeof record.delegationDepth !== 'number' || !Number.isSafeInteger(record.delegationDepth) || record.delegationDepth < 0)) {
    throw new Error('session header delegationDepth must be a non-negative safe integer')
@@ -793,6 +795,7 @@ export class SessionStore extends Service {
      ...meta?.cwd === undefined ? {} : { cwd: meta.cwd },
      ...meta?.parentSession === undefined ? {} : { parentSession: meta.parentSession },
      ...meta?.seedLength === undefined ? {} : { seedLength: meta.seedLength },
+      ...meta?.origin === undefined ? {} : { origin: meta.origin },
      ...meta?.delegationDepth === undefined ? {} : { delegationDepth: meta.delegationDepth },
    }
    return new Session(sessionId, seed, header)
@@ -924,10 +927,11 @@ export class SessionStore extends Service {
   * raw `ctx.parallel('session/flush', …)` — one owner, one spelling, and the
   * scoped-dispatch invariant can pin it.
   * @param session - the session whose buffered events must reach durable storage.
-   * @returns resolves when every flush listener has settled; after all settle,
-   *   rejects with the first registered listener failure if any listener failed.
+   * @returns whether at least one durability listener participated, after every
+   *   listener has settled successfully.
+   * @throws the first registered listener failure after every listener settles.
   */
-  async flush(session: Session): Promise<void> {
+  async flush(session: Session): Promise<boolean> {
    const { carrier } = this.liveEntryFor(session)
    const callbackArgs: unknown[] = [session]
    const callbacks = collectSessionCallbacks(this.ctx, [carrier, 'session/flush', session])
@@ -943,6 +947,7 @@ export class SessionStore extends Service {
    }))
    const failure = results.find((result): result is PromiseRejectedResult => result.status === 'rejected')
    if (failure !== undefined) throw failure.reason
+    return callbacks.length > 0
  }

  /** Return the exact live entry; detached/prepared objects reject. */
--- a/packages/core/session/src/types.ts
+++ b/packages/core/session/src/types.ts
@@ -57,6 +57,11 @@ export interface SessionHeader {
   * boundary lets resume and replay distinguish parent history from child work.
   */
  readonly seedLength?: number
+  /**
+   * Coarse product classification for a session created as a subagent child.
+   * This is presentation metadata, not proof that the child is continuable.
+   */
+  readonly origin?: 'subagent'
  /**
   * Delegation depth: absent (zero) for a top-level session, parent depth + 1
   * for a subagent child. Persisted so a recursion budget survives restart and
@@ -82,6 +87,7 @@ export interface CreateSessionOptions {
    readonly parentSession?: SessionId
    readonly createdAt?: number
    readonly seedLength?: number
+    readonly origin?: 'subagent'
    readonly delegationDepth?: number
  }
 }
--- a/packages/core/session/tests/scoped.spec.ts
+++ b/packages/core/session/tests/scoped.spec.ts
@@ -80,6 +80,24 @@ describe('session dispatch carriers', () => {
 })

 describe('sessions.flush()', () => {
+  it('allows an ordinary flush with no listeners', async () => {
+    const ctx = await mount()
+    const session = ctx.sessions.create()
+
+    await expect(ctx.sessions.flush(session)).resolves.toBe(false)
+  })
+
+  it('reports a participating listener after it succeeds', async () => {
+    const ctx = await mount()
+    const session = ctx.sessions.create()
+    const flushed: Session[] = []
+    ctx.on('session/flush', current => void flushed.push(current))
+
+    await expect(ctx.sessions.flush(session)).resolves.toBe(true)
+
+    expect(flushed).toEqual([session])
+  })
+
  it('dispatches session/flush with the owning carrier and awaits all listeners', async () => {
    const ctx = await mount()
    const scope = await mintScope(ctx, 'owner')
--- a/packages/core/session/tests/session.spec.ts
+++ b/packages/core/session/tests/session.spec.ts
@@ -1198,15 +1198,16 @@ describe('SessionStore', () => {
    })
  })

-  it('attaches delegationDepth from meta to the header', async () => {
+  it('attaches subagent origin and delegationDepth from meta to the header', async () => {
    const ctx = new Context()
    await ctx.plugin(SessionStore)
    const session = ctx.sessions.create(SessionId('delegated-child'), {
-      meta: { parentSession: SessionId('parent'), delegationDepth: 2 },
+      meta: { parentSession: SessionId('parent'), origin: 'subagent', delegationDepth: 2 },
    })
    expect(session.header).toMatchObject({
      id: 'delegated-child',
      parentSession: 'parent',
+      origin: 'subagent',
      delegationDepth: 2,
    })
  })
@@ -1225,6 +1226,7 @@ describe('SessionStore', () => {
      { meta: { seedLength: '1' }, error: /seedLength must be a non-negative safe integer/ },
      { meta: { seedLength: 0.5 }, error: /seedLength must be a non-negative safe integer/ },
      { meta: { seedLength: -1 }, error: /seedLength must be a non-negative safe integer/ },
+      { meta: { origin: 'fork' }, error: /origin must be "subagent"/ },
      { meta: { delegationDepth: '1' }, error: /delegationDepth must be a non-negative safe integer/ },
      { meta: { delegationDepth: 0.5 }, error: /delegationDepth must be a non-negative safe integer/ },
      { meta: { delegationDepth: -1 }, error: /delegationDepth must be a non-negative safe integer/ },
--- a/packages/core/tools/README.i18n.yaml
+++ b/packages/core/tools/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/tools/README.md
-README.md: 15fc5839a3b0e3fa2d20c5a9cc50577e9807ffda
-README.zh.md: 8547ee4a796dcd93945dfa40373c14c10d7d0c8a
+README.md: 80ea3cc93437d48a7ea0ffba0ff4d2ef2407755f
+README.zh.md: 1f0791c5df7afd4a3479afdd827c4fc148cf8883
--- a/packages/core/tools/README.md
+++ b/packages/core/tools/README.md
@@ -43,7 +43,7 @@ The live registry pipeline has three transformable waterfalls, then the definiti
 - `ToolExecutionInput` — the caller-supplied call description: `{ callId, name, arguments, signal, agent?, parent? }`; `signal` is required and readonly, callers may pass an enclosing execution's opaque token as `parent`, and callers never choose the new execution's own token.
 - `ToolExecutionToken` — a fresh branded `Symbol` assigned by the registry. It supports equality correlation only and never crosses a model, log, or worker boundary.
 - `ToolExecution` — the readonly pipeline view: immutable `{ token, callId, name, arguments, signal, agent?, parent? }`; the registry separately retains and re-fuses the original caller signal. `ToolDispatchExecution` is the `tools/execute`-only view whose required signal is mutable, so a wrapper may replace and restore it but cannot delete it. A nested call's `parent` is a `ToolExecutionToken`, not an execution object.
- `ToolRunContext` — the execution passed to a tool body, extending `ToolExecution` with `deferContext(context)`. Composite tools use it to ferry context produced by nested dispatches to the outer result even when the tool later throws or cancellation wins; it never injects immediately.
+- `ToolRunContext` — the execution passed to a tool body, extending `ToolExecution` with `deferContext(context)`. It defers one context until the tool's final result reaches the loop — typically a nested-dispatch context ferried by a composite tool, or a fresh plugin-sourced instruction minted by a leaf tool (`tool-goal`'s wrap-up) — even when the tool later throws or cancellation wins; it never injects immediately.
 - `ToolExecutionResult` — discriminated execution-local outcome. Success is `{ isError:false, value:JsonValue, content, meta?, additionalContexts? }`; failure is `{ isError:true, error:{ message, info? }, content, meta?, additionalContexts? }` and has no value. Call identity stays on the immutable `ToolExecution`. The registry snapshots, validates, and freezes the canonical value before rendering, then materializes the durable presentation fields before final observation. `ToolFailure.info` carries an internal `{ name, code }` for a `HarnessError`; `additionalContexts` preserves every deferred or post-execute identified `UserMessage` for the loop's post-result FIFO.
 - `PreToolDecision` — `{kind:'allow'}` | `{kind:'deny', reason}` | `{kind:'ask', reason?}`. Input rewrite is deliberately not offered; `ask` is serviced by [`ctx.approval`](../../ui/user-approval/README.md) when mounted and otherwise degrades to deny.
 - `PostToolDecision` — accept may replace `content` or `value`, never both, and may attach `additionalContexts`; block turns feedback into a valueless failure. Content replacement preserves the canonical value and metadata. Value replacement is revalidated and rerenders content/metadata. Accept preserves tool-deferred contexts before decision contexts; block discards tool-deferred contexts and exposes only contexts explicitly supplied by the blocking decision.
--- a/packages/core/tools/README.zh.md
+++ b/packages/core/tools/README.zh.md
@@ -43,7 +43,7 @@ tools:
 - `ToolExecutionInput`：调用方提供的调用描述：`{ callId, name, arguments, signal, agent?, parent? }`；`signal` 必填且只读，调用方可以将外层执行的不透明 token 作为 `parent` 传入，但绝不能选择新执行自身的 token。
 - `ToolExecutionToken`：注册表分配的全新带品牌 `Symbol`。它只支持通过相等性进行关联，绝不会跨越模型、日志或 worker 边界。
 - `ToolExecution`：只读流水线视图：不可变的 `{ token, callId, name, arguments, signal, agent?, parent? }`；注册表会另行保留并重新融合调用方的原始信号。`ToolDispatchExecution` 是仅供 `tools/execute` 使用的视图，其必填信号可变，因此包装层可以替换并还原它，但不能删除它。嵌套调用的 `parent` 是 `ToolExecutionToken`，而不是执行对象。
- `ToolRunContext`：传给工具主体的执行上下文，在 `ToolExecution` 基础上增加 `deferContext(context)`。组合工具借此把嵌套分发产生的上下文传递到外层结果，即使工具后来抛出或取消胜出也不例外；该方法绝不会立即注入上下文。
+- `ToolRunContext`：传给工具主体的执行上下文，在 `ToolExecution` 基础上增加 `deferContext(context)`。它把一条上下文推迟到该工具的最终结果抵达循环时——通常是组合工具转运的嵌套分发上下文，也可以是叶子工具铸造的全新插件来源指令（如 `tool-goal` 的收尾注入）——即使工具后来抛出或取消胜出也不例外；该方法绝不会立即注入上下文。
 - `ToolExecutionResult`：可辨识的执行局部结果。成功形态为 `{ isError:false, value:JsonValue, content, meta?, additionalContexts? }`；失败形态为 `{ isError:true, error:{ message, info? }, content, meta?, additionalContexts? }`，且不含值。调用身份保留在不可变的 `ToolExecution` 上。注册表会在呈现前快照、验证并冻结规范值，随后在最终观测前实体化持久呈现字段。`ToolFailure.info` 携带内部的 `{ name, code }`，用于表示 `HarnessError`；`additionalContexts` 会保留每个通过延迟或 post-execute 加入且带标识的 `UserMessage`，供循环在结果后按 FIFO 顺序处理。
 - `PreToolDecision`：`{kind:'allow'}` | `{kind:'deny', reason}` | `{kind:'ask', reason?}`。该类型有意不提供输入改写；`ask` 在挂载 [`ctx.approval`](../../ui/user-approval/README.md) 时由它处理，否则退化为拒绝。
 - `PostToolDecision`：接受决定可以替换 `content` 或 `value`（不能同时替换），并可附加 `additionalContexts`；阻止决定会把反馈变成无值失败。替换内容会保留规范值和元数据。替换值会重新验证，并重新呈现内容／元数据。接受决定会先保留工具延迟的上下文，再附加决定上下文；阻止决定会丢弃工具延迟的上下文，只公开阻止决定显式提供的上下文。
--- a/packages/core/tools/src/index.ts
+++ b/packages/core/tools/src/index.ts
@@ -344,15 +344,18 @@ export interface ToolDispatchExecution extends Omit<ToolExecution, 'signal'> {

 /**
 * Runtime context handed to a tool implementation after the registry has
- * accepted a {@link ToolExecution}. A composite tool uses
- * {@link deferContext} to ferry context produced by nested dispatches back to
- * the outer result; the loop appends it only after the outer `tool/result`.
+ * accepted a {@link ToolExecution}. {@link deferContext} attaches context to
+ * this execution's own result — a composite tool ferries nested-dispatch
+ * context back to the outer result, and a leaf tool may mint a fresh
+ * plugin-sourced instruction; the loop appends it only after the
+ * `tool/result`.
 */
 export interface ToolRunContext extends ToolExecution {
  /**
-   * Defer one nested-dispatch context until this tool's final result reaches
-   * the agent loop. Contexts retain their individual source and metadata and
-   * are emitted in call order.
+   * Defer one context — typically a nested-dispatch context ferried by a
+   * composite tool, or a fresh plugin-sourced instruction — until this tool's
+   * final result reaches the agent loop. Contexts retain their individual
+   * source and metadata and are emitted in call order.
   */
  deferContext(context: UserMessage): void
  /**
--- a/packages/core/tools/tests/gen-tool-catalog.spec.ts
+++ b/packages/core/tools/tests/gen-tool-catalog.spec.ts
@@ -23,7 +23,7 @@ describe('gen-tool-catalog collectToolCatalog', () => {
  it('boots every shipped tool package and harvests its model-facing schemas', async () => {
    const catalog = await collectToolCatalog()
    const names = catalog.flatMap(entry => entry.schemas.map(s => s.name)).sort()
-    expect(names).toEqual(['ask_user_question', 'bash', 'bash', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'create_goal', 'edit', 'exit_plan_mode', 'get_goal', 'glob', 'grep', 'lsp', 'ralph', 'read', 'run_code', 'session_event_read', 'session_event_search', 'session_event_trace', 'session_search', 'session_trace', 'skill', 'str_replace_editor', 'subagent', 'task_kill', 'task_list', 'task_output', 'terminal_close', 'terminal_list', 'terminal_open', 'terminal_read', 'terminal_send', 'terminal_signal', 'todo_write', 'update_goal', 'web_fetch', 'web_search', 'workflow', 'write'])
+    expect(names).toEqual(['ask_user_question', 'bash', 'bash', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'create_goal', 'edit', 'exit_plan_mode', 'get_goal', 'glob', 'grep', 'list_agents', 'lsp', 'ralph', 'read', 'report', 'run_code', 'send_message', 'session_event_read', 'session_event_search', 'session_event_trace', 'session_search', 'session_trace', 'skill', 'str_replace_editor', 'subagent', 'task_kill', 'task_list', 'task_output', 'terminal_close', 'terminal_list', 'terminal_open', 'terminal_read', 'terminal_send', 'terminal_signal', 'todo_write', 'update_goal', 'web_fetch', 'web_search', 'workflow', 'write'])
    // Every tool carries a JSON-Schema `parameters` object (what the model sees).
    for (const entry of catalog) {
      for (const schema of entry.schemas) {
@@ -43,10 +43,15 @@ describe('gen-tool-catalog collectToolCatalog', () => {
    expect(status?.enum).toEqual(['pending', 'in_progress', 'completed'])
  })

-  it('attributes each package with a source pointer that names its index', async () => {
+  it('attributes each harvested tool with its registering plugin source', async () => {
    const catalog = await collectToolCatalog()
    const bash = catalog.find(entry => entry.pkg === '@deepseek-ai/dsh-tool-bash')
-    expect(bash?.source).toBe('packages/bash/tool-bash/src/index.ts')
+    expect(bash?.sources.bash).toBe('packages/bash/tool-bash/src/index.ts')
+    const control = catalog.find(entry => entry.pkg === '@deepseek-ai/dsh-tool-subagent-control')
+    expect(control?.sources).toEqual({
+      list_agents: 'packages/subagent/tool-subagent-control/src/list-agents.ts',
+      send_message: 'packages/subagent/tool-subagent-control/src/index.ts',
+    })
  })

  it('harvests search tools without depending on the generator process PATH', async () => {
@@ -90,7 +95,7 @@ describe('gen-tool-catalog render', () => {
    const catalog: ToolCatalog = [
      {
        pkg: '@deepseek-ai/dsh-tool-demo',
-        source: 'packages/demo/tool-demo/src/index.ts',
+        sources: { demo: 'packages/demo/tool-demo/src/index.ts' },
        requires: ['ctx.tools'],
        writes: ['tool/result'],
        schemas: [{ name: 'demo', description: 'A demo tool.', parameters: { type: 'object', properties: {} } }],