子代理能否运行在与父代理不同的 agent preset 上？

[RACErace]

I've been reading packages/preset and the subagent drivers, and I can't find any supported way to make a delegated child run on a preset other than its parent's. Before treating that as a gap, I'd like to check whether it's deliberate and whether I'm missing a seam.

All line references are against master @ c291e79 (2026-09-10); I also verified the behaviour against the published @deepseek-ai/dsh-agent-presets@0.1.5-rc.2.

What I found

1. composeFrom has no preset id.

packages/preset/agent-presets/src/index.ts (implementation in lib/types/index.js):

composeFrom(agentCtx, parentCtx) {
    const agentKey = scopeOf(agentCtx);
    const standing = standingMountFor(parentCtx);   // parent's standing mount, always
    if (standing === undefined) return undefined;
    this.bindings.set(agentKey, bindScopeParent(agentKey, standing.key));
    return standing.presetId;
}

The signature is (agentCtx, parentCtx) — there is no parameter through which a different preset id could arrive. mount(agentCtx, id) is the one that takes an id.

2. Children go through exactly that call.

packages/subagent/subagent/src/child-agent.ts:

childCtx.get('agentPresets')?.composeFrom(childCtx, parent.ctx)

and the preset is deliberately read from the parent's live scope chain rather than its durable header. The matching tests (packages/subagent/subagent-in-process-driver/tests/preset-inheritance.spec.ts) assert this inheritance directly, including a case where the parent was recomposed to a different preset while blank and the child follows it.

3. The delegate tool exposes no preset field.

packages/subagent/tool-subagent — no preset parameter. So there is no model-facing path either.

Two adjacent things that made me pause

• packages/subagent/subagent-in-process-driver/tests/fixtures/presets/ contains coding and reviewing (with matching preset_only / reviewing_only tools) and tests/preset-inheritance.spec.ts. The fixture names suggest per-child preset assignment was at least considered or prototyped. The archived preset-tool-filter-DSL note points in the same direction, though I couldn't reach that file (404) so I may be reading too much into fixture names.
• The child-local composition controls that do exist are persona, toolFilter, and maxDepth (2026-07-12-subagent-persona-tool-filter-and-depth.md). These customise a child but cannot switch its preset — they filter or overlay the inherited composition.

The constraint I keep running into

agentPresets/select exists as a remote method and select(agent, agentPreset) as a service method, but swap() refuses once the session has produced anything:

if (boundary !== undefined && (boundary.openTurnStartSeq !== null || boundary.lastTurn > 0)) {
    throw new RemoteError('agent-preset/locked', ...)
}

which is the documented blank-session contract. And the in-process drivers compose their children inside a synchronous setup, while mount() is async — so composing a child from a named preset does not obviously fit the window the drivers use.

CreateAgentOptions.agentPreset does exist (packages/core/agent/src/types.ts) and the child header records agentPreset, but that field is set by whoever calls ctx.agents.create — not by the tool caller.

The use case I'm trying to reach

I want a parent to delegate to specialist children that carry their own skill sets — e.g. a Unity-expert child and a Blender-expert child — without a human hand-orchestrating several top-level sessions. Today the workaround is manual: open a separate top-level session per preset from the GUI and pass interfaces between them.

Questions

1. Is preset inheritance for children a deliberate hard boundary, or simply the only path today?
2. If deliberate: is the reasoning the same "a child must not run a different generation of the composition than its parent's history was produced under" argument recorded in composeFrom's doc comment, or is there something stronger — trust, or composition semantics?
3. Is there a seam I've missed (provider config, SDK, an existing per-child composition row) that already permits this?
4. If this is worth supporting, which shape would upstream prefer?
   • an optional preset field on the subagent tool plus a new provider capability flag (alongside persona / toolFilter / depthLimit), or
   • composeOneChild mounting an explicitly requested preset instead of composeFrom
     The second looks smaller, but it has to solve the sync-setup-vs-async-mount mismatch, which makes me suspect the first is the more honest shape.

