Agent Teams: let spawnTeammate pass agentOptions (provider/model/persona/toolFilter) through to startContinuable

[joel-young]

Motivation

Every teammate in an Agent Team currently inherits the Lead's model and tool surface. Real deployments (e.g. a fixed AI video pipeline: script → storyboard → frame generation → render → edit) need:

• per-member models — the Lead on a strong cloud model (CAS/wait/arbitration is a discipline-heavy job), content members on local models (cost and privacy);
• per-role toolsets — the frame-generation member only needs API + file writes, the editor needs ffmpeg, the reviewer is read-only.

Current state: the mechanism is complete, one wire is missing at the team layer

The subagent layer already supports per-child customization end to end: providers declare the agentOptions / persona / toolFilter capabilities, and startContinuable resolves request.agentOptions into the descriptor's agentProvider / agentModel / agentReasoningEffort (plus persona / toolFilter), which the continuation owner consumes.

But dsh-experimental-agent-team's roster.spawn hardcodes the call:

started = await this.ctx.subagents.startContinuable({
  childId,
  provider: request.provider,   // label only on the continuable path
  label: description,
  request: {
    prompt: request.prompt,
    parent: root,               // ← no agentOptions / persona / toolFilter
  },
  signal,
});

Verified byte-identical across 0.1.7-rc.1, 0.2.0-rc.2, and 0.2.1-alpha.1 (occurrences of agentOptions / persona / toolFilter in the package: 0).

PoC evidence (0.1.7-rc.1, standalone headless process)

• Registered a custom provider (all capabilities declared, wrapping the exported startInProcessRun and stamping agentOptions { provider, model }), then called spawnTeammate({ provider: "poc-spawn", ... }): the member record shows provider == "poc-spawn", but the provider's start() is never invoked (on the continuable path the child is materialized by the continuation owner), and member.model is inherited from the Lead.
• Everything else works: plugin code holding the Lead's live Agent as the caller can perform claim / reassign / spawn / sendMessage / waitForChange — the authority model is fine; only this parameter is missing.

Proposal

Minimal change: accept optional agentOptions / persona / toolFilter on the spawnTeammate request and pass them through to startContinuable in roster.spawn (and persist them on the member record — the roster already has a model display field). Alternatively, expose a per-role agentOptions table in the team service config.

That single wire lets a team run "Lead on cloud, members on local models, least privilege per role", which makes Agent Teams a solid execution substrate for fixed pipelines (task-board DAG + code-side dispatcher).

(We currently carry a plugin-side workaround — patching the one roster.spawn call site. Under the experimental contract we must re-apply it on every upgrade; we would love to see this land upstream.)

---

Environment: dsh 0.1.7-rc.1 (compared against the published 0.2.0-rc.2 and 0.2.1-alpha.1 npm artifacts) · Linux · reproducible PoC scripts available on request.

[joel-young]

