@duckmind/dm-windows-x64 0.61.4 → 0.61.9

package/extensions/dm-subagents/src/extension/tool-description.js

@@ -3,90 +3,101 @@ import * as path from "node:path";
 import { getAgentDir, getProjectConfigDir } from "../shared/utils.js";
 const CUSTOM_TOOL_DESCRIPTION_FILE = "subagent-tool-description.md";
 const CUSTOM_TOOL_DESCRIPTION_MAX_BYTES = 50 * 1024;
+const EXTERNAL_CLI_RUNNER_GUIDANCE = "External CLI agents (codex-exec, codex-exec-writer, claude-code, claude-code-writer, cursor-agent, cursor-agent-writer) use their own runner contract and do not support native DM child options such as model override, structured output, acceptance/agent contract, tool budget, fast mode, fork context, skills, or native DM tools unless the runner explicitly implements them.";
+const WORKFLOW_RESUME_KEY_GUIDANCE = "Each workflow key identifies one result lane: use a new stable workflow key for every distinct retained resume pass; same-key calls are reused only when launch parameters are identical, and incompatible parameters are rejected.";
+const WORKFLOW_OUTPUT_BINDING_GUIDANCE = "For durable workflow child files, set output on runs.run/runs.all; task filename prose is not an output declaration, and return the child's outputReference, outputPathMapping, or artifactPaths instead of inventing a literal path.";
+const WORKFLOW_LANES_GUIDANCE = "For bounded parallel sequential chains, use runs.lanes([{key,stages:[{key,agent,task},{key,resume:'previous',task},...]}]); first stages run together, later stages sequence per lane, and the bounded board reports lane-local failures. Only an explicit structuredOutput.verdict === 'blocked' blocks a successful stage; reviewer prose is not parsed.";
+const WORKFLOW_SCRIPT_PORTABILITY_GUIDANCE = "workflowScript rejects nested async function, arrow, and method helpers; use top-level await, plain helper functions that return runs.run(...), or explicit Promise chains instead.";
+const WORKFLOW_HOST_GUIDANCE = "For one non-interactive operator-owned command, await runs.host(key,{kind:'command',command,timeoutMs,output?,role?,provider?}). runs.host has no per-step cwd: commands and relative output paths use the workflow cwd; set cwd on the outer subagent request instead (for example, {cwd:'/path/to/worktree',workflowScript:'...'}), or put a trusted directory change in the command (for example, 'cd /path/to/worktree && npm test'). v1 supports only command steps; output is bounded and command failure fails the workflow.";
+const AGENT_CAPABILITY_GUIDANCE = 'For capability selection, use { action: "list", capabilities: true } for compact prompt-free rows.';
+export const DEFAULT_SUBAGENT_TOOL_DESCRIPTION = `Delegate to configured subagents. For execution, omit action and use {agent, task?} for one child, workflowScript for inline orchestration, or workflowScriptPath to load a script from the request cwd. The script inputs are mutually exclusive. Use action:'validate' with either script input to check it without launching children. For multi-step or parallel work, make exactly one top-level subagent call with async:true; launch children only inside that workflow and do not make another top-level call for them. Use runs.run('key',{agent,task}) for one child, await runs.all([{key:'a',agent:'reviewer',task:'...'},{key:'b',agent:'reviewer',task:'...'}]) for ordinary parallel children, and read its ordered array result with indexes, destructuring, or .map(...), not by key property. ${WORKFLOW_SCRIPT_PORTABILITY_GUIDANCE} ${WORKFLOW_LANES_GUIDANCE} ${WORKFLOW_HOST_GUIDANCE} ${EXTERNAL_CLI_RUNNER_GUIDANCE} Use action only for management/control. Use guide or the dm-subagents skill for advanced workflow details.`;
+export const SUBAGENT_TOOL_PROMPT_SNIPPET = "Delegate to subagents; orchestrate in one workflowScript call.";
+export const SUBAGENT_TOOL_PROMPT_GUIDELINES = [
+  `Use subagent only when delegation is needed. Before executing, call { action: "list" } and run only executable, non-disabled agents. ${AGENT_CAPABILITY_GUIDANCE}`,
+  "Omit action for execution. Use { agent, task? } only for one child; use workflowScript for multi-step or parallel work.",
+  "workflowScript means exactly one top-level subagent tool call with async:true. Inside it, use runs.run/runs.all to launch children; do not make another top-level subagent call for those children.",
+  WORKFLOW_SCRIPT_PORTABILITY_GUIDANCE,
+  WORKFLOW_LANES_GUIDANCE,
+  WORKFLOW_HOST_GUIDANCE,
+  WORKFLOW_RESUME_KEY_GUIDANCE,
+  WORKFLOW_OUTPUT_BINDING_GUIDANCE,
+  "For ordinary parallel work, use await runs.all([{key,agent,task}, ...]); it resolves to an ordered array, not a key map, so use results[0], destructuring, or results.map(...), not results.<key>. Do not read .output from unawaited runs.run launches. Stored runs.run promises are only for advanced rolling fanout and each must later be observed with direct await, Promise.race, or Promise.all.",
+  "Keep one writer per cwd/worktree unless writers run in isolated worktrees.",
+  `To pass an explicit model to a child, first call { action: "models" } and copy an exact provider/id (e.g. provider/model-id); bare ids resolve only when unique in the registry, and agent names (gpt-pro, advisor) are not model ids. Set per-run thinking with a suffix on the model string (e.g. provider/model-id:high; off/minimal/low/medium/high/xhigh/max); the suffix wins over the agent's thinking default. The thinking field only applies to action='watchdog.configure' and is ignored on dispatch.`,
+  EXTERNAL_CLI_RUNNER_GUIDANCE,
+  "Use guide or the dm-subagents skill for advanced scheduling, missions, steering, and retention."
+];
 export const SUBAGENT_SAFETY_GUIDANCE = `SAFETY-CRITICAL SUBAGENT GUIDANCE:
-• Use { action: "list" } before execution and only run executable/non-disabled agents or chains.
-• Keep execution and management separate: omit action for SINGLE/PARALLEL/CHAIN execution; use action only for list/get/models/create/update/delete/status/interrupt/resume/append-step/doctor.
-• Async/background runs: launch with async:true only when work can proceed independently. Do not sleep or poll status just to wait; if this turn must block, use the wait tool. Otherwise continue useful work or respond and let completion notifications arrive.
-• Child-safety boundary: ordinary child subagents are not orchestrators and must not run subagents. Only explicitly configured fanout children may use the child-safe subagent tool, still bounded by depth/session limits.
-• Writing/review safety: keep one writer for the same cwd/worktree. Use fresh-context read-only reviewers/validators for independent review, then have the parent synthesize and apply fixes as the sole writer unless an isolated worktree was intentionally requested.
-• Artifacts/status essentials: chain outputs live under {chain_dir}; async runs expose asyncId/asyncDir with status.json, events.jsonl, output logs, and status via { action: "status", id }. Include output paths and residual risks when reporting results.`;
-export const FULL_SUBAGENT_TOOL_DESCRIPTION = `Delegate to subagents or manage agent definitions.
+• Use { action: "list" } before execution and only run executable/non-disabled agents.
+• Keep execution and management separate: omit action for structured single-child or workflowScript execution; use action only for management/control.
+• Async/background runs are the normal default unless config sets asyncByDefault:false; set async:true explicitly when async behavior matters. Use async:false only when the parent must block until completion. Async mode still shows progress. Final reviews and gate checks stay async; needing a result is not a blocking reason. After an async launch, continue independent work only until its next dependency barrier; consume the result before work that depends on it. Ordinary async subagents notify this session natively, so return control and do not call bg_wait merely to get a completion wake. Do not sleep or poll status just to wait; use bg_wait only for provider, detached, or other background work without a native notification when this turn must receive its result.
+• ${WORKFLOW_RESUME_KEY_GUIDANCE}
+• ${WORKFLOW_OUTPUT_BINDING_GUIDANCE}
+• ${WORKFLOW_HOST_GUIDANCE}
+• Ordinary child subagents are not orchestrators. Only explicitly configured fanout children may use the child-safe subagent tool, still bounded by depth/session limits.
+• Oracle/advisor consultations should use supervisor dialogue for material unknowns when available; request one-shot only when desired.
+• Keep one writer for the same cwd/worktree. Use fresh-context read-only reviewers for independent review, then have the parent synthesize and apply fixes.
+• Async runs expose asyncId/asyncDir with status.json, events.jsonl, output logs, status via { action: "status", id }, and lifecycle diagnostics via { action: "debug.run", id }. Include output paths and residual risks when reporting results.`;
+export const FULL_SUBAGENT_TOOL_DESCRIPTION = `Run one child with { agent, task? }; use { workflowScript } for inline orchestration or { workflowScriptPath } to load it from the request cwd. The script inputs are mutually exclusive. Omit action for execution. Use action only for management/control actions.
 
-EXECUTION (use exactly ONE mode):
-• Before executing, use { action: "list" } to inspect configured agents/chains. Only execute agents listed as executable/non-disabled.
-• SINGLE: { agent, task? } - one task; omit task for self-contained agents
-• CHAIN: { chain: [{agent:"agent-a"}, {parallel:[{agent:"agent-b",count:3}]}] } - sequential pipeline with optional parallel fan-out
-• PARALLEL: { tasks: [{agent,task,count?,output?,reads?,progress?}, ...], concurrency?: number, worktree?: true } - concurrent execution (worktree: isolate each task in a git worktree)
-• Optional context: { context: "fresh" | "fork" } (explicit value overrides every child; when omitted, each requested agent uses its own defaultContext, otherwise "fresh"; inspect agent defaults via { action: "list" })
-• Optional timeout: { timeoutMs } or { maxRuntimeMs } sets a run-level max runtime for foreground and async/background runs
-• If { action: "list" } shows proactive skill subagent suggestions, consider a small fresh-context fanout for broad tasks where one of those skills would materially help
+EXECUTION:
+• ${EXTERNAL_CLI_RUNNER_GUIDANCE}
+• Before executing, use { action: "list" } and run only executable/non-disabled configured agents.
+• When passing an explicit model to a child (on the call or a runs.run/runs.all item), first call { action: "models" } and copy an exact provider/id; bare ids resolve only when unique in the registry, and agent names (e.g. gpt-pro, advisor) are not model ids. Set per-run thinking with a suffix on the model string (e.g. provider/id:high; off/minimal/low/medium/high/xhigh/max); the suffix wins over the agent's thinking default. The thinking field only applies to action='watchdog.configure' and is ignored on dispatch.
+• SINGLE CHILD: { agent:"worker", task:"..." }. This structured form starts exactly one direct child. Fields such as model, context, cwd, worktree, output, budgets, acceptance, and async apply to that child. Do not combine agent/task with action, workflowScript, or workflowScriptPath.
+• WORKFLOW SCRIPT: { workflowScript: "return runs.run('main', {agent:'worker', task:'...'})" }. Use stable-key runs.run for one child and await runs.all([{key,agent,task}, ...]) for ordinary parallel children. runs.all resolves to an ordered array, not a key map, so use results[0], array destructuring, or results.map((result) => result.output), not results.<key>. Do not read .output from unawaited runs.run launches. Stored runs.run promises are only for advanced rolling fanout and each must later be observed with direct await, Promise.race, or Promise.all. Ordinary JavaScript provides sequence, branching, filtering, retries, and aggregation. workflowScript is an ordinary JavaScript statement body, so use an explicit return for a useful result. Use top-level await, plain helper functions, or explicit Promise chains; nested async function, arrow, and method helpers are rejected. For task text with Markdown fences or shell blocks, build quoted lines instead of nesting raw template literals: \`const task=["Run:","\`\`\`bash","npm test","\`\`\`"].join("\\n")\`. Scripts normally start async unless config sets asyncByDefault:false; set async:true explicitly when async behavior matters. Pass async:false only when the parent must block until completion, never for final reviews or gates. Same-repo blocking workflows default to a live in-chat card; explicit live-card requires same-repository async:false, so async workflows should omit chatProgress or use auto/off. Workflow-level child controls default onto each runs.run launch, and explicit child fields override them. Use {action:"children.list"} to list recent retained workflow children with resumable/not-resumable reasons. Resume only rows reported resumable. For a simple follow-up or implementation challenge, use {action:"resume", id:"run-id", message:"..."}. Resume keeps the stored agent/model/tool contract. If no resumable child is listed, launch a same-role fallback challenge and label it as fallback. Inside workflowScript, continue one with runs.run(key, {resume:"run-id", task:"follow-up"}); workflow resumes wait for completed output, and loops must continue from each latest returned runId. Await runs.steer(key, message, {mode?, index?, ackTimeoutMs?}) to guide a prior keyed child without exposing its run id; receipts are queued, delivered, missed, or failed. Always await or return runs.steer. For repository mutation lanes, set worktree:true on the workflow or individual runs.run/runs.all item for managed isolation; each parallel child gets a separate worktree and handoff artifact. A workflow usageBudget is enforced once across the workflow. Available globals are runs.run, runs.all, runs.steer, runs.status, runs.ref/refs, emit, console, and standard JavaScript only. Workflows get async state.get(key) and state.set(key, JSONValue) through their automatic or explicit mission; mission:false workflows do not have a state global. Scripts cannot access filesystem, shell, arbitrary DM tools, or host globals.
+• ${WORKFLOW_LANES_GUIDANCE}
+• FILE SCRIPT: { workflowScriptPath:"workflows/review.js" }. Relative paths resolve against the request cwd. The host reads the file before the filesystem-free workflow sandbox starts. Do not combine this field with workflowScript.
+• Sequential example: { workflowScript: "const a = await runs.run('analyze', {agent:'agent-a', task:'Analyze the request'}); return (await runs.run('plan', {agent:'agent-b', task:'Plan from: '+a.output})).output" }
+• Parallel example: { workflowScript: "const [a,b] = await runs.all([{key:'correctness',agent:'agent-a',task:'Review correctness'},{key:'tests',agent:'agent-b',task:'Review tests'}]); return {correctness:a.output,tests:b.output}" }
+• Optional context is "fresh", "fork", or "profile". profile requires the selected agent's declared defaultContext and ignores config defaultSubagentContext. Explicit fresh/fork wins. When omitted, config defaultSubagentContext wins over agent defaultContext. Config forkContext can summarize transcript overflow with stable recovery refs before spawn without adding another public context value. timeoutMs/maxRuntimeMs apply to foreground and async workflows; foreground workflows default to 30 minutes and async workflows have no default timeout. Omit acceptance for reviewer/read-only calls; evidence levels end at verified, and acceptance.review.required requests independent writer review.
+• Durable mission attachment is automatic by default. Use missionId to attach an existing mission, mission:{...} to override auto-create, or mission:false for ephemeral work. A mission object needs exactly one non-empty title or summary; objective and labels are optional. goal may only be true and requires budget:{tokens}.
 
-CHAIN TEMPLATE VARIABLES (use in task strings):
-• {task} - The original task/request from the user
-• {previous} - Text response from the previous step (empty for first step)
-• {chain_dir} - Shared directory for chain files (e.g., <tmpdir>/dm-subagents-<scope>/chain-runs/abc123/)
-
-Example: { chain: [{agent:"agent-a", task:"Analyze {task}"}, {agent:"agent-b", task:"Plan based on {previous}"}] }
-
-MANAGEMENT (use action field, omit agent/task/chain/tasks):
-• { action: "list" } - discover executable agents/chains
-• { action: "get", agent: "name" } - full detail; packaged agents use dotted runtime names like "package.agent"
-• { action: "models", agent?: "name" } - show the runtime-loaded builtin subagent model mapping, optionally filtered to one builtin
-• { action: "create", config: { name: "custom-agent", package: "code-analysis", systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, defaultContext, ... } }
-• { action: "update", agent: "code-analysis.custom-agent", config: { package: "analysis", ... } } - merge
-• { action: "delete", agent: "code-analysis.custom-agent" }
-• { action: "eject", agent: "reviewer", agentScope?: "user" | "project" } - copy a bundled/package agent to user/project scope as an editable custom file that shadows the original (default scope: user)
-• { action: "disable", agent: "reviewer", agentScope?: "user" | "project" } - hide any agent from runtime discovery via a reversible settings override (default scope: user)
-• { action: "enable", agent: "reviewer", agentScope?: "user" | "project" } - remove a disabled override and restore discovery
-• { action: "reset", agent: "reviewer", agentScope?: "user" | "project" } - delete the scope's custom agent file and/or settings override, restoring the bundled default
-• Use chainName for chain operations; packaged chains also use dotted runtime names
-
-CONTROL:
-• { action: "status", id: "..." } - inspect an async/background run by id or prefix
-• { action: "status", view: "fleet" } - read-only active foreground/async fleet view with transcript commands
-• { action: "status", id: "...", view: "transcript", index?: 0, lines?: 80 } - tail a run or child output/session transcript
-• { action: "interrupt", id?: "..." } - soft-interrupt the current child turn and leave the run paused
-• { action: "resume", id: "...", message: "...", index?: 0 } - interrupt then follow up with a live async child, or revive a completed async/foreground child from its session
-• { action: "steer", id: "...", message: "...", index?: 0 } - queue non-terminal guidance for a live/queued async DM child when supported
-• { action: "append-step", id: "...", chain: [{agent:"agent-c", task:"Use {previous}"}] } - append one step to the tail of a running async chain
-
-SCHEDULE (opt-in; requires { "scheduledRuns": { "enabled": true } } in config.json):
-• { action: "schedule", agent, task?, schedule: "+10m" | "2030-01-01T09:00:00Z", scheduleName? } - defer a subagent launch until a future time. Also accepts tasks[] or chain[]. Scheduled runs always launch async with fresh context; they become normal tracked async runs once they fire. Only schedule explicit delayed runs the user asked for.
-• { action: "schedule-list" } - list scheduled runs for this session
-• { action: "schedule-status", id: "..." } - inspect one scheduled run
-• { action: "schedule-cancel", id: "..." } - cancel a scheduled run before it fires
-
-DIAGNOSTICS:
-• { action: "doctor" } - read-only report for runtime paths, discovery, sessions, and intercom
+MANAGEMENT / CONTROL (use action; omit execution fields):
+• validate checks workflowScript or workflowScriptPath syntax and statically decidable structure without launching children. list, get, models, guide, children.list, create, update, delete, eject, disable, enable, reset, status, debug.run, doctor, grant-spawn-budget, worktree.discard, worktree.cleanup (plan-only), lane.status, lane.recordMerge, lane.recordSupersession, refine/refine.show/refine.rollback, mission.create/list/show/update/resolve-decision/attach-run/close, inspector.open/status/close, project.open/status/close, and watchdog actions remain available. Use {action:"guide", topic:"overview"} for packaged current-version help; topics are overview, workflows, agents, missions, observability, tool-reference, configuration, models, watchdog, and extension-api.
+• status, interrupt, stop, resume, and steer manage live or persisted runs. Use status view:"fleet" for an overview or view:"transcript" with id and optional index to tail output.
+• Create durable project schedules with { action:"schedule.create", id?, name?, at:"+10m" | ISO, workflowScript:"return runs.run('main', {agent:'worker', task:'...'})" }, or use workflowScriptPath instead. Manage them with schedule.list/show/history/pause/resume/run/run-due/delete. This first slice supports fixed intervals; calendar schedules and schedule mission attachment are deferred.
 
 ${SUBAGENT_SAFETY_GUIDANCE}`;