I'm happy to prototype whichever direction you'd accept. I may well be missing repo context, so a pointer would be just as useful as an answer.

[RACErace]

本文是上方正文的中文版本，内容一致，仅为方便中文读者。英文原文如有歧义，以英文版为准。

我最近在读 packages/preset 和子代理驱动层，但找不到任何受支持的方式，让被委派的子代理运行在与父代理不同的预设上。在把这件事当成能力缺失之前，我想先确认它究竟是刻意为之，还是我漏掉了某个接缝。

以下行号引用均基于 master @ c291e79（2026-09-10）；我也针对已发布的 @deepseek-ai/dsh-agent-presets@0.1.5-rc.2 实测过该行为。

我查到的

1. composeFrom 没有预设 id 参数。

packages/preset/agent-presets/src/index.ts（实现位于 lib/types/index.js）：

composeFrom(agentCtx, parentCtx) {
    const agentKey = scopeOf(agentCtx);
    const standing = standingMountFor(parentCtx);   // 永远是父代理的 standing mount
    if (standing === undefined) return undefined;
    this.bindings.set(agentKey, bindScopeParent(agentKey, standing.key));
    return standing.presetId;
}

签名是 (agentCtx, parentCtx)——没有任何参数可以让一个不同的预设 id 传进来。接受 id 的是 mount(agentCtx, id)。

2. 子代理走的恰恰就是这个调用。

packages/subagent/subagent/src/child-agent.ts：

childCtx.get('agentPresets')?.composeFrom(childCtx, parent.ctx)

而且预设是刻意从父代理的实时（live） scope 链读取，而非从它的持久化 header 读。对应的测试（packages/subagent/subagent-in-process-driver/tests/preset-inheritance.spec.ts）直接断言了这种继承关系，其中一例是父代理在空白期被 recompose 到另一个预设后、子代理跟随它。

3. delegate 工具不暴露预设字段。

packages/subagent/tool-subagent——没有 preset 参数。所以模型侧也没有任何路径。

两个让我停顿的旁证

• packages/subagent/subagent-in-process-driver/tests/fixtures/presets/ 下有 coding 和 reviewing（各自配套 preset_only / reviewing_only 工具）以及 tests/preset-inheritance.spec.ts。这些夹具命名暗示"按子代理指派预设"至少被考虑过、或做过原型。那份归档的 preset-tool-filter-DSL 笔记指向同一方向，不过我没能取到那个文件（404），所以也可能是我从夹具名过度推断了。
• 目前确实存在的子代理级组合控制是 persona、toolFilter 和 maxDepth（见 2026-07-12-subagent-persona-tool-filter-and-depth.md）。它们能定制一个子代理，但无法切换它的预设——它们只是在继承来的组合上做过滤或覆盖。

我一直撞上的那个约束

agentPresets/select 作为远端方法存在，select(agent, agentPreset) 作为服务方法也存在，但 swap() 在会话已经产生任何东西之后就拒绝：

if (boundary !== undefined && (boundary.openTurnStartSeq !== null || boundary.lastTurn > 0)) {
    throw new RemoteError('agent-preset/locked', ...)
}

这就是文档化的"空白会话"契约。而 in-process 驱动是在同步的 setup 里组合子代理的，mount() 却是异步的——所以"用某个具名预设去组合子代理"这件事，并不能自然地塞进驱动所用的那个窗口。

CreateAgentOptions.agentPreset 确实存在（packages/core/agent/src/types.ts），子代理 header 也会记录 agentPreset，但那个字段是由调用 ctx.agents.create 的一方设置的——不是由工具调用方设置。

我想达成的用例

我希望父代理能把任务委派给自带技能集的专家子代理——例如一个 Unity 专家子代理和一个 Blender 专家子代理——而不需要人工去手工编排多个顶层会话。目前只能绕行：从 GUI 为每个预设单独开一个顶层会话，再在它们之间人工传递接口。

我的问题

1. 子代理的预设继承是一条刻意的硬边界，还是说它只是目前唯一可走的路径？

