@duckmind/dm-darwin-x64 0.66.4 → 0.66.6

package/extensions/dm-subagents/src/extension/schemas.js

@@ -1,4 +1,5 @@
 import { Type } from "typebox";
+import { MAX_ARGS_BYTES, MAX_ARGS_DEPTH, MAX_ARGS_FIELDS, MAX_ARGS_ITEMS } from "../workflows/workflow-resources.js";
 function keepTopLevelParameterDescriptions(schema) {
   return pruneNestedDescriptions(schema, []);
 }
@@ -31,24 +32,10 @@ const SkillOverride = Type.Unsafe({
   ],
   description: "Skills: names/CSV/array; false disables, true uses default."
 });
-const OutputOverride = Type.Unsafe({
-  anyOf: [
-    { type: "string" },
-    { type: "boolean" }
-  ],
-  description: "Output filename/path (string), or false to disable file output"
-});
 const OutputModeOverride = Type.String({
   enum: ["inline", "file-only"],
   description: "Default inline; file-only requires output path."
 });
-const ReadsOverride = Type.Unsafe({
-  anyOf: [
-    { type: "array", items: { type: "string" } },
-    { type: "boolean" }
-  ],
-  description: "Files to read before running (array of filenames), or false to disable"
-});
 const JsonSchemaObject = Type.Unsafe({
   type: "object",
   additionalProperties: true,
@@ -64,12 +51,11 @@ const AcceptanceOverride = Type.Unsafe({
     {
       type: "string",
       enum: ["reviewed"],
-      deprecated: true,
       description: "Invalid as an explicit policy. Recognized only so preflight can explain that reviewed is an achieved status."
     },
     {
       type: "string",
-      pattern: "^\\s*\\{"
+      pattern: "^\\s*\\{[\\s\\S]*$"
     },
     { type: "boolean" },
     { type: "object", additionalProperties: true }
@@ -79,10 +65,6 @@ const AcceptanceOverride = Type.Unsafe({
 const AgentContractOverride = Type.Object({
   version: Type.Integer({ minimum: 1, maximum: 1, description: "Enable compatibility behavior for this run/child." })
 }, { additionalProperties: false, description: "Compatibility behavior. Omit for the default behavior." });
-const ChainGateOverride = Type.String({
-  enum: ["execution", "acceptance"],
-  description: "For chain steps with agentContract, choose whether the chain advances on execution success or acceptance success. Defaults to execution."
-});
 const WorkflowLaneMetadata = Type.Object({
   version: Type.Integer({ minimum: 1, maximum: 1 }),
   key: Type.String({ minLength: 1, maxLength: 128, pattern: "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" }),
@@ -122,103 +104,7 @@ const WorkflowPreflightOverride = Type.Object({
   version: Type.Integer({ minimum: 1, maximum: 1 }),
   coverage: Type.Optional(Type.String({ enum: ["complete", "partial"] })),
   lanes: Type.Array(WorkflowPreflightLane, { maxItems: 64 })
-}, { additionalProperties: false, description: "workflowScript/workflowScriptPath only; display-only hints; coverage warns." });
-export const ParallelTaskSchema = Type.Object({
-  agent: Type.String(),
-  task: Type.Optional(Type.String({ description: "Task template with {task}, {previous}, {chain_dir} variables. Defaults to {previous}." })),
-  phase: Type.Optional(Type.String({ description: "Optional phase/group label for status and graph rendering." })),
-  label: Type.Optional(Type.String({ description: "Optional user-facing label for this parallel task." })),
-  as: Type.Optional(Type.String({ description: "Optional safe identifier used as {outputs.name} in later chain steps." })),
-  outputSchema: Type.Optional(OutputSchemaOverride),
-  cwd: Type.Optional(Type.String()),
-  machine: Type.Optional(Type.String({ minLength: 1, maxLength: 128, description: "Herdr saved machine id or label." })),
-  count: Type.Optional(Type.Integer({ minimum: 1, description: "Repeat this parallel task N times with the same settings." })),
-  output: Type.Optional(OutputOverride),
-  outputMode: Type.Optional(OutputModeOverride),
-  reads: Type.Optional(ReadsOverride),
-  progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
-  skill: Type.Optional(SkillOverride),
-  model: Type.Optional(Type.String({ description: "Override model for this task" })),
-  fast: Type.Optional(Type.Boolean({ description: "Opt into priority service tier for supported native OpenAI-Codex child models. This can increase quota or cost." })),
-  toolBudget: Type.Optional(ToolBudgetOverride),
-  acceptance: Type.Optional(AcceptanceOverride),
-  agentContract: Type.Optional(AgentContractOverride),
-  gateOn: Type.Optional(ChainGateOverride)
-});
-export const DynamicExpandSchema = Type.Object({
-  from: Type.Object({
-    output: Type.String({ description: "Prior named structured output to expand from." }),
-    path: Type.String({ description: "JSON Pointer into the structured output, e.g. /items." })
-  }, { additionalProperties: false }),
-  item: Type.Optional(Type.String({ description: "Template variable name for each item. Defaults to item." })),
-  key: Type.Optional(Type.String({ description: "JSON Pointer relative to each item for stable child ids." })),
-  maxItems: Type.Optional(Type.Integer({ minimum: 0, description: "Required fanout bound unless configured globally." })),
-  onEmpty: Type.Optional(Type.String({ enum: ["skip", "fail"], description: "Empty input behavior. Defaults to skip." }))
-}, { additionalProperties: false });
-export const DynamicParallelTemplateSchema = Type.Object({
-  agent: Type.String(),
-  task: Type.Optional(Type.String({ description: "Task template with {item}, {item.path}, {task}, {previous}, {chain_dir}, and {outputs.name} variables." })),
-  phase: Type.Optional(Type.String({ description: "Optional phase/group label for status and graph rendering." })),
-  label: Type.Optional(Type.String({ description: "Optional user-facing label; item templates are supported." })),
-  outputSchema: Type.Optional(OutputSchemaOverride),
-  cwd: Type.Optional(Type.String()),
-  machine: Type.Optional(Type.String({ minLength: 1, maxLength: 128, description: "Herdr saved machine id or label." })),
-  output: Type.Optional(OutputOverride),
-  outputMode: Type.Optional(OutputModeOverride),
-  reads: Type.Optional(ReadsOverride),
-  progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
-  skill: Type.Optional(SkillOverride),
-  model: Type.Optional(Type.String({ description: "Override model for this task" })),
-  fast: Type.Optional(Type.Boolean({ description: "Opt into priority service tier for supported native OpenAI-Codex child models. This can increase quota or cost." })),
-  toolBudget: Type.Optional(ToolBudgetOverride),
-  acceptance: Type.Optional(AcceptanceOverride),
-  agentContract: Type.Optional(AgentContractOverride),
-  gateOn: Type.Optional(ChainGateOverride)
-}, { additionalProperties: false });
-export const DynamicCollectSchema = Type.Object({
-  as: Type.String({ description: "Safe output name for the ordered collected result array." }),
-  outputSchema: Type.Optional(JsonSchemaObject)
-}, { additionalProperties: false });
-export const ChainItem = Type.Object({
-  agent: Type.Optional(Type.String({ description: "Sequential step agent name" })),
-  task: Type.Optional(Type.String({
-    description: "Task template with variables: {task}=original request, {previous}=prior step's text response, {chain_dir}=shared folder, {outputs.name}=prior named output. Required for first step, defaults to '{previous}' for subsequent steps."
-  })),
-  phase: Type.Optional(Type.String({ description: "Optional phase/group label for status and graph rendering." })),
-  label: Type.Optional(Type.String({ description: "Optional user-facing label for this chain step." })),
-  as: Type.Optional(Type.String({ description: "Optional safe identifier used as {outputs.name} in later chain steps." })),
-  outputSchema: Type.Optional(OutputSchemaOverride),
-  cwd: Type.Optional(Type.String()),
-  machine: Type.Optional(Type.String({ minLength: 1, maxLength: 128, description: "Herdr saved machine id or label." })),
-  output: Type.Optional(OutputOverride),
-  outputMode: Type.Optional(OutputModeOverride),
-  reads: Type.Optional(ReadsOverride),
-  progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
-  skill: Type.Optional(SkillOverride),
-  model: Type.Optional(Type.String({ description: "Override model for this step" })),
-  fast: Type.Optional(Type.Boolean({ description: "Opt into priority service tier for supported native OpenAI-Codex child models. This can increase quota or cost." })),
-  toolBudget: Type.Optional(ToolBudgetOverride),
-  acceptance: Type.Optional(AcceptanceOverride),
-  agentContract: Type.Optional(AgentContractOverride),
-  gateOn: Type.Optional(ChainGateOverride),
-  parallel: Type.Optional(Type.Unsafe({
-    anyOf: [
-      Type.Array(ParallelTaskSchema, { minItems: 1, description: "Tasks to run in parallel" }),
-      DynamicParallelTemplateSchema
-    ],
-    description: "Static parallel tasks array, or a single dynamic fanout child template when expand/collect are present."
-  })),
-  expand: Type.Optional(DynamicExpandSchema),
-  collect: Type.Optional(DynamicCollectSchema),
-  concurrency: Type.Optional(Type.Number({ description: "Max concurrent tasks (default: 4)" })),
-  failFast: Type.Optional(Type.Boolean({ description: "Stop on first failure (default: false)" })),
-  worktree: Type.Optional(Type.Boolean({
-    description: "Create isolated git worktrees for each parallel task."
-  }))
-}, {
-  description: "Chain step: use {agent, task?, ...} for sequential, {parallel: [...]} for static concurrent execution, or {expand, parallel: {...}, collect} for dynamic fanout.",
-  additionalProperties: false
-});
+}, { additionalProperties: false, description: "workflow: true or a script path only; display-only hints; coverage warns." });
 const MissionLaunchOverride = Type.Unsafe({
   anyOf: [
     { type: "object", additionalProperties: true },
@@ -246,7 +132,7 @@ const SubagentParamProperties = {
   extensionBindings: Type.Optional(Type.Unsafe({ type: "object", maxProperties: 16, additionalProperties: true, description: "Child-only plain JSON; package.name/1; depth 16, 256 props, 16 KiB." })),
   action: Type.Optional(Type.String({
     minLength: 1,
-    description: "Management/control only; omit for execution. validate accepts either script input. Discover actions with guide topic tool-reference."
+    description: 'Management/control only; omit for execution. validate accepts workflow: true or a script path. Discover actions with {action:"guide",options:{topic:"tool-reference"}}.'
   })),
   capabilities: Type.Optional(Type.Boolean({ description: "list: compact capability rows/details without system prompts." })),
   name: Type.Optional(Type.String({ description: "schedule.create name." })),
@@ -260,13 +146,14 @@ const SubagentParamProperties = {
     description: "Async directory for status/control."
   })),
   handoffPath: Type.Optional(Type.String({ description: "Existing manifest for worktree/lane actions." })),
-  repo: Type.Optional(Type.String({ description: "worktree.cleanup repo; default cwd." })),
-  planId: Type.Optional(Type.String({ description: "Reserved; cleanup is plan-only." })),
+  repo: Type.Optional(Type.String({ description: "Cleanup repo; apply requires it." })),
+  planId: Type.Optional(Type.String({ description: "Reviewed cleanup plan for apply." })),
   laneId: Type.Optional(Type.String({ minLength: 1, maxLength: 128, description: "Exact manifest run id for lane actions." })),
   merge: Type.Optional(Type.Unsafe({ type: "object", additionalProperties: true, description: "lane.recordMerge evidence; read guide tool-reference." })),
   supersession: Type.Optional(Type.Unsafe({ type: "object", additionalProperties: true, description: "lane.recordSupersession evidence; read guide tool-reference." })),
   index: Type.Optional(Type.Integer({ minimum: 0, description: "Zero-based child/transcript index." })),
   childId: Type.Optional(Type.String({ minLength: 1, maxLength: 256, description: "Child-scoped stop identity." })),
+  toolCallId: Type.Optional(Type.String({ description: "Command tool-call id." })),
   view: Type.Optional(Type.String({
     enum: ["fleet", "transcript"],
     description: "status view: fleet overview or transcript tail with id/dir and optional index."
@@ -274,22 +161,22 @@ const SubagentParamProperties = {
   lines: Type.Optional(Type.Integer({ minimum: 1, maximum: 500, description: "Transcript tail lines; default 80." })),
   topic: Type.Optional(Type.String()),
   message: Type.Optional(Type.String({ description: "resume/steer guidance or project.open prompt." })),
-  mode: Type.Optional(Type.String({ enum: ["steer", "follow_up", "auto", "plan", "apply"], description: "steer delivery mode; worktree.cleanup supports plan only, no apply/removal." })),
+  mode: Type.Optional(Type.String({ enum: ["steer", "follow_up", "auto", "plan", "apply"], description: "steer delivery; worktree.cleanup plan/apply (reviewed planId)." })),
   steeringRecovery: Type.Optional(Type.Boolean({ description: "steer: pause/revive after missed acknowledgment; default true in direct steer mode, forced false by extension RPC for exact ownership." })),
   additional: Type.Optional(Type.Integer({ minimum: 1, description: "grant-spawn-budget: root interactive parent + native user confirmation only; total grants capped at original configured cap." })),
   scope: Type.Optional(Type.String({ enum: ["session", "user", "project"], description: "watchdog.configure scope; default session, persistent only if explicit." })),
   target: Type.Optional(Type.String({ enum: ["main", "children", "child"], description: "Watchdog target." })),
   focus: Type.Optional(Type.Boolean({ description: "Focus inspector.open/project.open pane." })),
   thinking: Type.Optional(Type.Unsafe({ anyOf: [{ type: "string" }, { type: "boolean" }], description: "watchdog.configure only: off/minimal/low/medium/high/xhigh/max, inherit, false=off; true invalid. Dispatch ignores this; use model suffix." })),
-  at: Type.Optional(Type.String({ description: "schedule.create: delay (+10m) or zoned ISO timestamp." })),
-  every: Type.Optional(Type.String({ description: "schedule.create interval, e.g. 30m/6h/2d/2w." })),
+  at: Type.Optional(Type.String({ description: "Delay/ISO or local HH:mm." })),
+  every: Type.Optional(Type.String({ description: "Duration or day/week." })),
   sessionOnly: Type.Optional(Type.Boolean()),
   quiet: Type.Optional(Type.Boolean()),
-  on: Type.Optional(Type.Unsafe({ anyOf: [{ type: "string" }, { type: "integer" }], description: "Reserved calendar selector." })),
-  timezone: Type.Optional(Type.String()),
+  on: Type.Optional(Type.Array(Type.String({ enum: ["mon", "tue", "wed", "thu", "fri", "sat", "sun"] }), { minItems: 1, description: "Weekly." })),
+  timezone: Type.Optional(Type.String({ description: "IANA/UTC." })),
   overlap: Type.Optional(Type.String({ enum: ["skip"] })),
-  catchUp: Type.Optional(Type.String({ enum: ["none", "latest"], description: "Missed schedule occurrences; default latest." })),
-  missionId: Type.Optional(Type.String()),
+  catchUp: Type.Optional(Type.String({ enum: ["none", "latest"], description: "Missed; default latest." })),
+  missionId: Type.Optional(Type.String({ description: "Existing mission to attach to a workflow or schedule.create; read guide missions for lifecycle and retention." })),
   mission: Type.Optional(Type.Unsafe({ ...MissionLaunchOverride, description: "false disables; true invalid. Object: exactly one non-empty title or summary; objective/labels optional; goal only true, requires budget.tokens." })),
   missionUpdate: Type.Optional(Type.Unsafe({ ...MissionUpdateOverride, description: "Mission patch; read guide missions." })),
   missionStatus: Type.Optional(Type.String()),
@@ -304,10 +191,11 @@ const SubagentParamProperties = {
     ],
     description: "create/update agent config; object or JSON string."
   })),
-  workflow: Type.Optional(Type.String({ minLength: 1, description: "Extension-owned workflow resource." })),
-  args: Type.Optional(Type.Unsafe({ type: "object", maxProperties: 16, additionalProperties: true, description: "Bounded plain-JSON args for named, inline, or file-backed workflows; raw-script args are exposed deeply frozen and persisted, so do not include secrets." })),
-  workflowScript: Type.Optional(Type.String({ minLength: 1, description: "Inline JavaScript statement body; raw/unknown provenance, no runs.host. Use explicit return and top-level await; see tool guidance/guide workflows." })),
-  workflowScriptPath: Type.Optional(Type.String({ minLength: 1, description: "Raw script file; host reads from request cwd before sandbox. Mutually exclusive with workflowScript and workflow." })),
+  workflow: Type.Optional(Type.Unsafe({
+    anyOf: [{ type: "boolean" }, { type: "string", minLength: 1 }],
+    description: "true: run the one ```js workflow block written in this same reply (false invalid). String with '/': script file read from request cwd. Other string: named workflow resource. Raw scripts (true or path) have no runs.host."
+  })),
+  args: Type.Optional(Type.Unsafe({ type: "object", maxProperties: MAX_ARGS_FIELDS, additionalProperties: true, description: `Plain-JSON args for workflow; ${MAX_ARGS_FIELDS} fields/object, ${MAX_ARGS_ITEMS} items/array, depth ${MAX_ARGS_DEPTH}, ${MAX_ARGS_BYTES / 1024} KiB total; raw-script args are exposed deeply frozen and persisted, so do not include secrets.` })),
   globalConcurrencyLimit: Type.Optional(Type.Integer({ minimum: 1 })),
   maxSubagentSpawnsPerRun: Type.Optional(Type.Integer({ minimum: 1 })),
   preflight: Type.Optional(WorkflowPreflightOverride),
@@ -343,6 +231,7 @@ const SubagentParamProperties = {
     description: "Child output path or false; relative workflow paths use managed artifact routing. Bind durable output here, not task prose; return outputReference/outputPathMapping/artifactPaths."
   })),
   outputMode: Type.Optional(OutputModeOverride),
+  maxOutput: Type.Optional(Type.Object({ bytes: Type.Optional(Type.Integer({ minimum: 1 })), lines: Type.Optional(Type.Integer({ minimum: 1 })) }, { additionalProperties: false })),
   skill: Type.Optional(SkillOverride),
   model: Type.Optional(Type.String({ description: "Child model provider/id; bare id only if unique. Suffix :off/minimal/low/medium/high/xhigh/max overrides agent thinking default." })),
   fast: Type.Optional(Type.Boolean({ description: "Native OpenAI-Codex priority tier; default false, may cost more/quota." })),
@@ -354,30 +243,62 @@ const SubagentParamProperties = {
       { type: "string", minLength: 1 },
       { type: "object", properties: { command: { type: "string", minLength: 1 }, output: { type: "string", enum: ["json"] }, schema: { type: "object" }, timeoutMs: { type: "integer", minimum: 1 } }, required: ["command"], additionalProperties: false }
     ],
-    description: 'Host gate command run after the child finishes: a string, or { command, output: "json", schema?, timeoutMs? } whose passing stdout becomes structuredOutput (not with outputSchema). Cannot be combined with acceptance; an explicit acceptance of false is treated as omitted.'
+    description: 'Host gate command run after the child finishes: a string, or an object; with output "json", passing stdout becomes structuredOutput (not with outputSchema). Cannot be combined with acceptance except false (treated as omitted).'
+  }))
+};
+export const SubagentFlatParams = Type.Object(SubagentParamProperties);
+const { runId: _runId, maxRuntimeMs: _maxRuntimeMs, isolation: _isolation, ...ModelProperties } = SubagentParamProperties;
+const { agent, task, workflow, args, async, model, cwd, worktree, output, action, id, message, ...SubagentOptionProperties } = ModelProperties;
+export const SUBAGENT_OPTION_KEYS = Object.keys(SubagentOptionProperties);
+export const SubagentOptionParams = Type.Object(SubagentOptionProperties, { additionalProperties: false });
+const ModelTopLevelProperties = {
+  agent,
+  task,
+  workflow,
+  args,
+  async,
+  model,
+  cwd,
+  worktree,
+  output,
+  action,
+  id,
+  message,
+  options: Type.Optional(Type.Unsafe({ type: "object", additionalProperties: true, description: "Every field not listed here, such as acceptance, timeoutMs, context, view and index; guide tool-reference/parameter-reference." }))
+};
+export const SubagentParams = keepTopLevelParameterDescriptions(Type.Object(ModelTopLevelProperties));
+const StructuredTask = { type: "object", properties: { agent: { type: "string", minLength: 1 }, task: { type: "string" } }, required: ["agent", "task"], additionalProperties: false };
+const StructuredWorkflowProperties = {
+  action: Type.Optional(Type.String({ minLength: 1, description: 'Management/control only; omit for execution. Discover actions with {action:"guide",options:{topic:"tool-reference"}}.' })),
+  task: Type.Optional(Type.String({ description: "One-child task with agent, or the original request ({task}) with chain/tasks." })),
+  tasks: Type.Optional(Type.Unsafe({ type: "array", minItems: 1, items: StructuredTask, description: "Parallel children; results in order." })),
+  chain: Type.Optional(Type.Unsafe({
+    type: "array",
+    minItems: 1,
+    items: { type: "object", properties: { agent: { type: "string", minLength: 1 }, task: { type: "string" }, as: { type: "string" }, parallel: { type: "array", minItems: 1, items: StructuredTask } }, additionalProperties: false },
+    description: "Sequential steps: {agent,task?,as?} or {parallel:[{agent,task}]}."
   }))
 };
-const SubagentParamsSchema = Type.Object(SubagentParamProperties);
-export const SubagentParams = keepTopLevelParameterDescriptions(SubagentParamsSchema);
-export function createSubagentParamsSchema() {
-  return SubagentParams;
+export function createSubagentParamsSchema(disabled) {
+  if (!disabled || disabled.params.size === 0)
+    return SubagentParams;
+  const structured = disabled.features.has("workflow-scripts");
+  const enabledProperties = Object.fromEntries(Object.entries(ModelTopLevelProperties).flatMap(([name, schema]) => {
+    if (disabled.params.has(name))
+      return [];
+    if (structured && name === "action")
+      return [[name, StructuredWorkflowProperties.action]];
+    if (structured && name === "task")
+      return [[name, StructuredWorkflowProperties.task], ["tasks", StructuredWorkflowProperties.tasks], ["chain", StructuredWorkflowProperties.chain]];
+    return [[name, schema]];
+  }));
+  return keepTopLevelParameterDescriptions(Type.Object(enabledProperties));
 }
 const SubagentWaitParamsSchema = Type.Object({
-  id: Type.Optional(Type.String({
-    description: "Async run or remembered detached foreground run id/prefix to wait for one specific run. Ordinary async subagent runs already notify this session natively; use bg_wait for provider, detached, or other background work without native notification, or when same-turn blocking results are truly needed. Omit to wait across every active async run started in this session only when a same-turn wait is truly needed."
-  })),
-  nonBlocking: Type.Optional(Type.Boolean({
-    description: "When true, resolve id to one exact run, persist a wake subscription, and return immediately. Use this only for provider, detached, or other background work without a native completion notification; ordinary async subagent runs already notify this session natively and do not need a subscription. The originating session is woken on completion, failure, attention, reconciliation failure, or timeout. Requires id and cannot be combined with all."
-  })),
-  all: Type.Optional(Type.Boolean({
-    description: "Wait for ALL active runs to finish. Ordinary async subagent runs already notify this session natively; use all only when a same-turn result from tracked background work is truly needed. Default false: return when the first tracked run or provider item finishes or needs attention. Ignored when id targets a single run."
-  })),
-  timeoutMs: Type.Optional(Type.Integer({
-    minimum: 1,
-    description: "Give up waiting after this many milliseconds (the runs keep going regardless). Ordinary async subagent runs already notify this session natively; use a wait timeout only when same-turn results are truly needed for provider, detached, or other background work without native notification. Defaults to config waitTool.defaultTimeoutMs, then 1800000 (30 minutes). Window expiry is a non-error active-work result."
-  })),
-  stopOnAttention: Type.Optional(Type.Boolean({
-    description: "For a blocking wait that is truly needed, stop when a run needs attention by default. Set false to keep waiting through idle or long-thinking attention; supervisor/contact requests still stop the wait."
-  }))
+  id: Type.Optional(Type.String({ description: "Run id or prefix." })),
+  nonBlocking: Type.Optional(Type.Boolean({ description: "Subscribe to id's wake and return immediately; requires id, not with all." })),
+  all: Type.Optional(Type.Boolean({ description: "Wait for all work active at call time." })),
+  timeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Max wait; default waitTool.defaultTimeoutMs, then 30 min." })),
+  stopOnAttention: Type.Optional(Type.Boolean({ description: "false: keep waiting through idle or long-thinking attention." }))
 });
 export const SubagentWaitParams = keepTopLevelParameterDescriptions(SubagentWaitParamsSchema);

package/extensions/dm-subagents/src/extension/subagent-guide.js

@@ -14,6 +14,7 @@ export const SUBAGENT_GUIDE_TOPICS = [
   "extension-api",
   "council"
 ];
+const SUBAGENT_GUIDE_SECTION_MAX_CHARS = 8000;
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
 const COUNCIL_FILES = [
   "skills/council-mode/SKILL.md",
@@ -23,20 +24,104 @@ const COUNCIL_FILES = [
 function isGuideTopic(value) {
   return SUBAGENT_GUIDE_TOPICS.includes(value);
 }
+function headingSlug(title) {
+  return title.toLowerCase().replace(/[^\p{L}\p{N}\s_-]/gu, "").trim().replace(/\s/g, "-");
+}
+function parseSections(topic, lines) {
+  const sections = [];
+  let fence;
+  lines.forEach((line, index) => {
+    const marker = /^\s*(```+|~~~+)/.exec(line)?.[1];
+    if (marker) {
+      if (!fence)
+        fence = marker;
+      else if (marker.startsWith(fence))
+        fence = undefined;
+      return;
+    }
+    const heading = fence ? undefined : /^(#{2,6})\s+(.+?)\s*#*\s*$/.exec(line);
+    if (heading)
+      sections.push({ address: "", title: heading[2], level: heading[1].length, start: index, end: lines.length, children: [] });
+  });
+  const used = new Set;
+  const parents = [];
+  for (const [index, section] of sections.entries()) {
+    const next = sections.slice(index + 1).find((other) => other.level <= section.level);
+    if (next)
+      section.end = next.start;
+    while (parents.length && parents.at(-1).level >= section.level)
+      parents.pop();
+    const parent = parents.at(-1);
+    parent?.children.push(section);
+    let slug = headingSlug(section.title);
+    if (used.has(slug) && parent)
+      slug = `${parent.address.slice(topic.length + 1)}-${slug}`;
+    for (let suffix = 2, base = slug;used.has(slug); suffix++)
+      slug = `${base}-${suffix}`;
+    used.add(slug);
+    section.address = `${topic}/${slug}`;
+    parents.push(section);
+  }
+  return sections;
+}
+function tableOfContents(topic, sections) {
+  const rows = sections.map((section) => `${"  ".repeat(section.level - 2)}${section.address} — ${section.title}`);
+  return `Sections of guide topic '${topic}'. Read one with {action:"guide",options:{topic:"<section address>"}}:
+${rows.join(`
+`)}`;
+}
+function sectionText(lines, section) {
+  const text = lines.slice(section.start, section.end).join(`
+`).trim();
+  if (text.length <= SUBAGENT_GUIDE_SECTION_MAX_CHARS || !section.children.length)
+    return text;
+  const intro = lines.slice(section.start, section.children[0].start).join(`
+`).trim();
+  return `${intro}
+
+Subsections (read one with {action:"guide",options:{topic:"<address>"}}):
+${section.children.map((child) => `${child.address} — ${child.title}`).join(`
+`)}`;
+}
+function readGuideFiles(topic, files, root) {
+  try {
+    return files.map((file) => fs.readFileSync(path.join(root, file), "utf-8").replace(/\r\n/g, `
+`));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to read packaged subagents guide '${topic}': ${message}`, { cause: error instanceof Error ? error : undefined });
+  }
+}
 export function readSubagentGuide(topic = "overview", root = packageRoot) {
-  if (!isGuideTopic(topic)) {
+  const separator = topic.indexOf("/");
+  const name = separator === -1 ? topic : topic.slice(0, separator);
+  const sectioned = isGuideTopic(name) && name !== "overview" && name !== "council";
+  if (!isGuideTopic(name) || separator !== -1 && !sectioned) {
     return `Unknown subagents guide topic '${topic}'. Valid topics: ${SUBAGENT_GUIDE_TOPICS.join(", ")}. No files were changed.`;
   }
-  const files = topic === "overview" ? ["README.md"] : topic === "council" ? COUNCIL_FILES : [path.join("docs", `${topic}.md`)];
-  try {
-    const contents = files.map((file) => fs.readFileSync(path.join(root, file), "utf-8"));
+  if (!sectioned) {
+    const files = name === "overview" ? ["README.md"] : COUNCIL_FILES;
+    const contents = readGuideFiles(name, files, root);
     return files.length === 1 ? contents[0] : contents.map((content, index) => `<!-- ${files[index]} -->
 
 ${content}`).join(`
 
 `);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`Failed to read packaged subagents guide '${topic}': ${message}`, { cause: error instanceof Error ? error : undefined });
   }
+  const lines = readGuideFiles(name, [path.join("docs", `${name}.md`)], root)[0].split(`
+`);
+  const sections = parseSections(name, lines);
+  if (separator === -1) {
+    const intro = lines.slice(0, sections[0]?.start ?? lines.length).join(`
+`).trim();
+    return `${intro}
+
+${tableOfContents(name, sections)}`;
+  }
+  const section = sections.find((candidate) => candidate.address === topic);
+  if (!section)
+    return `Unknown section '${topic}'. No files were changed.
+
+${tableOfContents(name, sections)}`;
+  return sectionText(lines, section);
 }

package/extensions/dm-subagents/src/extension/subagent-options.js

@@ -0,0 +1,47 @@
+import { isDeepStrictEqual } from "node:util";
+import { Compile } from "typebox/compile";
+import { closestMatch } from "../shared/edit-distance.js";
+import { removedModelWorkflowFieldError } from "./public-execution.js";
+import { SUBAGENT_OPTION_KEYS, SubagentOptionParams, createSubagentParamsSchema } from "./schemas.js";
+const optionKeys = new Set(SUBAGENT_OPTION_KEYS);
+const ALIAS_HINTS = { runId: "id (top-level)", maxRuntimeMs: "options.timeoutMs", isolation: "worktree (top-level)" };
+const optionsValidator = Compile(SubagentOptionParams);
+export function flattenSubagentToolOptions(params, disabled) {
+  const removedTopLevel = removedModelWorkflowFieldError(params);
+  if (removedTopLevel)
+    throw new Error(removedTopLevel);
+  const { options, ...topLevel } = params;
+  if (options === undefined)
+    return topLevel;
+  if (!options || typeof options !== "object" || Array.isArray(options))
+    throw new Error("subagent: options must be an object.");
+  const removedField = removedModelWorkflowFieldError(options);
+  if (removedField)
+    throw new Error(removedField);
+  const entries = Object.entries(options);
+  const enabledKeys = SUBAGENT_OPTION_KEYS.filter((key) => !disabled?.params.has(key));
+  const unknown = entries.map(([key]) => key).filter((key) => !optionKeys.has(key));
+  if (unknown.length > 0) {
+    const fields = Object.keys(createSubagentParamsSchema(disabled).properties);
+    const hints = unknown.map((key) => {
+      if (Object.hasOwn(ALIAS_HINTS, key))
+        return `unknown options key '${key}'; use ${ALIAS_HINTS[key]}.`;
+      if (fields.includes(key))
+        return `'${key}' is a top-level field, not an option.`;
+      const suggestion = closestMatch(key, enabledKeys);
+      return `unknown options key '${key}'.${suggestion ? ` Did you mean '${suggestion}'?` : ""}`;
+    });
+    throw new Error(`subagent: ${hints.join(" ")} Valid options: ${enabledKeys.sort().join(", ")}.`);
+  }
+  const disabledKey = entries.find(([key]) => disabled?.params.has(key))?.[0];
+  if (disabledKey)
+    throw new Error(`subagent option 'options.${disabledKey}' is disabled by config ${disabled.params.get(disabledKey)}.`);
+  if (!optionsValidator.Check(options)) {
+    const errors = [...optionsValidator.Errors(options)].slice(0, 4).map((error) => `options${error.instancePath.replaceAll("/", ".")} ${error.message}`);
+    throw new Error(`subagent: ${errors.join("; ")}.`);
+  }
+  const conflicts = entries.filter(([key, value]) => topLevel[key] !== undefined && !isDeepStrictEqual(topLevel[key], value)).map(([key]) => `'${key}'`);
+  if (conflicts.length > 0)
+    throw new Error(`subagent: ${conflicts.join(", ")} given both at the top level and in options with different values; give each once.`);
+  return { ...topLevel, ...options };
+}