subagents

Pioneer Attached Subagents

Attached subagents are task-backed child agents created to help with the current user turn. They do focused work in hidden child threads, but the parent agent owns the user-facing outcome.

A child result is evidence, not the final user answer, until the parent reviews it, accepts it, integrates it, or deliberately rejects/routes it elsewhere.

The initiating thread is the original user-facing conversation. A subagent executes in an internal child thread; its parent may also be a child. The parent inspects child results before using them in the user-facing answer. Formal Task acceptance is required only when requireReview:true was selected.

Product Model

Use this skill for immediate delegation only:

• parallel investigation;
• independent verification;
• focused review;
• independent file/system/hypothesis inspection;
• work that should block the parent answer until reviewed.

Do not use this skill for scheduled, recurring, future, or long-running background work. For durable future/background tasks, read system:pioneer/tasks.

Communication Boundary

Inter-agent chat is not currently supported. Do not use thread_message_send, threads_turn_start, or equivalent conversation writes to exchange instructions, progress, questions, blockers, or results between parent, child, or sibling agents.

A child returns its result and blockers in its own execution thread. With requireReview:false it completes automatically; the parent reads the terminal result through task_wait/task_get. With requireReview:true it submits a review candidate; the parent reads task_wait/task_result and uses task_accept/task_revise. Do not send an additional message to announce or duplicate the result.

Quick Start

Before delegating, decide whether attached subagents improve the current answer.

1. If the user needs one direct answer and the work is small, tightly coupled, or sequential, do it in the parent turn.
2. If independent focused work improves speed, coverage, verification, or auditability, use task_create to create attached subagents.
3. Create independent child tasks first. Use requireReview:false normally; explicitly select true when the assignment needs formal acceptance and same-worker revisions.
4. Call task_wait until the next child result is terminal or requires review.
5. Inspect each returned terminal result. For review-required candidates, read complete reviewContent, paging through task_result when necessary.
6. For review-required candidates, accept good work or request revisions. Automatically completed results need no task_accept and cannot be reopened with task_revise. Cancel or detach active work only when appropriate.
7. Call task_wait again for the remaining active runs and repeat the review cycle until all child work is resolved.
8. Synthesize the parent answer from accepted results and direct parent work.

Do not finish the parent turn while attached subagents created by this turn are pending, running, waiting for review, or producing unreviewed candidates.

Load References When Needed

Keep this file in context for the normal attached-subagent flow. Load detailed references only when the matching situation appears:

• Read references/tool-schemas.md before constructing non-trivial attached-subagent task_* payloads, after schema errors, or when exact field names matter.
• Read references/workflows-and-examples.md for concrete attached-subagent examples: parallel investigation, independent review, parent synthesis, revision, cancel, and detach.
• Read references/troubleshooting.md after bad child results, missing evidence, review confusion, parent finished too early, schema errors, or stuck attached work.

For scheduled task delivery, cron, recurring runs, task updates, or delivery troubleshooting, read system:pioneer/tasks instead.

CLI Runtime Binding

When Pioneer provides these operations through its CLI MCP facade, use the callable names in the current CLI tool catalog. The turn instructions bind the canonical task names to those callables. The catalog is fixed for that turn; use only the operations it contains. No request_tools call is needed in this environment.

In CLI runtimes, system:pioneer/tasks means the exported pioneer-system-tasks skill and system:pioneer/subagents means the exported pioneer-system-subagents skill. Load them using the runtime's skill mechanism or read their exported SKILL.md files. Resolve references/ relative to the loaded skill directory. Other system skill references do not imply that a CLI export or tool is available. Use artifact tools only when the current catalog provides them.

Tool Visibility

Only call task tools that are visible in the current turn.

If a needed task tool is hidden and request_tools is visible, request the task domain:

{
  "domains": ["task"],
  "reason": "Need task tools to create, wait for, review, revise, accept, cancel, detach, or inspect attached subagent work."
}

Do not request individual task tool names. Request the task domain.

The task domain also exposes threads_start_options; opening threads separately is unnecessary to inspect task launch options. Call it when you need to choose an identity, execution profile, or permitted destination explicitly. For an ordinary attached task that inherits the parent's identity and profile, omit launch and targetOptionId; no preliminary options call is required. Options list permitted selections but do not grant execution rights. See references/tool-schemas.md for the exact fields.

If the task domain cannot be opened, do not pretend a subagent was created, waited on, accepted, revised, cancelled, or detached.

When To Delegate

Create attached subagents when at least one is true:

• the user explicitly asks for subagents, agents, parallel work, independent workers, or review;
• the task naturally splits into independent parts;
• separate agents can inspect different files, systems, tools, or hypotheses in parallel;
• the parent needs independent verification before committing to an answer;
• the work is large enough that one parent timeline would be hard to audit.

Prefer parent-only work when:

• the task is small, obvious, or single-step;
• each next step depends on one previous result;
• delegation would add coordination overhead without improving quality;
• the user asks not to delegate.

Create Good Attached Subagents

For immediate attached subagents, omit trigger and normally set requireReview:false. Set true before launching work that requires formal acceptance or revisions.

Good child tasks are narrow and auditable:

• title: short label visible in the parent timeline.
• goal: one concrete outcome.
• instructions: behavior, constraints, and what not to do.
• inputText or input: data, paths, ids, dates, examples, and scope.
• outputInstructions: exact result shape, evidence requirements, and language.

