Address comment cleanup review

.agents/skills/dsh-prose-standard/SKILL.md

@@ -7,6 +7,8 @@ description: Use when writing, reviewing, restoring, trimming, or auditing prose
 
 Write enough to preserve the contract, then remove reasoning transcripts, repetition, and decoration. This skill owns editorial judgment and required prose coverage; use [dsh-doc-standards](../dsh-doc-standards/SKILL.md) for placement, budgets, bilingual pairs, and documentation gates. It is guidance, not a script.
 
+comment should only describe what is not obvious in the code or not implied by the code.
+
 ## Inputs and exclusions
 
 Require an explicit `scope`. If it is missing, report the required input and stop; do not infer a repository-wide scope or begin an interview.

docs/core-data-structures/subagent.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
-subagent.md: fda4b4b738c648c893c65a633e4a0d6a1761424f
+subagent.md: b5e041dc54d43dcf3609885cfd3dc2c93fa09f25
-subagent.zh.md: ba43789a3e4efe59b197f6454c977db52d90aca1
+subagent.zh.md: 22fb3cd32bded30beff00a79ed4920ebacdd691a

docs/core-data-structures/subagent.md

@@ -19,7 +19,8 @@ A provider advertises its **start-time** features on a static descriptor the ser
  * is rejected with a typed error rather than accepted-then-ignored (the "fail loud, no silent
  * degradation" rule). These static flags cover features needed before a run exists; runtime
  * capabilities such as steering and resume are optional {@link SubagentRun} methods whose presence
- * is the capability.
+ * is the capability. Each flag corresponds one-to-one to a {@link SubagentStartRequest} option:
+ * `depthLimit` to `maxDepth`; the other names match.
  */
 interface SubagentCapabilities {
   readonly outputSchema: boolean
@@ -125,11 +126,13 @@ interface SubagentResult {
  * non-`completed` result to an `isError` tool result.
  */
 interface SubagentStopReasonMap {
+  /** The child finished its turn normally. */
   completed: 'completed'
   /** Cancelled through the request signal or disposal. */
   aborted: 'aborted'
   /** Model or transport failure. */
   error: 'error'
+  /** The child hit its token ceiling before finishing. */
   'max-tokens': 'max-tokens'
   refusal: 'refusal'
 }

docs/core-data-structures/subagent.zh.md

@@ -19,7 +19,8 @@ subagent seam：一个 agent（智能体）将工作委派给子 agent。与 [ba
  * is rejected with a typed error rather than accepted-then-ignored (the "fail loud, no silent
  * degradation" rule). These static flags cover features needed before a run exists; runtime
  * capabilities such as steering and resume are optional {@link SubagentRun} methods whose presence
- * is the capability.
+ * is the capability. Each flag corresponds one-to-one to a {@link SubagentStartRequest} option:
+ * `depthLimit` to `maxDepth`; the other names match.
  */
 interface SubagentCapabilities {
   readonly outputSchema: boolean
@@ -125,11 +126,13 @@ interface SubagentResult {
  * non-`completed` result to an `isError` tool result.
  */
 interface SubagentStopReasonMap {
+  /** The child finished its turn normally. */
   completed: 'completed'
   /** Cancelled through the request signal or disposal. */
   aborted: 'aborted'
   /** Model or transport failure. */
   error: 'error'
+  /** The child hit its token ceiling before finishing. */
   'max-tokens': 'max-tokens'
   refusal: 'refusal'
 }

packages/subagent/subagent/src/types.ts

@@ -28,7 +28,8 @@ export function SubagentRunId(id: string): SubagentRunId {
  * is rejected with a typed error rather than accepted-then-ignored (the "fail loud, no silent
  * degradation" rule). These static flags cover features needed before a run exists; runtime
  * capabilities such as steering and resume are optional {@link SubagentRun} methods whose presence
- * is the capability.
+ * is the capability. Each flag corresponds one-to-one to a {@link SubagentStartRequest} option:
+ * `depthLimit` to `maxDepth`; the other names match.
  */
 export interface SubagentCapabilities {
   readonly outputSchema: boolean
@@ -98,11 +99,13 @@ export interface SubagentStartRequest {
  * non-`completed` result to an `isError` tool result.
  */
 export interface SubagentStopReasonMap {
+  /** The child finished its turn normally. */
   completed: 'completed'
   /** Cancelled through the request signal or disposal. */
   aborted: 'aborted'
   /** Model or transport failure. */
   error: 'error'
+  /** The child hit its token ceiling before finishing. */
   'max-tokens': 'max-tokens'
   refusal: 'refusal'
 }