2. 如果是有意为之：理由是否与 composeFrom 文档注释中记录的那条"子代理不应运行与其父代理历史产出时不同代际的组合"相同，还是有更强的理由——比如信任模型，或组合语义本身？

3. 有没有我漏掉的接缝（provider 配置、SDK、某个已存在的子代理级组合行）其实已经允许这样做？

4. 如果这件事值得支持，上游更倾向哪种形态？

   • 在 subagent 工具上加一个可选的 preset 字段，并新增一个 provider 能力位（与 persona / toolFilter / depthLimit 并列）；或
   • 让 composeOneChild 在显式请求预设时改用 mount，而不是 composeFrom。

   第二种看起来改动更小，但它必须解决"同步 setup vs 异步 mount"这个错配——这也让我怀疑第一种才是更诚实的形态。

无论你们接受哪个方向，我都乐意去做原型。我完全可能漏了仓库里的上下文，所以哪怕只是指个路，和给出答案一样有用。

[PerryLink]

Verified against master @ c291e79 — the same commit you cite — so every reference below is load-bearing.

Q1 — deliberate, and currently the only path. Inheritance is not just what composeFrom happens to do; the doc comment states the design outright (packages/preset/agent-presets/src/index.ts): it is a bind, not a mount — the child joins the parent's exact standing instance ("the same plugin objects, the same tool registrations, the same prompt sections"). Re-resolving by id would hand the child a different generation than its parent's history was produced under. It is also the only composition step that fits the child-creation window: composeFrom "reads no roster, mounts nothing, and touches no file" — synchronous, with no failure mode — while mount() is async, and both in-process providers compose children inside a synchronous setup (packages/subagent/subagent-in-process-driver/src/index.ts). Two further structural walls, for the record:

• The binding authority is private to the roster (the mount comment: "held privately so nothing outside this roster can move a composed agent to another preset"). Any per-child preset selection has to pass through that authority, not around it.
• Child history reconstruction depends on inheritance: childSessionMeta (packages/subagent/subagent/src/child-agent.ts) records the preset read from the parent's live scope precisely so a cold read rebuilds the child under the toolset it actually had. A differently-composed child needs its own preset in the durable header — and the field already exists (CreateAgentOptions.agentPreset, packages/core/agent/src/index.ts:84); the delegation path just never sets it.

Q2 — the documented reason is exactly the one you quoted, and I found no stronger one in the tree (no trust-model note anywhere in the code). The reinforcements are structural rather than trust-based: the private binding authority and the sync setup window above, plus one you didn't list — preset services must sit behind isolate realms (packages/preset/agent-presets/src/invariant.ts and the roster's own docs). A child on a different preset is a second standing composition inside one agent tree: a second realm boundary in the same lineage. That's feasible — standings already coexist in one runtime — but it is a real semantic crossing, which is why it deserves a deliberate seam rather than a call-site hack.

Q3 — no in-tree seam selects a preset per delegation. The nearest thing, which you didn't mention, is the out-of-process backends (subagent-acp, subagent-dsh-sdk). Their contract is "an out-of-process child starts fresh — no parent conversation crosses the process boundary", and they advertise NO_START_CAPABILITIES (packages/subagent/subagent/src/out-of-process.ts). The seam does not pin the composition of that external session — it starts fresh by contract, and how the external session is composed (including which preset it is mounted on) is the backend's business. So the supported shape for "specialist child" today is: register an out-of-process backend whose target session runs the specialist preset. The costs are exactly the advertised capability list — no seed, no persona/toolFilter/agentOptions/outputSchema/maxDepth across the boundary — and the preset is a property of the backend, not something the model-facing caller picks per call. In other words, the formalized version of your manual top-level-session workaround.

(Your fixture reading is also right: coding/reviewing plus preset_only/reviewing_only tools are exactly the shape per-preset children would take, though today they only serve the inheritance/recompose assertions in preset-inheritance.spec.ts.)

