[BUG] Spawned subagents inherit the parent's creation-time model options — stale provider keeps 401ing until server restart

[ahmadmhmdsy]

Summary

Spawned subagents (subagent / subagent_fork, in-process spawn/fork providers) inherit the parent agent's creation-time model options instead of the session's live model selection. After the default model/provider changes mid-session (via $DSH_HOME/settings.yaml → agent-default-model, or a per-session /model switch), the parent's own requests route through the new provider, but every subsequently spawned child still routes through the old provider — with the old provider's credentials resolved per request. When those credentials are expired/revoked, 100% of subagent dispatches fail with AUTH 401 while the parent session keeps working, until the server is restarted.

Reproduction

1. Boot a web profile (bundles dsh-base + dsh-web-app). The base bundle ships agent-default-model pinned to deepseek-official:
   • @deepseek-ai/dsh-base/cordis.patch.yml rows 62-67: provider: deepseek-official, model: deepseek-v4-flash
2. Open a session while that default is effective — the session agent is created with agentOptions taken from defaultModelSelection() (see below).
3. Change the model default to a different provider (settings document, hot-reloaded), or select a different model via the session /model UI.
4. Dispatch a trivial subagent.

Expected: the child uses the session's current model selection (same provider the parent's own requests now use).

Actual: the child's first request/header shows the parent's creation-time provider/model, and the first LLM call fails (observed: Authentication Fails… code AUTH, status 401) because the stale provider resolves a dead credential.

Evidence from the session log (decompressed session.jsonl.zstd):

• First parent request/header (seq ~11): provider: deepseek-official (creation-time default).
• Later parent request/header (seq ~26): provider: opencode-go (after the default change).
• Child request/header: provider: deepseek-official (stale) → assistant/chunk finish error {code: AUTH, status: 401}.
• After a server restart the child routes correctly (cold resume re-creates the session agent with the current default) — restart is the workaround, and confirms the sliding window.

Root cause (from source)

1. Web session agents are created/resumed with options snapshotted from the live default:
   • packages/host/apiproxy/src/api-proxy.ts → agentOptions() = defaults.defaultModelSelection()
   • packages/host/apiproxy/src/index.ts → defaultModelSelection: () => ctx.agentDefaultModel.currentSelection()
2. agentDefaultModel.currentSelection() is settings-driven and evaluated at create/resume time. The snapshot lands in the agent's immutable options.
3. Request-time routing is separate: api-proxy installs installModelSelection(...), which re-reads a per-session selection waterfall — picked selection → session's latest logged request/header → live default — on every request. That is why the parent switches cleanly while agent.options stays frozen.
4. Children are composed via packages/subagent/subagent/src/child-agent.ts → resolveChildAgentOptions(parent, requested, depth), which copies parent.options.provider/model/maxTokens and only then spreads any per-child agentOptions override. Nothing feeds the session's live selection or the current default into that copy, so children pin the parent's creation-time route indefinitely.

Suggested fix

Children should resolve their route from the same live waterfall the parent uses per request (session selection → latest logged request/header → agentDefaultModel.currentSelection()), falling back to parent.options only when none of those exist — or, minimally, the spawned-child options should re-read agentDefaultModel.currentSelection() when the parent's options differ from it. An escape hatch already exists per-tool (tool-subagent config agentOptions, spread last so it wins), but it is per-deployment config, not a fix for the default path.

Affected versions / environment

• DSH web profile (dsh-base + dsh-web-app bundles), latest installed as of 2026-08-17
• In-process spawn and fork subagent providers (tool-subagent, tool-subagent-fork), backgroundMode: continuable
• Windows 10/11, Node 24, npm 11
• Setting change path: $DSH_HOME/settings.yaml agent-default-model section plus $DSH_HOME/.credentials.yaml provider keys

Workarounds (until fixed)

• Server restart — cold resume re-creates the session agent with the current default; children route correctly afterwards.
• Per-tool override — set agentOptions: {provider, model} on the tool-subagent / tool-subagent-fork preset rows (spread last in resolveChildAgentOptions, so it wins over the inherited parent route). Note the preset composition is stamped: edits apply to sessions created afterwards.
• New session — a session created after the default change inherits the correct route.

---

Reported from local diagnosis only; no keys or credentials are included in this report. The failing provider line was confirmed from child session logs (request/header + assistant/chunk failure records), not from any secret material.

[argszero]

Verified against the current checkout (master @ 99f6f02fec, rc.7) — every claim in the report checks out, and the precise mechanism boundary is even narrower than "children copy frozen options".

1. Confirmed at source.