-export const COMPACT_SUBAGENT_TOOL_DESCRIPTION = `Delegate to subagents or manage definitions. Use exactly one mode per call.
+export const COMPACT_SUBAGENT_TOOL_DESCRIPTION = `Run one child with { agent, task? }; use { workflowScript } for inline orchestration or { workflowScriptPath } to load it from the request cwd. The script inputs are mutually exclusive. Omit action for execution. Use action only for management/control actions.
 
 EXECUTE:
-• Before execution, call { action: "list" }; run only executable/non-disabled configured agents/chains.
-• SINGLE {agent, task?}; PARALLEL {tasks:[{agent,task,count?,output?,reads?,progress?}], concurrency?, worktree?}; CHAIN {chain:[{agent,task?},{parallel:[...]}]}.
-• context can be "fresh" or "fork"; omitted uses each agent defaultContext, otherwise fresh. timeoutMs/maxRuntimeMs apply to foreground and async/background runs.
-• Chain templates may use {task}, {previous}, {chain_dir}, and named outputs. Parallel worktree isolation requires a clean git repo.
-• If list shows proactive skill subagent suggestions, use a small fresh-context fanout only when the task is broad enough.
+• ${EXTERNAL_CLI_RUNNER_GUIDANCE}
+• Call { action:"list" } first and use only executable/non-disabled agents.
+• Passing an explicit model? Call {action:"models"} first and copy an exact provider/id; bare ids resolve only when unique in the registry; agent names (e.g. gpt-pro, advisor) are not model ids. Per-run thinking is a suffix on the model string (provider/id:high; off/minimal/low/medium/high/xhigh/max), and the suffix wins over the agent's thinking default; the thinking field only applies to action='watchdog.configure' and is ignored on dispatch.
+• SINGLE {agent:"worker",task:"..."} starts exactly one direct child. Fields apply to that child. Do not combine agent/task with action, workflowScript, or workflowScriptPath.
+• SCRIPT {workflowScript:"return runs.run('main', {agent:'worker', task:'...'})"}. Use stable-key runs.run for one child and await runs.all([{key,agent,task}, ...]) for ordinary parallel work. runs.all resolves to an ordered array, not a key map; use results[0], destructuring, or results.map(...), not results.<key>. Do not read .output from unawaited runs.run launches. Stored runs.run promises are only for advanced rolling fanout and each must later be observed with direct await, Promise.race, or Promise.all. Await runs.steer(key,message,options?) to guide a prior keyed child; it returns queued, delivered, missed, or failed and never accepts a raw run id. Always await or return steering calls. Use {action:"children.list"} for recent retained workflow children and resume only rows reported resumable. Use {action:"resume",id:"run-id",message:"..."} for a simple follow-up or challenge; resume keeps the stored agent/model/tool contract. If none is resumable, launch a same-role fallback challenge and label it as fallback. Inside workflowScript use runs.run(key,{resume:"run-id",task:"follow-up"}) when the script must wait for completion and continue from the latest returned runId. Workflows get async state.get/state.set through their automatic or explicit mission; mission:false does not. Scripts are ordinary JavaScript statement bodies; use explicit return for a useful result. Use top-level await, plain helper functions, or explicit Promise chains; nested async function, arrow, and method helpers are rejected. For task text with Markdown fences or shell blocks, build quoted lines instead of nesting raw template literals: \`const task=["Run:","\`\`\`bash","npm test","\`\`\`"].join("\\n")\`. Use JavaScript for sequence, branching, retries, and aggregation. For repository mutation lanes, use worktree:true on the workflow or runs.run/runs.all item for managed isolation. Scripts normally start async unless config sets asyncByDefault:false; set async:true explicitly when async behavior matters. async:false blocks the parent until completion and auto-enables a same-repo live chat card unless chatProgress is off; explicit live-card requires same-repository async:false, so async workflows should omit chatProgress or use auto/off.
+• ${WORKFLOW_LANES_GUIDANCE}
+• FILE SCRIPT {workflowScriptPath:"workflows/review.js"} loads the script on the host relative to the request cwd before sandbox execution. Do not combine it with workflowScript.
+• Example: {workflowScript:"const [a,b]=await runs.all([{key:'a',agent:'agent-a',task:'Implement A',worktree:true},{key:'b',agent:'agent-b',task:'Implement B',worktree:true}]); return [a.output,b.output]"}
+• context can be fresh, fork, or profile. profile requires the selected agent's declared defaultContext and ignores defaultSubagentContext. Explicit fresh/fork wins; omitted context follows defaultSubagentContext before agent defaultContext. Config forkContext can summarize transcript overflow with stable recovery refs before spawn without adding another public context value. timeoutMs/maxRuntimeMs apply to foreground and async workflows; foreground workflows default to 30 minutes and async workflows have no default timeout. Omit acceptance for reviewer/read-only calls.
 
 MANAGE / CONTROL:
-• Use action without execution fields: list, get, models, create, update, delete, eject, disable, enable, reset, doctor.
-• Async control actions: status, interrupt, resume, steer, append-step. Use status view:"fleet" for active-run overview, view:"transcript" to tail child output, and steer for non-terminal live guidance. Use id/runId prefixes carefully; use index for a specific child.
-• Opt-in schedule actions: schedule, schedule-list, schedule-status, schedule-cancel. Schedule only explicit delayed runs the user asked for.
+• Use action without execution fields for list/get/models/guide/authoring, refine/refine.show/refine.rollback, mission, watchdog, status, interrupt, stop, resume, steer, worktree.cleanup (mode:'plan' only), script-only scheduling, diagnostics, and other management actions. guide reads shipped current-version docs by topic.
+• A mission object needs exactly one non-empty title or summary; objective and labels are optional. goal may only be true and requires budget:{tokens}.
 
-ASYNC / WAIT:
-• async:true detaches background work. Do not sleep or poll just to wait; use the wait tool only when this turn must block. Otherwise continue useful work or respond and let completion notifications arrive.
-• Status and artifacts live under asyncId/asyncDir with status.json, events.jsonl, output logs, session files, and { action:"status", id:"..." }.
-
-SAFETY:
-• Ordinary child subagents are not orchestrators and must not run subagents. Only explicit fanout children may use child-safe subagent, still bounded by depth/session limits.
-• Keep one writer per cwd/worktree. Use fresh read-only review/validation fanout, then synthesize and apply fixes from the parent unless isolated worktrees were intentionally requested.`;
+ASYNC / SAFETY:
+• Omitted async follows asyncByDefault config; set async:true explicitly when async behavior matters. Continue independent work only until its next dependency barrier; consume the result before work that depends on it. Ordinary async subagents notify this session natively, so return control and do not call bg_wait merely to get a completion wake. Do not sleep or poll merely to wait; use bg_wait only for provider, detached, or other background work without a native notification when this turn must receive its result.
+• ${WORKFLOW_RESUME_KEY_GUIDANCE}
+• ${WORKFLOW_OUTPUT_BINDING_GUIDANCE}
+• ${WORKFLOW_HOST_GUIDANCE}
+• Ordinary children are not orchestrators. Keep one writer per cwd/worktree and use fresh read-only reviewers for independent checks.
+• Oracle/advisor consultations use available supervisor dialogue for material unknowns; request one-shot when desired.
+• Status and artifacts live under asyncId/asyncDir with status.json, events.jsonl, output logs, and {action:"status",id:"..."}.`;
 function isToolDescriptionMode(value) {
   return value === "full" || value === "compact" || value === "custom";
 }
 function warn(options, message) {
   (options?.warn ?? console.warn)(`[dm-subagents] ${message}`);
 }
+export function buildSubagentToolPromptMetadata(config = {}) {
+  if (config.toolDescriptionMode !== undefined)
+    return {};
+  return {
+    promptSnippet: SUBAGENT_TOOL_PROMPT_SNIPPET,
+    promptGuidelines: SUBAGENT_TOOL_PROMPT_GUIDELINES
+  };
+}
 export function resolveToolDescriptionMode(config, options) {
   const mode = config.toolDescriptionMode;
   if (mode === undefined)
@@ -172,14 +183,21 @@ function withMandatorySafetyGuidance(description) {
 ${SUBAGENT_SAFETY_GUIDANCE}` : SUBAGENT_SAFETY_GUIDANCE;
 }
 export function buildSubagentToolDescription(config = {}, options) {
+  if (config.toolDescriptionMode === undefined)
+    return DEFAULT_SUBAGENT_TOOL_DESCRIPTION;
   const mode = resolveToolDescriptionMode(config, options);
+  let description;
   if (mode === "compact")
-    return COMPACT_SUBAGENT_TOOL_DESCRIPTION;
-  if (mode === "custom") {
+    description = COMPACT_SUBAGENT_TOOL_DESCRIPTION;
+  else if (mode === "custom") {
     const custom = loadCustomToolDescription(options);
     if (custom)
-      return withMandatorySafetyGuidance(custom);
-    warn(options, `${CUSTOM_TOOL_DESCRIPTION_FILE} was not found or valid for toolDescriptionMode "custom"; using full description.`);
-  }
-  return FULL_SUBAGENT_TOOL_DESCRIPTION;
+      description = withMandatorySafetyGuidance(custom);
+    else {
+      warn(options, `${CUSTOM_TOOL_DESCRIPTION_FILE} was not found or valid for toolDescriptionMode "custom"; using full description.`);
+      description = FULL_SUBAGENT_TOOL_DESCRIPTION;
+    }
+  } else
+    description = FULL_SUBAGENT_TOOL_DESCRIPTION;
+  return description;
 }