Q4 — between your two shapes, (a) is the more honest one, and I'd add two constraints. One naming note first: at this commit the function is applyChildComposition, not composeOneChild (packages/subagent/subagent/src/child-agent.ts). Shape (b) hits three walls: the sync-setup/async-mount mismatch you already spotted; the private binding authority (the call site cannot do this work — the roster must); and fork-seed semantics (continuing parent-produced history under a different composition is precisely the contradiction the composeFrom doc comment exists to prevent). Shape (a) fits the existing vocabulary — the provider capability flags already gate per-child start features, and NO_START_CAPABILITIES shows the pattern for backends that can't honor them. Suggested shape:

• optional preset field on the subagent tool + a preset capability bit on the in-process provider;
• constrain it to unseeded spawns, mirroring the blank-session recompose contract, so the generation argument stays intact for forks;
• resolve the requested preset to its standing mount in the spawn path before create() — that's where the async work belongs, outside setup — and fail publication with agent-preset/not-found / agent-preset/locked semantics;
• record the child's actual preset in the durable header through the existing CreateAgentOptions.agentPreset.

I'd be happy to prototype (a) behind the capability flag if a maintainer blesses the direction.

---

中文摘要：① 子代理继承父预设是刻意设计（bind 而非 mount，子代加入父代的同一 standing 实例），也是当前唯一路径；② 代码里记录的理由就是你在 composeFrom 注释中引用的"代际一致性"，没有更强的信任模型表述——额外的结构性约束是：binding 权限私有于 roster、同步 setup 窗口、以及预设服务必须位于 isolate realm 之后（跨预设子代 = 同一 agent 树内的第二道 realm 边界）；③ 树内没有按次选择预设的接缝，但你漏掉的相邻接缝是 out-of-process 后端（ACP/SDK）：契约上"fresh start、零继承"，外部会话的组成（包括挂载哪个预设）由后端自行决定——这就是"专家子代理"的现行支持形态（预设是后端的属性，模型侧调用方不能按次选）；④ 两个形态中 (a)（工具预设字段 + 提供者能力位）更诚实：(b) 撞上三堵墙——同步 setup/异步 mount 错配、binding 私有权限、fork 种子语义矛盾。建议加两条约束：仅限未播种的 spawn（镜像空白会话 recompose 契约）；预设解析放在 create() 之前的 spawn 路径而非 setup 内。若维护者认可，我可基于能力位做 (a) 的原型。

[RACErace]

Thanks — this is exactly the kind of answer I was hoping for, and the correction lands.

Correction accepted

applyChildComposition, not composeOneChild — my original post named it wrong. I had the call site in front of me and still wrote the wrong identifier, which is a good reminder that the name I typed was the one I expected to find rather than the one in the file.

I built the thing your constraints describe

After reading ctx.agentPresets in docs/subsystems/core.zh.md I stopped trying to redirect the delegate path and had a plugin create its own child instead. Checking it against your four constraints, it happens to land on all of them:

// resolved OUTSIDE setup, before create()
const requested = (await ctx.agentPresets.list()).find(p => p.id === args.preset)

const handle = await ctx.agents.create({
  sessionId, parentAgent: parent, signal,
  agentOptions: resolveChildAgentOptions(parent, undefined, childDepth),
  meta: {
    origin: 'subagent',
    delegationDepth: childDepth,
    agentPreset: requested.id,        // durable, so a cold read rebuilds the right toolset
    parentSession: parent.session.header.id,
  },
  setup: async (agentCtx) => { await ctx.agentPresets.mount(agentCtx, requested.id) },
})
// then: followup one turn → await child.whenIdle() → finalAssistantOutput → dispose

• unseeded only — no seed is ever passed;
• the preset is resolved before create(), not inside setup;
• it goes through the roster's authority (mount is the roster's own method) rather than around the private binding — your point that "the call site cannot do this work" is right, and this is why the call site has to ask the roster instead;
• the child's actual preset is recorded via meta.agentPreset.

It also reuses the exported helpers (delegationDepthOf, resolveChildAgentOptions, finalAssistantOutput, assertSubagentMaxDepth) rather than reimplementing the driver's logic, so it stays close to the real thing.

