From 5da2ac58357bfdb6164e79af3f907a54889f0514 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 2 Aug 2026 12:29:02 +0800
Subject: [PATCH] docs(subagent): state that per-activation knobs are not
 restored on cold resume
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The descriptor deliberately snapshots a curated composition field set
rather than the merge-extensible `AgentOptions`, and it already names the
per-activation exclusions (`outputSchema`). `maxTokens` is the same class
of property — it budgets one activation, and on cold resume there is no
parent to inherit a limit from, so the resumed activation runs under the
deployment defaults. Spell that out in the module contract so the
fallback is a documented decision instead of a silent surprise for
deployments that set explicit child token limits.
---
 packages/subagent/subagent/src/descriptor.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/packages/subagent/subagent/src/descriptor.ts b/packages/subagent/subagent/src/descriptor.ts
index 22acbecbdd..4cec72e658 100644
--- a/packages/subagent/subagent/src/descriptor.ts
+++ b/packages/subagent/subagent/src/descriptor.ts
@@ -12,6 +12,10 @@
  * omits `subagentDepth` — cold resume trusts the persisted header's
  * `delegationDepth` as the monotone floor — and `outputSchema`, which belongs
  * to one activation's result contract rather than durable child composition.
+ * Per-activation knobs such as `maxTokens` are omitted for the same reason as
+ * `outputSchema`: they budget one activation and, on cold resume, no parent
+ * exists to inherit them from, so the resumed activation runs under the
+ * deployment defaults rather than restoring a stale budget.
  *
  * @module @deepseek-ai/dsh-subagent/descriptor
  */