package/extensions/dm-subagents/src/extension/tool-result.js

@@ -0,0 +1,7 @@
+export function finalizeToolResult(result) {
+  if (result.isError !== true)
+    return result;
+  const message = result.content.flatMap((item) => item.type === "text" && typeof item.text === "string" ? [item.text] : []).join(`
+`).trim();
+  throw new Error(message || "dm-subagents reported a logical tool failure.");
+}

package/extensions/dm-subagents/src/inspectors/herdr/actions.js

@@ -0,0 +1,218 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readMissionBinding } from "../../missions/lifecycle.js";
+import { listMissions, missionRecordPath, resolveMissionStoreLocation } from "../../missions/store.js";
+import { resolveAuthorityDecision } from "../../policy/authority.js";
+import { writeAtomicJson } from "../../shared/atomic-json.js";
+import { DIRS } from "../../shared/types.js";
+import { readStatus } from "../../shared/utils.js";
+import { resolveSubagentRunId } from "../../runs/background/run-id-resolver.js";
+import { resolveNodeExecutable } from "../../shared/node-executable.js";
+import { createHerdrClient, detectHerdr } from "./client.js";
+import { encodeSessionRoots } from "./session-roots-codec.js";
+import { formatShellCommand } from "./shell-command.js";
+export const HERDR_INSPECTOR_ACTIONS = ["inspector.open", "inspector.status", "inspector.close"];
+function result(text, isError = false) {
+  return { content: [{ type: "text", text }], ...isError ? { isError: true } : {}, details: { mode: "management", results: [] } };
+}
+function formatHerdrError(input) {
+  return `Herdr inspector error (${input.code}): ${input.message}`;
+}
+function bindingPath(asyncDir, index) {
+  return path.join(asyncDir, "inspectors", `herdr${index === undefined ? "" : `-${index}`}.json`);
+}
+function parseBinding(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return;
+  const input = value;
+  if (input.schemaVersion !== 1 || input.kind !== "herdr-inspector")
+    return;
+  if (typeof input.runId !== "string" || typeof input.asyncDir !== "string" || typeof input.paneId !== "string" || typeof input.openedAt !== "string" || typeof input.command !== "string")
+    return;
+  if (input.childIndex !== undefined && (!Number.isInteger(input.childIndex) || input.childIndex < 0))
+    return;
+  return input;
+}
+export function readHerdrInspectorBinding(asyncDir, index) {
+  try {
+    return parseBinding(JSON.parse(fs.readFileSync(bindingPath(asyncDir, index), "utf-8")));
+  } catch {
+    return;
+  }
+}
+function extractPaneId(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return;
+  const record = value;
+  const pane = record.pane && typeof record.pane === "object" && !Array.isArray(record.pane) ? record.pane : record;
+  for (const key of ["pane_id", "paneId", "id"])
+    if (typeof pane[key] === "string")
+      return pane[key];
+  return;
+}
+function inspectorCommand(input) {
+  const args = [input.runnerPath, "--async-dir", input.asyncDir, "--run-id", input.runId, "--allow-steer", String(input.allowSteer), "--allow-stop", String(input.allowStop), "--session-roots", encodeSessionRoots(input.sessionRoots)];
+  if (input.index !== undefined)
+    args.push("--index", String(input.index));
+  if (input.missionPath)
+    args.push("--mission-path", input.missionPath);
+  return formatShellCommand(resolveNodeExecutable(), args);
+}
+function missionForRun(asyncDir, cwd, config, runId) {
+  try {
+    const binding = readMissionBinding(asyncDir);
+    if (binding)
+      return { id: binding.missionId, path: missionRecordPath(binding.location, binding.missionId) };
+    const location = resolveMissionStoreLocation({ projectRoot: cwd, ...config ? { config } : {} });
+    const mission = listMissions(location).records.find((record) => record.runs.some((run) => run.runId === runId));
+    return mission ? { id: mission.id, path: missionRecordPath(location, mission.id) } : undefined;
+  } catch {
+    return;
+  }
+}
+function pathWithin(base, candidate) {
+  const resolvedBase = path.resolve(base);
+  const resolvedCandidate = path.resolve(candidate);
+  return resolvedCandidate === resolvedBase || resolvedCandidate.startsWith(`${resolvedBase}${path.sep}`);
+}
+function herdrSessionRoots(target, deps) {
+  const roots = deps.sessionRoots ?? deps.state?.trustedSessionRoots ?? [];
+  const job = deps.state?.asyncJobs.get(target.runId) ?? deps.state?.fleetJobs?.get(target.runId);
+  return [...new Set([...roots, ...job?.sessionRoot ? [job.sessionRoot] : []])];
+}
+function isTrustedAsyncDir(asyncDir, deps) {
+  try {
+    if (fs.lstatSync(asyncDir).isSymbolicLink() || !fs.statSync(asyncDir).isDirectory())
+      return false;
+    const realDir = fs.realpathSync(asyncDir);
+    const registered = [...deps.state?.asyncJobs.values() ?? []].some((job) => {
+      try {
+        return fs.realpathSync(job.asyncDir) === realDir;
+      } catch {
+        return false;
+      }
+    });
+    if (registered)
+      return true;
+    const root = deps.asyncDirRoot ?? DIRS.async;
+    if (!fs.existsSync(root) || !pathWithin(root, asyncDir))
+      return false;
+    return pathWithin(fs.realpathSync(root), realDir);
+  } catch {
+    return false;
+  }
+}
+function resolveAsyncTarget(params, deps) {
+  const requestedId = params.id ?? params.runId;
+  if (params.dir) {
+    const asyncDir = path.resolve(params.dir);
+    if (!isTrustedAsyncDir(asyncDir, deps))
+      return { error: `Async run directory '${asyncDir}' is outside trusted run roots.` };
+    const status = readStatus(asyncDir);
+    if (!status)
+      return { error: `No async run status found in '${asyncDir}'.` };
+    if (requestedId && requestedId !== status.runId && !status.runId.startsWith(requestedId))
+      return { error: `Run '${requestedId}' does not match status run '${status.runId}'.` };
+    return { runId: status.runId, asyncDir };
+  }
+  if (!requestedId)
+    return { error: "Herdr inspector actions require id or dir." };
+  try {
+    const resolved = resolveSubagentRunId(requestedId, { state: deps.state, asyncDirRoot: deps.asyncDirRoot ?? DIRS.async, resultsDir: deps.resultsDir ?? DIRS.results });
+    if (!resolved)
+      return { error: `No subagent run found for '${requestedId}'.` };
+    if (resolved.kind !== "async" || !resolved.location.asyncDir)
+      return { error: `Run '${resolved.id}' is not an inspectable async run with lifecycle artifacts.` };
+    return { runId: resolved.id, asyncDir: resolved.location.asyncDir };
+  } catch (cause) {
+    return { error: cause instanceof Error ? cause.message : String(cause) };
+  }
+}
+async function paneExists(client, paneId, signal) {
+  return client.run(["pane", "get", paneId], { timeoutMs: 5000, signal });
+}
+export async function handleHerdrInspectorAction(action, params, deps) {
+  const target = resolveAsyncTarget(params, deps);
+  if ("error" in target)
+    return result(target.error, true);
+  const status = readStatus(target.asyncDir);
+  if (!status)
+    return result(`No lifecycle status exists for async run '${target.runId}'.`, true);
+  if (params.index !== undefined && (params.index < 0 || params.index >= (status.steps?.length ?? 0))) {
+    return result(`Async run '${target.runId}' has ${status.steps?.length ?? 0} children. Index ${params.index} is out of range.`, true);
+  }
+  const existing = readHerdrInspectorBinding(target.asyncDir, params.index);
+  const client = deps.client ?? createHerdrClient();
+  if (action === "inspector.status") {
+    if (!existing)
+      return result(`No Herdr inspector binding exists for async run ${target.runId}${params.index === undefined ? "" : ` child ${params.index}`}.`);
+    const live = await paneExists(client, existing.paneId, deps.signal);
+    if (live.ok === false)
+      return result(`${formatHerdrError(live.error)}
+Binding: ${bindingPath(target.asyncDir, params.index)}
+Run state remains authoritative: ${status.state}.`, true);
+    return result(`Herdr inspector ${existing.paneId} is open for async run ${target.runId}.
+Run state: ${status.state}
+Binding: ${bindingPath(target.asyncDir, params.index)}`);
+  }
+  if (action === "inspector.close") {
+    if (!existing)
+      return result(`No Herdr inspector binding exists for async run ${target.runId}.`);
+    const closed = await client.run(["pane", "close", existing.paneId], { timeoutMs: 1e4, signal: deps.signal });
+    if (closed.ok === false && closed.error.code !== "NOT_FOUND" && closed.error.code !== "PANE_GONE")
+      return result(formatHerdrError(closed.error), true);
+    fs.rmSync(bindingPath(target.asyncDir, params.index), { force: true });
+    return result(`Closed Herdr inspector pane ${existing.paneId} for async run ${target.runId}. The subagent run was not stopped.`);
+  }
+  const detected = await detectHerdr(client, deps.signal);
+  if (detected.ok === false)
+    return result(formatHerdrError(detected.error), true);
+  if (existing) {
+    const live = await paneExists(client, existing.paneId, deps.signal);
+    if (live.ok)
+      return result(`Herdr inspector pane ${existing.paneId} is already open for async run ${target.runId}.${params.focus ? " Herdr cannot refocus an arbitrary raw pane id; select it in the Herdr UI." : ""}`);
+  }
+  const splitArgs = ["pane", "split", "--current", "--direction", "right", "--cwd", status.cwd ?? deps.cwd];
+  splitArgs.push(params.focus === true ? "--focus" : "--no-focus");
+  const split = await client.run(splitArgs, { timeoutMs: 15000, signal: deps.signal });
+  if (split.ok === false)
+    return result(formatHerdrError(split.error), true);
+  const paneId = extractPaneId(split.data);
+  if (!paneId)
+    return result("Herdr inspector error (PANE_GONE): pane split returned no pane id.", true);
+  const mission = missionForRun(target.asyncDir, deps.cwd, deps.missions, target.runId);
+  const runnerPath = deps.runnerPath ?? fileURLToPath(new URL("../../../inspector-runner.mjs", import.meta.url));
+  const command = inspectorCommand({
+    runnerPath,
+    asyncDir: target.asyncDir,
+    runId: target.runId,
+    index: params.index,
+    missionPath: mission?.path,
+    allowSteer: resolveAuthorityDecision({ action: "steerRun", policy: deps.authorityPolicy }) === "auto",
+    allowStop: resolveAuthorityDecision({ action: "stopRun", policy: deps.authorityPolicy }) === "auto",
+    sessionRoots: herdrSessionRoots(target, deps)
+  });
+  const started = await client.run(["pane", "run", paneId, command], { timeoutMs: 15000, signal: deps.signal });
+  if (started.ok === false) {
+    await client.run(["pane", "close", paneId], { timeoutMs: 5000 });
+    return result(formatHerdrError(started.error), true);
+  }
+  const now = (deps.now?.() ?? new Date).toISOString();
+  const binding = {
+    schemaVersion: 1,
+    kind: "herdr-inspector",
+    runId: target.runId,
+    asyncDir: target.asyncDir,
+    ...params.index !== undefined ? { childIndex: params.index } : {},
+    ...mission ? { missionId: mission.id, missionPath: mission.path } : {},
+    paneId,
+    openedAt: now,
+    ...params.focus === true ? { lastFocusedAt: now } : {},
+    herdrVersion: detected.data.versionText,
+    command
+  };
+  writeAtomicJson(bindingPath(target.asyncDir, params.index), binding);
+  return result(`Opened read-only Herdr inspector pane ${paneId} for async run ${target.runId}. Closing the pane does not stop the run.
+Controls inside the pane: steer <message>, stop, status.`);
+}