Related work — two complementary layers. kimi-tide (discussion #9169) solves per-step and per-member model routing today, purely plugin-side: decide at agent/pre-step, rewrite the resolved callConfig at agent/request — the same official mechanism the built-in dsh-agent-default-model uses. Worth knowing if you need this now.

The two layers are complementary:

• Request-level rewriting is dynamic and available today, but the truth lives only in outbound request headers — the author themselves documents that list_agents, the subagent descriptor, and the UI keep showing the inherited model, and auditing requires an external ledger.
• This proposal fixes it at birth: spawnTeammate plumbs agentOptions / persona / toolFilter into the child descriptor, so the choice is persisted in the member record and the team journal, visible in the roster — and it covers the tool surface (least privilege per role), which request rewriting cannot touch at all.

Our PoC (above) also shows why provider-name tricks don't work for teammates: on the continuable path the provider name is just a descriptor label and the provider's start() is never invoked — the continuation owner materializes the child directly.

One caution if the layers coexist: two agent/request rewriters can fight over the same callConfig — worth keeping in mind when stacking routing plugins.

[joel-young]

Follow-up — the wire already exists one layer down (verified on 0.2.0-rc.2).

Cross-referencing @tafcear in discussion #9169, who independently verified this against a running 0.2.0-rc.2 host (we re-checked all of it locally, same version):

1. This is one call site, not a missing mechanism. dsh-tool-subagent already builds and forwards exactly this request shape — agentOptions, persona, toolFilter included (see the [Plugin] 月汐 kimi-tide — 按模型强项编排工作流与代理：K3 写前端、GLM-5.3 写后端、flash 驱动 DSH #9169 thread for line refs) — and the subagent layer resolves and applies them on the child descriptor. Only the Agent Teams roster omits it: dsh-experimental-agent-team/lib/index.js:578 hardcodes { prompt, parent }.

2. Two implementation refinements worth stating up front. assertCapabilities is not on the continuable path (its only call site is the one-shot start()), so forwarding needs no provider capability gating — conditional spreads suffice. And the provider name is not merely a label: expectProvider resolves it and the name decides the seed (spawn = empty, fork = the Lead's completed turns); only start() is unused.

3. A caveat for anyone reading this as least-privilege. toolFilter cannot name run_code — it is a reserved PTC transport and tools.restrict() throws on it (dsh-tools/lib/types/index.js:503). A "read-only" teammate still holds run_code; the hard boundary needs a presentation-mode check (fail closed under PTC) or a scoped tools.guard.

On coexistence: agent/request has four official consumers (dsh-agent, dsh-acp, dsh-api-session-controller, dsh-headless), and cordis waterfalls take the outermost listener with no arbitration. So beyond this ask: an explicit priority for agent/request — or model selection as an official policy service that routing plugins contribute to — would make routing plugins composable instead of silently competing.

[tafcear]

从一台 0.2.0-rc.2 上交叉核验：结论一致。另有两处会改变改法（不是改不改）的实测发现。

断层在两层，不是一层。 公开工具 spawn_teammate 只声明了 4 个入参（dsh-experimental-tool-agent-team/lib/index.js:245-266），转发链在工具层就已经断了：

const agentRequest = {
  name: args.name,
  description: args.description,
  prompt: [...],
  context,
  provider: context === 'fork' ? config.forkProvider : config.freshProvider,   // :290
  signal: exec.signal,
};

全包扫描：dsh-experimental-agent-team（24 个文件）与 dsh-experimental-tool-agent-team 里 agentOptions / persona / toolFilter 命中数均为 0。所以改动＝工具 schema ＋ service 入参 ＋ roster 三处；只改 roster.spawn 的话，模型根本够不着这条路——这点建议在提案里写明。

关于「可见性」那一段，补一层实测到的坑。 list_agents 确实会报 model（MEMBER_VIEW_SCHEMA.model），roster 也确实读的是活体 agent：roster.js:117（live?.options.model ?? root.options.model）与 :413（live.options.model）。但 agent.options.model 是 agent 创建时的合成值，不随 agent/request 的逐请求改写更新——所以插件在请求层给队友改道后，名单上仍是创建时的旧值。它和 descriptor.agentModel 是同一个坑，也是我这边把「队友首条 request/header」写成唯一可信证据的原因。你这个提案恰好把它修掉了：agentOptions 一旦接通，名单报的就是被请求的值，出生点那次记录成为唯一写入点；今天它只能报 Lead 出生时的路由。

一条持久性缺口。 member 记录里没有 model 字段（roster.js:233-240），队友失活后 list 会回落到 root.options.model（:117）——即使这个改动落地，冷恢复的队友仍会显示 Lead 的模型。把解析后的 agentOptions 一并持久化到 member 记录上，这个缺口就闭环了。

核验方法：抽出本机在跑的 app.asar，逐条对照随包发布的 0.2.0-rc.2 源码。帖子里其余断言全部复现：调用点、能力声明、expectProvider / prepareContinuable，以及 fork provider 由 prepareContinuable 返回 seed（dsh-subagent-fork-in-process/lib/index.js:52-55）。

[joel-young]

Correction & strengthening from the proposer — with working patch evidence.

@tafcear's cross-check (comment on this thread) corrected an understatement in our earlier follow-up: the break is not one call site — it spans three layers: the spawn_teammate tool schema (4 params only, dsh-experimental-tool-agent-team/lib/index.js:245-266), the service request, and roster.spawn's startContinuable request. The dsh-tool-subagent precedent shows the right shape; the team path needs all three wired.

We have since validated the whole chain end-to-end with a zero-fork runtime patch on 0.2.0-rc.2: wrap ctx.subagents.startContinuable (the exact call roster.spawn makes) and inject agentOptions into spec.request at spawn time. Results: the teammate is born with the injected model (model: "vl8b" in the member view while live), its turns actually run on that model, and cold recovery resumes on it (descriptor-persisted). toolFilter injection is behaviorally effective too — an A/B run showed the deny-bash teammate's tool schema simply lacks bash, while the control teammate calls it normally. The diagnosis holds, and the fix lands exactly where this proposal points.

One addition the patch evidence surfaced (echoing @tafcear): once the live agent is disposed, list_agents falls back to root.options.model — the member record carries no model field. Please persist the resolved agentOptions (at least provider/model) onto the member record so the roster stays truthful across cold recovery; our run reproduces the fallback exactly.

[tafcear]

Good — and one thing your patch evidence explains that is worth writing into the ask, plus a confirmation.

Why the roster shows the patched model while the teammate is live. With agentOptions injected, the resolved route reaches the child's agent.options: resolveChildAgentOptions(parent, requested, depth) merges the request over the parent (dsh-subagent/lib/types/child-agent.js:75-92), the continuation manager passes it as agentOptions into materialize (dsh-subagent/lib/types/continuation.js:156-170), and the live roster row reads exactly that — live?.options.model ?? root.options.model (dsh-experimental-agent-team/lib/types/roster.js:117), memberView at :413. So your model: "vl8b" is the same field the fallback consults. That is why live-time correctness and post-disposal fallback are one rule, not two bugs: once the member record carries the resolved value, both ends agree, and the descriptor-persisted route keeps cold recovery on the injected model — which is what your run measured.

Your member-record request, confirmed at the source. The record built in roster.spawn is { id, name, description, provider, context, phase } — no model field (roster.js:233-240) — and list therefore has nothing to fall back to except the Lead's own options (:117). Persisting the resolved agentOptions on the member record is exactly the missing write.

One interface caveat if the fix is done provider-side. A custom provider can define its own seed strategy: registerProvider indexes on provider.name alone (dsh-subagent/lib/types/index.js:345-361, duplicates throw DUPLICATE_PROVIDER, registration is effect-scoped and HMR-safe), and the name is constructor-injected — both built-in drivers take it from config (Config = z.object({ providerName: z.string().default(...) }), fork-in-process/lib/index.js:14, spawn-in-process/lib/index.js:13), so one class can be registered under several names. But SubagentProvider.start(request) is a required member; only prepareContinuable is optional (declaration in dsh-subagent/lib/typert.host.js:759). The continuable path never calls it, yet it must exist — a name that resolves without start() throws on one-shot dispatch.

Nothing further from me on the diagnosis — your three-layer framing plus the runtime patch is the complete picture, and the two asks (tool/service/roster wiring, member-record persistence) are the right ones.