One incidental data point for your meta.agentPreset note: the field sits inside meta at line 84 of packages/core/agent/src/index.ts, and the surrounding doc comment enumerates the meta fields as cwd/parentSession/isSeeded/origin/delegationDepth/agentPreset — so meta.agentPreset is the validated path. I only mention it because your wording ("CreateAgentOptions.agentPreset") reads as top-level, and someone implementing shape (a) from your sketch could plausibly wire it one level too high.

Where this differs from shape (a), honestly

It is not a substitute for (a), for two reasons you'd be right to press on:

1. It is a separate tool, so it only helps callers who choose it. Existing subagent calls still inherit, and nothing negotiates the capability.
2. It does cross the realm boundary you raised — a second standing composition inside one agent tree, which is exactly the semantic crossing you said deserves a deliberate seam. This is a call-site-shaped solution to a seam that ought to be owned by the platform, and I'd rather see (a) land.

The one place I'd push back slightly

You list the sync-setup/async-mount mismatch as a wall for shape (b). Agreed for the drivers — but it isn't a property of the composition model, only of that one synchronous setup callback: AgentSetup is explicitly allowed to return a promise and the factory awaits it before publication. So the window "after agentCtx is minted, before the first prompt is assembled" is genuinely async-capable; the drivers just don't use it that way. That's the crack I drove this through, and it's also why I think your option of resolving before create() is the better shape — it keeps the async work where it already belongs instead of widening what setup is used for.

Out-of-process, for the record

Your Q3 answer is the most useful thing in this thread for me. Worth noting it wasn't available in my deployment: neither subagent-acp nor subagent-dsh-sdk is installed, so "register a backend whose target session runs the specialist preset" was not reachable — there was no supported seam present, which is what pushed me toward building one.

If a maintainer blesses (a), I'm happy to hand this over as a reference implementation, or to drop it entirely if the conclusion is that cross-preset children shouldn't be reachable without the capability bit. Either outcome is a better place to land than where this started.

[RACErace]