Use self-contained wording. Do not rely on hidden parent reasoning, invisible local assumptions, or tool names that might not exist in the child turn.

Ask for file:line references when code claims matter. Ask children to register user-visible files with artifact_register when they create files.

Do not pass runtime-owned fields such as workspaceId, ownerKind, parentTaskId, rootTaskId, depth, model, modelProvider, or trigger.spec.

Read references/tool-schemas.md for exact payload examples.

Wait And Review

Task reading, control, and review follow the authorized root-thread capsule and current action grants/capabilities, including in later turns or independent executions. Reading full candidate content requires permitted result reading, not final-review authority. Accept/revise additionally enforce UserFinal, required advisory/quorum policy, authentic actor binding, and the prohibition on self-acceptance. Creator identity and execution graph do not grant exclusive review rights.

An access or runtime error is not proof that a child stopped. Do not recreate work or claim cancellation on that basis; report the unresolved state and avoid duplicate work. See system:pioneer/tasks for durable task access and failure handling.

For independent attached subagents, create them all first, then call task_wait with taskIds or runIds. Prefer runIds when available. By default, task_wait returns as soon as any target is terminal or requires review. Handle every returned result before calling task_wait again for the remaining active runs.

The parent may also keep working and check a child with task_get. A running run has not finished; a missing result or unchanged updatedAt does not show that it is stuck. In task_get, execution.heartbeatAt is a liveness signal, while execution.lastActivityAt records confirmed task activity when available. Missing activity data is unknown. Do not cancel or repeat a child's work solely because time passed or repeated observations look the same. A task_wait timedOut result ends only that wait window; wait again for active attached work when needed.

task_wait can return terminal results, pending work, or reviewRequired. A review-required candidate is not final. Inspect every candidate and accept only when it satisfies:

• the original user request;
• the child task goal;
• the requested output shape;
• evidence and artifact requirements;
• safety, scope, and write constraints.

For an authorized result reader, reviewRequired.reviewContent contains the reviewer-safe child result for that exact candidate. Do not decide from summary alone; summary is only a preview and may be just the first heading. If reviewContent.truncated is true, call task_result with the candidate's candidateId, then continue with each returned nextCursor until the complete content has been inspected. Use the same task_result(candidateId) flow to re-read a candidate after recovery or context compaction.

Always read by candidateId, not by taskId: a task may have several immutable revision rounds, and the review decision must apply to the exact content that was inspected.

Use task_revise when the result is close but incomplete or incorrectly shaped. Give concrete feedback: what is wrong, what to add/remove/correct, and what the revised output must look like.

Use task_accept only after the candidate is good enough to use. Use accepted child results in the parent synthesis.

After accepting, revising, or cancelling the returned candidates, call task_wait again for unresolved active runs. Continue this wait-review cycle until no attached child work remains unresolved.

Use task_cancel when the child is irrelevant, unsafe, duplicate, or no longer needed.

Use task_detach only when the work should continue in the background and no longer block the parent turn. Do not detach review-required work; accept, revise, or cancel the active candidate first.

Before Finalizing

Validate the attached-subagent state before answering the user:

• every relevant child is terminal, accepted, revised, cancelled, or deliberately detached;
• review-required candidates are inspected;
• accepted candidates are the only candidates treated as final evidence;
• failures, cancellations, detached work, and uncertainty are accounted for.

Final Parent Answer

The final user-facing answer comes from the parent.

Include only what matters:

• which subagents ran, when useful;
• which results were accepted or revised, when relevant;
• any failures, cancellations, or detached work;
• the integrated answer;
• links or artifacts created by parent or children.

Do not paste raw child outputs blindly. Combine duplicate findings, preserve important evidence, and write one coherent parent response.

Gotchas

• Attached subagents are for current-turn delegation, not scheduled future work.
• task_wait uses arrays: taskIds or runIds, not singular taskId or runId.
• A pending_review candidate is not accepted work.
• A candidate summary is a preview, not sufficient review evidence; inspect reviewContent or call task_result.
• Do not quote rejected candidates as final results.
• Do not finish while attached child work from this turn is unresolved.
• Do not claim a child was created, accepted, revised, cancelled, or detached unless the relevant tool succeeded.

Review choice and later executions

Use requireReview:false for ordinary task/subagent work; it is the default for all types and attachment modes, including scheduled, interval, cron and webhook. Set requireReview:true explicitly when each run result must wait for acceptance and may need same-worker revisions. The meaning does not depend on the trigger. Enabled review has no timeout acceptance. The saved policy supplies the revision budget (normally five); acceptance is final. Detaching a task or changing its schedule does not silently change its saved review choice.

Later authorized executions in the same capsule can inspect and review saved workers under current grants, without creator/graph ownership or adoption. task_get.reviewRequired exposes current candidate references and available actions; read full content through task_result(candidateId) and all pages. For recurring/webhook work, decisions target the exact run and candidate, even when another run is queued or running. Read access does not require TaskReview; self-review, policy eligibility, finality and stale-candidate guards still apply.

Background work without review defaults to origin_thread delivery. For background:true plus requireReview:true, omitted deliveryPolicy selects none; an explicit permitted policy wins. Results, errors and blocked/exhausted outcomes follow that same policy. None keeps results/history available without delivery. Scheduled work retains its existing delivery defaults and requires self-contained instructions and available Skills/MCP; capability inheritance is not promised.