• resolveChildAgentOptions (packages/subagent/subagent/src/child-agent.ts:68-83) copies parent.options.provider/model/maxTokens and only then spreads the per-child requested override (so the per-tool escape hatch really does win — your workaround #2 is correct).
• Single composition home: the module doc states "Both the one-shot provider driver and the continuation manager compose children this way" — continuation.ts:444 is the one call site. One fix covers subagent AND subagent_fork.
• Parent-side liveness: selectionFor(agent) (packages/host/apiproxy/src/api-proxy.ts:1123-1150) computes the per-request waterfall exactly as you described (picked → agent.session.requestHeader()?.config → defaults.defaultModelSelection()), and installModelSelection(agent.ctx, selection) (packages/core/agent/src/model-selection.ts:39-78) couples it to request routing.

2. The mechanism boundary — why the parent switches but the child never does.
The selections map is keyed by Agent instance (api-proxy.ts:1123), and the selection handlers are registered on the parent's scoped ctx. The child is composed on its own scoped ctx via this.ownerCtx.agents.create(...) (continuation.ts:1016) — it never enters the parent's selections map, and nothing in the child's own scope chain rewrites its route. Then the seed timing locks it in: buildRequest seeds the first request/header from this.options when !requestHeaderLogged (agent.ts:428-437, header logged at :465-470). So the entire divergence is decided at seed time — after its first request the child would re-resolve like any agent, but by then its header already carries the stale route. This also explains why your restart workaround works: cold resume re-creates the session agent with the live default, so the next child seeds correctly.

3. Fix design — three tiers.

• Minimal (package-local, has a precedent in the same file): in resolveChildAgentOptions, prefer the parent's live route — parent.session.requestHeader()?.config (provider/model/maxTokens) — over parent.options. requestHeader() is a public Session API (session/index.ts:670) returning the folded latest request/header, and after a mid-session switch it already carries the new provider (your evidence: parent header seq ~26 = opencode-go). The precedent is literally next door: childSessionMeta (child-agent.ts:107) already reads parent.session.header for the same reason — persist/seed what the child will actually run under, not what the parent started with. This alone fixes your exact scenario.
• Edge case: a child spawned immediately after the switch, before the parent's next request, still sees the stale folded header (the header only advances when the parent actually makes a request). Full correctness needs the fallback chain to the live default — but the subagent package can't reach ctx.agentDefaultModel (host service, api-proxy/index.ts:99). That tier needs either a small injected resolver (an optional resolveDefaultModel callback threaded into the subagent service config, defaulting to parent.options) or moving the decision from creation time to the child's first agent/request waterfall.
• Symmetric long-term: selectionFor.current's picked tier (per-session /model switch) also only reaches the child after the parent has made one request under it. If in-process children shared the parent's WebModelSelectionRef instead of re-deriving, /model switches would propagate to children too — the cleanest end-state, at the cost of crossing the api-proxy/subagent boundary.

4. Family + regression test.
This is the "creation-time snapshot diverges from live state" pattern — same root shape as the replay-state coherence family (#1627/#1703/#2143: durable content vs frozen replay metadata): a value captured at creation outlives the state it was derived from, and only a cold re-create resyncs. The asymmetry that hid it: the parent's own path was already fixed to be live (per-request re-resolution), but the child-composition path kept the frozen snapshot. A regression test would be cheap: spawn a child after a mid-session model switch, assert the child's first request/header carries the new route.

One question this raises that the report doesn't cover: continuable children on cold resume — a child resumed from disk re-creates from its persisted header (the stale one). Does the resume path re-resolve the route the same way selectionFor does for parents, or does it keep the stale route until its first request? If the latter, the minimal fix should also cover the resume path, not just the spawn path.

[jzhao0]

Implemented and regression-tested a package-local fix for the stale child route described here.

Patch commit: jzhao0@bead7b4
Branch: https://github.com/jzhao0/deepseek-harness/tree/fix/subagent-live-route-inheritance

The change makes resolveChildAgentOptions() prefer the parent's latest session.requestHeader()?.config for provider, model, and maxTokens, with per-field fallback to parent.options; explicit child agentOptions still win. Continuable creation resolves the route once before its first await and reuses that snapshot for both the durable descriptor and materialization.

Regression coverage: one-shot and continuable RED→GREEN, relevant inheritance suites 14/14, and the assembled keyless snapshot fails against the old source and passes with the patch.

I also tried to open an upstream PR, but the repository currently reports has_pull_requests=false and GitHub rejects CreatePullRequest. The commit above is ready to cherry-pick; if PRs are re-enabled I can open it immediately.

[ahmadmhmdsy]

Implementation ready for review

A working implementation of the fix described in this discussion is now available on a fork.

Branch: fix/subagent-live-routing
Fork URL: https://github.com/ahmadmhmdsy/deepseek-harness/tree/fix/subagent-live-routing
Commit: 721c1d6fe11971d8895e6f273b190f7d70f2e43b
Patch file: https://github.com/ahmadmhmdsy/deepseek-harness/raw/fix/subagent-live-routing/0001-fix-subagent-route-spawned-children-through-pare.patch

Note: I tried to open a PR directly, but deepseek-ai/deepseek-harness has PR creation disabled at the repo level (has_pull_requests: false), so the standard PR flow is unavailable. Filing here per the existing discussion thread.

What changed (5 files, 215 insertions, 10 deletions)

• packages/subagent/subagent/src/child-agent.ts — resolveChildAgentOptions now reads, per field, the highest-precedence source from the parent's live waterfall (request header → agentDefaultModel.currentSelection() → parent.options), preserving the per-child requested override as the winner.
• packages/subagent/subagent/tests/child-agent.spec.ts — new file (10 tests, the first test file in this package): live default precedence, request-header precedence, override wins, maxTokens preservation, subagentDepth stamping, undefined-field omission, and a backward-compat regression guard.
• packages/subagent/subagent/package.json — adds @deepseek-ai/dsh-agent-default-model to devDependencies (workspace protocol, no lockfile churn beyond the link line).
• packages/subagent/subagent/tsconfig.json — adds a project reference to ../../core/agent-default-model so cross-package ambient augmentation resolves during tsc -p standalone typecheck (matches the convention used by host/apiproxy/tsconfig.json).
• pnpm-lock.yaml — one link entry added for the new devDep; no version bumps.

Verification

• npx vitest run packages/subagent/subagent/tests/child-agent.spec.ts — 10 passed (10)
• npx tsc --noEmit -p packages/subagent/subagent/tsconfig.json — clean
• npx tsc --noEmit -p packages/host/apiproxy/tsconfig.json (downstream consumer) — clean
• npx tsc --noEmit -p packages/subagent/subagent-in-process-driver/tsconfig.json (other caller) — clean
• Repository pre-push lefthook gate (typecheck:contracts-ready → tsc -b tsconfig.client.json) — pass in 97.88s on the push.

Compatibility

• Compositions without agentDefaultModel keep the legacy parent.options fallback unchanged.
• The per-tool agentOptions override continues to win.
• No public type signatures changed.
• No secrets, API keys, credential tails, or local paths are included in the patch, branch, or this comment.

Caveat (from the diagnosis)

The per-session picked selection set by the master's /model UI lives inside api-proxy.selectionFor's closure and is not externally readable; subagents pick it up automatically after the parent's next logged request carries the new header. The two accessible sources (request header, live default) cover every other routing change without restart.

Happy to revise the implementation or split it into multiple commits if maintainers prefer a different shape.

[argszero]

Cross-validating both implementations against the 0.1.1-rc.2 source. Your patch (721c1d6f) checks out, and the design decisions in it map exactly onto the tiers this thread banked back in #2904's first reply — with one load-bearing gap worth closing before this is the canonical candidate.

What's verified and correct

1. The waterfall requestHeader()?.config → ctx.get('agentDefaultModel')?.currentSelection() → parent.options is precisely tier-1 + tier-2 of the blueprint: the live folded header first, then the live default for the no-request-yet window, then the legacy seed. requestHeader() is the public Session API (packages/core/session/src/index.ts:670), and currentSelection() exists on AgentDefaultModelConfig (packages/core/agent-default-model/src/index.ts:88) — already used by api-proxy as defaultModelSelection (packages/host/apiproxy/src/index.ts:99).
2. ctx.get('agentDefaultModel') is the clean Cordis-DI form of the tier-2 "small injected resolver" the blueprint proposed (threading a callback through the subagent config). Optional composition keeps rosterless/minimal bundles on the legacy fallback — no forced dependency. Verified the service is actually composed where it matters: host/apiproxy mounts it and bundle/headless references it, so the tier is live in both web and headless deployments, not dead code.
3. requested (the per-tool agentOptions) spread last — the documented escape hatch still wins. maxTokens policy noted below.

Gap — the durable descriptor still snapshots parent.options

packages/subagent/subagent/src/continuation.ts:420-421 still reads:

const agentProvider = request.agentOptions?.provider ?? parent.options.provider
const agentModel = request.agentOptions?.model ?? parent.options.model

while :463 materializes through the fixed resolveChildAgentOptions. Two consequences:

1. Audit inversion. The subagent/descriptor record (with agentProvider/agentModel) is exactly the evidence users quoted in [Bug] Subagents inherit session-start options.model instead of the current UI-selected model (causes unexpected v4-pro billing) #1472 and Subagents inherit the parent's creation-time model seed instead of its live route, delegation silently runs on for exmaple `openrouter/auto` after the default model is switched #4065 to diagnose the billing misroute. After this patch the child runs the live route but the durable record says the stale one — the record users audit now lies in the opposite direction.
2. Cold resume still misroutes. The resume path (continuation.ts:967 folds the persisted descriptor; :982-983 reconstructs agentOptions from its agentProvider/agentModel) never passes through resolveChildAgentOptions. So a continuable child created under this patch persists a stale descriptor (from :420-421) and, when cold-resumed, re-materializes on the stale route — the exact silent-misroute class this family exists to kill.

There is already a second implementation that closes this

jzhao0's bead7b4f8 (posted 8/19) is tier-1 only (requestHeader → per-field parent.options fallback, no live-default tier), but it resolves AgentOptions once before the first await and feeds that single snapshot into both the durable descriptor and materialization — so descriptor, runtime route, and resume reconstruction all agree, with a documented stance that cold resume stays stable on the persisted child route rather than re-sampling the parent. Its regression pins exactly this: one-shot child materializes live, continuable descriptor + child request/header carry the same live snapshot.

Suggested canonical patch when PRs re-enable

Your waterfall (tier-1 + tier-2) + jzhao0's descriptor sync: resolve once, share the snapshot across :420-421 and :463, and add a regression asserting the three sites agree (resolved options / durable descriptor / child first request/header). That gives the repo one candidate instead of two divergent ones.

One open design decision (from my original reply here)

jzhao0's choice — "cold resume does not re-read the parent's current route" — is defensible (an established durable child shouldn't be retroactively re-routed), but it is precisely the question this thread asked and never got an answer to: a continuable child resumed after the parent switched models will run the old route for its entire remaining life. For the billing-misroute family, "stability" is exactly what the reports keep calling a silent bug. Maintainers should pick: stable-from-descriptor (jzhao0) or re-resolve-at-resume — and either way the descriptor must agree with the actual route, which requires the :420-421 fix regardless.

Also note the maxTokens divergence: jzhao0 copies it from the live header ("part of the same inherited request route — splitting sources leaves request config internally inconsistent"), you keep it on parent.options as "budget, not route". Both are coherent; worth one explicit maintainer decision so the two don't stay divergent in the merged form.

中文摘要：对照 rc.2 验证了你的补丁（瀑布顺序 = 本线程蓝图的 tier-1+tier-2，ctx.get('agentDefaultModel') 正是蓝图提议的注入解析器形态，且 web/headless 均实际组合该服务，不是死代码）。但 continuation.ts:420-421 的描述符快照仍读 parent.options——后果是 (1) 用户审计计费时引用的 subagent/descriptor 记录与子代理实际路由相反地不一致；(2) 冷恢复（:967/:982-983）从持久化描述符重建，恢复后的子代理仍走陈旧路由。jzhao0 的 bead7b4（仅 tier-1）已解决描述符同步（首 await 前解析一次、描述符与物化共用同一快照）。建议 PR 重开时收敛为：你的瀑布 + jzhao0 的描述符同步，并用三处一致（解析结果/持久描述符/child 首请求 header）的回归测试钉住。另有两个待定决策：冷恢复是否重新解析父当前路由（稳定性 vs 活跃性），以及 maxTokens 来源（两补丁分歧）。

[weijiafu14]

补一条与楼上 DSH 原生补丁并行、可以直接使用的替代路线。它不修复官方 resolveChildAgentOptions()，而是用 Pi 社区的子代理插件创建原生 DSH child session：

dsh plugin --profile <你的-profile> add pi2dsh
dsh plugin --profile <你的-profile> add @tintinweb/pi-subagents

pi2dsh 的子代理路由解析现在优先读取父会话持久日志中最后一次真实请求的 provider/model，最后才回退创建时 options。因此旧 provider 已失效但父会话已经切到新 provider 时，新开的 Pi 子代理不会继续拿旧凭证 401。

真机验收不是看选择器文字：stock dsh-TUI 中父会话先请求官方线，/model 切到独立网关后再 spawn 无模型子代理；最终直接读取父子两份 session JSONL，父路由为 deepseek-official → work-gw，子路由只为 work-gw，子工具也真实落盘。这个结果覆盖“创建时快照导致 stale provider”的核心症状，但不代表 DSH 原生 spawn/fork 已被我们修好。

复现与证据：
https://github.com/weijiafu14/pi2dsh/tree/main/examples/subagents
https://github.com/weijiafu14/pi2dsh/blob/main/community/subagents-acceptance-report.md