Function buildTaskToolDescription

src/common/utils/tools/toolDefinitions.ts:295–330

(runtimeMode: RuntimeMode | undefined)

}

export function buildTaskToolDescription(runtimeMode: RuntimeMode | undefined): string {
  const isolationGuidance = runtimeModeSupportsSharedTaskWorkspace(runtimeMode)
    ? "\n\nWorkspace isolation: by default each sub-agent runs in a forked copy of this workspace. " +
      'On this runtime you may pass isolation: "none" to run the sub-agent directly in this workspace\'s ' +
      "checkout (shared working tree, including uncommitted changes), skipping the fork + init overhead. " +
      'Reserve isolation: "none" for read-only analysis (e.g. the explore agent) or when you instruct the ' +
      "sub-agent to avoid editing shared files, since concurrent edits to the same files are possible. "
    : "";
  return (
    "Spawn a sub-agent task (child workspace). " +
    "\n\nIMPORTANT: Whether a sub-agent can see uncommitted changes depends on the runtime. " +
    `${getTaskRuntimeVisibilityGuidance(runtimeMode)} ` +
    "\n\nProvide agentId (preferred) or subagent_type, prompt, title, run_in_background, and optional n or variants. " +
    `Use n when you want several agents to try the same prompt independently. Use variants when you want several agents to run the same prompt template with a different ${TASK_VARIANT_PLACEHOLDER} substituted into each run. ` +
    "Examples: solve GitHub issues 45, 32, and 69 with one shared issue-solving template; investigate a regression across commit windows like A..B and B..C with one shared investigation template; or split a review into frontend/backend/tests/docs lanes with one shared review template. " +
    `For variants, keep the shared template in the prompt and put the per-lane difference into ${TASK_VARIANT_PLACEHOLDER}. ` +
    "n and variants are mutually exclusive; omit both for a single task. Leave n and variants unset unless the developer explicitly asks for parallel sibling tasks, and prefer non-interfering sub-agents for grouped runs (for example read-only agents like explore). " +
    "\n\nWhen the user explicitly asks for best-of-n work, the parent should begin with light preliminary analysis to extract shared context, constraints, or evaluation criteria that would otherwise be duplicated across children. " +
    "Keep that pre-work lightweight: frame the task and provide useful starting points, but do not pre-solve the problem or over-constrain how the children reason about it. Then delegate the substantive analysis to the spawned sub-agents. " +
    "Do not also do a full parallel analysis in the parent. Call task_await when you are ready to act on child output; do not await reflexively just because tasks are running. " +
    "task_await returns as soon as the first awaited task completes by default (min_completed), so you can start dependent work on each result as it lands instead of blocking on the whole batch; for best-of-N synthesis that must compare every candidate, pass min_completed equal to the batch size (or use a foreground grouped spawn, below). " +
    "\n\nWhen delegating, include a compact task brief (Task / Background / Scope / Starting points / Acceptance / Deliverables / Constraints). " +
    "For now, persisted sub-agent goals are not supported; pass sub-agent objectives, success criteria, and deliverables directly in the prompt. " +
    "Sub-agents observe the same system instructions as the parent (project/global AGENTS.md and custom instructions), so do not restate that shared context in the prompt; spend the prompt on task-specific information the sub-agent cannot infer from those instructions. " +
    "Caveat: instruction files are read from the child's checkout, so uncommitted AGENTS.md edits in the parent follow the same runtime visibility rules above — commit them first or pass the relevant guidance in the prompt. " +
    "Avoid telling the sub-agent to read your plan file; child workspaces do not automatically have access to it. " +
    "\n\nIf run_in_background is false, waits for the sub-agent to finish and returns the completed report. When grouped sibling tasks are requested via n or variants, the completed result includes one report per spawned task. " +
    "If the foreground wait times out, returns queued/starting/running task metadata with a note (the task continues running); use task_await to monitor progress. " +
    "If run_in_background is true, returns immediately with queued/starting/running task metadata and the task runs non-blocking: you may end your turn without awaiting it, and Mux wakes this workspace when the task reaches a terminal state so you can integrate its result. Use task_await only when the current request depends on the output before you can answer, or to inspect progress. " +
    "Prefer run_in_background: false when spawning a single task — it is equivalent to spawning background + immediately awaiting, but saves a round-trip. " +
    "Use run_in_background: true when launching multiple tasks in parallel so you can act on each as it completes via task_await (which returns on the first completion by default); a foreground grouped spawn (run_in_background: false) instead blocks until every sibling finishes and returns all reports at once. " +
    "Do not call task_await in the same parallel tool-call batch; wait for the returned task metadata first. " +
    isolationGuidance +
    "Use the bash tool to run shell commands."
  );
}

const WorkspaceTaskKindSchema = z.enum(["subagent", "workspace"]);
const WorkspaceTaskModeSchema = z.enum(["new", "fork", "existing"]);