Follow-up after reading docs/subsystems/core.zh.md (ctx.agentPresets) and packages/preset/*: I now believe the answer is that there is no hook to redirect an existing delegated child, but the composition model does support the underlying goal, so I built it a different way and can report what worked.

Why redirecting a live child is not available

Three facts, all verifiable against the tree:

1. composeFrom(agentCtx, parentCtx) takes no preset id — it reads the parent's standing mount.
2. The child's scope key is bound during the driver's setup, and bindScopeParent documents that "a key that already has a parent throws: there is no open re-link path".
3. observeRun emits subagent/start after drivePublishedRun has already called child.followup(...), so by the time any listener sees the event the child's first turn has begun — and agentPresets/select then refuses with agent-preset/locked.

The subagent subsystem exposes only four events (subagent/start, subagent/end, subagent/provider-added, subagent/provider-removed), none of them a pre-start waterfall, so there is no interception point between composition and the first turn either.

What does work

mount(agentCtx, id) is documented to be called from the agent factory's setup, which runs after agentCtx is minted but before the session/agent are published and before the first prompt is assembled. The in-process driver cannot use that window for a named preset because its setup is synchronous while mount is async — but an agent created by a plugin can, because AgentSetup may return a promise and the factory awaits it.

So instead of redirecting the delegate path, I registered a separate delegation tool that creates its own child:

const handle = await ctx.agents.create({
  sessionId, parentAgent: parent, signal,
  agentOptions: resolveChildAgentOptions(parent, undefined, childDepth),
  meta: { origin: 'subagent', delegationDepth: childDepth, agentPreset: requested.id, ... },
  setup: async (agentCtx) => { await ctx.agentPresets.mount(agentCtx, requested.id) },
})

then followup one turn, await child.whenIdle(), read the final answer with the exported finalAssistantOutput, and dispose. Reusing the public helpers (delegationDepthOf, resolveChildAgentOptions, finalAssistantOutput, assertSubagentMaxDepth) kept it close to the real driver instead of reimplementing its logic.

It works in a normal production profile: the child's first request already carries the named preset's tools, skills, and prompt sections. Worth noting for anyone attempting the same: recording meta.agentPreset matters, since a child's history otherwise reads back under the deployment default and rebuilds its turns under a tool set it never had.

Two things I could not resolve from the docs

• Whether an optional per-child preset on the delegation path is something upstream would want at all, or whether the current single-path inheritance is deliberate precisely because it is unbypassable. If it is the latter, a one-line note in the composeFrom docs saying "a child intentionally cannot be composed from a different preset" would have saved me the whole investigation.
• If it were wanted, the smaller change still looks like composeOneChild mounting an explicitly requested preset — but that has to solve the sync-setup-vs-async-mount mismatch, which is exactly the constraint that makes "create the child yourself" the easier route from outside.

Happy to share the plugin if it is useful as a reference, or to drop it if this is intended to be impossible.

[PerryLink]

Both corrections verified against the same checkout (c291e79) — you're right on both, and thank you for catching them:

1. meta.agentPreset — correct. The field sits inside meta (packages/core/agent/src/index.ts:78-85), and the doc comment enumerates it as cwd/parentSession/isSeeded/origin/delegationDepth/agentPreset. My "CreateAgentOptions.agentPreset" wording reads as top-level and could have sent someone wiring shape (a) one level too high. Retracted.

2. sync-setup vs async-mount — also correct, and it narrows my earlier claim. AgentSetup allows Promise<AgentSetupCommit | void> (packages/core/agent/src/index.ts:50-53), and the factory awaits setup after minting agentCtx but before publishing the session/agent (:100-105). So the mismatch is a property of the in-process drivers' synchronous setup usage, not of the composition model. The wall that remains for shape (b) is the private binding authority — the call site still cannot do the work itself — which is why your structure (resolve outside, mount through the roster, record meta.agentPreset) is exactly the shape a capability-gated (a) should take.

On the two items you couldn't resolve from the docs:

• Upstream intent: no maintainer signal in this thread so far. If the conclusion is "deliberately unbypassable", the one-line composeFrom doc note you propose is a cheap, valuable improvement — happy to open that docs PR myself, or hand it to you.
• If it is wanted, I still think resolving the preset before create() in the spawn path (your plugin's structure) is the more honest seam than widening what setup is used for.

Your plugin is a solid reference implementation for shape (a); if a maintainer blesses the direction, any PR could start from working code instead of zero. Thanks for the push-back on both points — the record is more accurate now.

[RACErace]

Both takeaways registered, and no further back-and-forth needed on either:

• meta.agentPreset — understood, and agreed that the cost of my earlier wording was real: it would have put the field one level too high.
• Sync-setup vs async-mount — agreed it's a property of how the in-process drivers call setup, not of the composition model, so the remaining wall for shape (b) is the private binding authority alone.

On the docs PR

Please don't wait on us, and don't hold the offer open. We're not able to submit PRs or issues here, so the composeFrom note won't come from this side. That says nothing about whether it's worth having — if you or a maintainer judges the one-liner a net win, treat it as entirely yours to decide and land. Same for shape (a): the direction is yours to take or drop without reference to this thread.

What would still be useful, whoever acts on it, is only the shape of the fix, since the investigation settled some of it already:

1. Resolve the preset before create(), in the spawn path — not inside setup. setup is already awaited and is the right window for composition, but the drivers' synchronous use of it is what made the mismatch look like a model constraint.
2. Mount through the roster (AgentPresets.mount) rather than re-binding the child's scope. The binding authority is deliberately private, and asking the roster to do the work is how a call site respects that instead of working around it.
3. Record the child's real preset in its durable header (meta.agentPreset), or a cold read rebuilds the child's turns under the deployment default.
4. Gate it on an explicit capability bit, constrained to unseeded spawns, so the generation argument that composeFrom's doc comment protects stays intact for forks.

That ordering is what makes shape (a) honest rather than a call-site hack; the rest is your call.

Thanks for engaging with the push-back seriously — the thread is a better record for it, and I'll leave it there.