package/extensions/dm-subagents/src/inspectors/herdr/client.js

@@ -0,0 +1,123 @@
+import { spawn } from "node:child_process";
+function error(code, message, details) {
+  return { ok: false, error: { code, message, ...details !== undefined ? { details } : {} } };
+}
+function parseLastJson(value) {
+  const trimmed = value.trim();
+  if (!trimmed)
+    return;
+  try {
+    return JSON.parse(trimmed);
+  } catch {}
+  for (const line of trimmed.split(/\r?\n/).reverse()) {
+    try {
+      return JSON.parse(line);
+    } catch {}
+  }
+  return;
+}
+function normalizeCode(raw) {
+  const code = String(raw ?? "").toLowerCase();
+  if (code.includes("timeout") || code.includes("timed_out"))
+    return "TIMEOUT";
+  if (code.includes("gone"))
+    return "PANE_GONE";
+  if (code.includes("not_found") || code.includes("not-found") || code === "no_such_pane")
+    return "NOT_FOUND";
+  return "VALIDATION_ERROR";
+}
+export function createHerdrClient(options = {}) {
+  const bin = options.bin ?? process.env.HERDR_BIN ?? "herdr";
+  const spawnImpl = options.spawn ?? spawn;
+  return {
+    run(args, runOptions = {}) {
+      return new Promise((resolve) => {
+        let child;
+        try {
+          child = spawnImpl(bin, args, { shell: false, windowsHide: true, env: process.env });
+        } catch (cause) {
+          const code = cause?.code;
+          resolve(error("HERDR_UNAVAILABLE", code === "ENOENT" ? "Herdr is not installed or is not on PATH. Install Herdr 0.7.5+ or set HERDR_BIN." : `Failed to start Herdr: ${cause instanceof Error ? cause.message : String(cause)}`));
+          return;
+        }
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const finish = (result) => {
+          if (settled)
+            return;
+          settled = true;
+          clearTimeout(timer);
+          runOptions.signal?.removeEventListener("abort", abort);
+          resolve(result);
+        };
+        const abort = () => {
+          try {
+            child.kill();
+          } catch {}
+          finish(error("TIMEOUT", `Herdr command '${args.join(" ")}' was aborted.`));
+        };
+        const timer = setTimeout(() => {
+          try {
+            child.kill();
+          } catch {}
+          finish(error("TIMEOUT", `Herdr command '${args.join(" ")}' timed out after ${runOptions.timeoutMs ?? 15000}ms.`));
+        }, runOptions.timeoutMs ?? 15000);
+        timer.unref?.();
+        if (runOptions.signal?.aborted)
+          abort();
+        else
+          runOptions.signal?.addEventListener("abort", abort, { once: true });
+        child.stdout?.on("data", (chunk) => {
+          stdout += chunk.toString();
+        });
+        child.stderr?.on("data", (chunk) => {
+          stderr += chunk.toString();
+        });
+        child.on("error", (cause) => {
+          const code = cause.code;
+          finish(error("HERDR_UNAVAILABLE", code === "ENOENT" ? "Herdr is not installed or is not on PATH. Install Herdr 0.7.5+ or set HERDR_BIN." : `Failed to run Herdr: ${cause.message}`));
+        });
+        child.on("close", (exitCode) => {
+          const parsed = parseLastJson(stdout) ?? (exitCode === 0 ? undefined : parseLastJson(stderr));
+          if (parsed && typeof parsed === "object" && !Array.isArray(parsed) && "error" in parsed) {
+            const raw = parsed.error;
+            finish(error(normalizeCode(raw?.code), String(raw?.message ?? "Herdr command failed."), raw));
+            return;
+          }
+          if (exitCode === 0) {
+            if (parsed !== undefined) {
+              const envelope = parsed;
+              finish({ ok: true, data: envelope.result ?? parsed });
+            } else if (runOptions.textOk)
+              finish({ ok: true, data: stdout.trim() });
+            else
+              finish({ ok: true, data: {} });
+            return;
+          }
+          const message = stderr.split(/\r?\n/).find((line) => line.trim())?.trim() ?? `Herdr exited with code ${exitCode}.`;
+          finish(error("VALIDATION_ERROR", message, { exitCode }));
+        });
+      });
+    }
+  };
+}
+export function parseHerdrVersion(value) {
+  const match = /(\d+)\.(\d+)\.(\d+)/.exec(value);
+  return match ? { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) } : undefined;
+}
+export function supportsRawPanes(version) {
+  return version.major > 0 || version.minor > 7 || version.minor === 7 && version.patch >= 5;
+}
+export async function detectHerdr(client, signal) {
+  const result = await client.run(["--version"], { timeoutMs: 3000, signal, textOk: true });
+  if (result.ok === false)
+    return result;
+  const versionText = typeof result.data === "string" ? result.data : JSON.stringify(result.data);
+  const version = parseHerdrVersion(versionText);
+  if (!version)
+    return error("VALIDATION_ERROR", `Could not parse the Herdr version from '${versionText}'.`);
+  if (!supportsRawPanes(version))
+    return error("HERDR_UNSUPPORTED_VERSION", `Herdr ${versionText} does not support raw inspector panes. Upgrade to Herdr 0.7.5 or newer.`);
+  return { ok: true, data: { version, versionText } };
+}