Spawn subagents — one per call, or a
tasks[]batch per call (task.batch, default on). Withasync.enabled=true, ordinary spawns run in the background; otherwise the call blocks until they finish. Execution mode is per item: an item whose custom agent type declaresblocking: trueruns inline while non-blocking items in the same call still spawn as background jobs. No bundled agent currently declaresblocking: true.
- Entry:
packages/coding-agent/src/task/index.ts - Model-facing prompt:
packages/coding-agent/src/prompts/tools/task.md - Key collaborators:
packages/coding-agent/src/task/types.ts— dynamic schema, progress/result types, output caps.packages/coding-agent/src/task/discovery.ts— discover project/user/plugin/bundled agents.packages/coding-agent/src/task/agents.ts— bundled agent definitions and frontmatter parsing.packages/coding-agent/src/task/executor.ts— create child sessions, run subagents, collect output, hand finished sessions to the lifecycle manager.packages/coding-agent/src/registry/agent-lifecycle.ts— idle-TTL parking and revival of finished subagents.packages/coding-agent/src/registry/agent-registry.ts— process-global agent directory (running | idle | parked | aborted).packages/coding-agent/src/async/job-manager.ts— background job registration, progress, and result delivery.packages/coding-agent/src/task/parallel.ts—Semaphoreused for the session-scoped concurrency bound.@oh-my-pi/pi-natives(crates/pi-iso) — isolation PAL:isoResolve/isoStart/isoStop backend resolution and fallback.packages/coding-agent/src/task/worktree.ts— isolation backend mapping (parseIsolationBackend) and lifecycle (ensureIsolation/cleanupIsolation), patch capture, branch merge.packages/coding-agent/src/task/output-manager.ts— session-scopedagent://id allocation.packages/coding-agent/src/task/name-generator.ts— default AdjectiveNoun agent ids.packages/coding-agent/src/internal-urls/agent-protocol.ts— resolveagent://<id>to saved subagent output.packages/coding-agent/src/internal-urls/history-protocol.ts— resolvehistory://<id>to a concise transcript.packages/coding-agent/src/tools/index.ts— tool registration and recursion-depth gating.packages/coding-agent/src/sdk.ts— child-session router/tool wiring and per-subagentAgentOutputManager.docs/task-agent-discovery.md— deeper discovery and precedence notes.
The wire schema is shape-swapped by task.batch (default on). One unit of work is the task item { name?, agent?, task, solutionSpace, effort?, outputSchema?, schemaMode?, isolated? }. isolated exists only when task.isolation.enabled is true and plan mode is disabled; effort exists only when task.enableEffort=true (default off).
- Batch shape (
task.batchon):{ context, tasks: item[] }— one subagent per item, all run under the same fan-out rules; there is no top-level agent field.contextis required shared background rendered into every spawned subagent's system prompt (CONTEXTsection);agent,outputSchema, andschemaModeare per item.effortis added only when its setting enables it;isolatedadditionally requires plan mode to be disabled. - Flat shape (
task.batchoff):{ ...item }— exactly one spawn per call. Shared background goes into alocal://file (e.g.local://ctx.md) that each spawn'staskreferences; subagents share the parent'slocal://root.
| Field | Type | Required | Description |
|---|---|---|---|
context |
string |
Yes (batch) | Shared background prepended to every spawn of the call via the subagent system prompt. Rejected when task.batch is off. |
tasks |
array |
Yes (batch) | One task item per subagent. Provided names must be unique within the call (case-insensitive). Rejected when task.batch is off. |
name |
string |
No | Stable agent name — becomes the registry/IRC id. Defaults to a generated AdjectiveNoun name. Uniquified per session by AgentOutputManager. Item field in batch shape, top-level in flat shape. |
agent |
string |
No | Agent type to run this item (e.g. scout). Defaults to the spawn policy's default agent (usually task); items in one batch call may use different agent types. Item field in batch shape, top-level in flat shape. |
task |
string |
Yes | The work — complete, self-contained instructions. Empty-after-trim is rejected. Item field in batch shape, top-level in flat shape. |
solutionSpace |
string |
Yes | How open-ended the child's problem is: whether the fix or design is given, or which causes or designs remain open (e.g. one fix: rename, names given; deadlock cause open, no repro). Volume of work does not widen it. Rides the child's first prompt into the auto thinking classifier as its sole input — the judge sees this field, not the task text; ignored when the child's thinking selector is not auto or effort overrides it. Blank or missing values fall back to classifying the task text: the schema advertises it as required, but the tool's lenient argument validation still spawns a call that omits it. Item field in batch shape, top-level in flat shape. |
effort |
"lo" | "med" | "hi" |
No | Present only with task.enableEffort=true. Per-spawn thinking effort, mapped onto the resolved model's supported range (lowest/middle/highest level it tops out at, e.g. high/xhigh/max). Overrides the agent's default selector, including auto; omitting it keeps the agent's configured selector — automatic per-prompt classification only for agents configured auto (e.g. the bundled task); scout/sonic configure medium. Item field in batch shape, top-level in flat shape. |
outputSchema |
JSON Schema (object | boolean | string | null at the coarse wire-validation layer) |
No | Invocation-specific structured-output contract. Takes precedence over agent frontmatter output and the inherited parent session schema. Item field in batch shape, top-level in flat shape. |
schemaMode |
"permissive" | "strict" |
No | Validation mode for the effective output schema. Overrides the parent session mode; defaults to permissive. Item field in batch shape, top-level in flat shape. |
isolated |
boolean |
No | Run in an isolated workspace and return patches. Exists only when task.isolation.enabled is true and plan mode is disabled; per item in batch shape, top-level in flat shape. Isolated agents are torn down at completion — not revivable. |
There is no wire label field: the one-line UI label shown in the TUI/registry is generated automatically from the task text by the tiny/title model (fire-and-forget), so callers never provide it.
Users can tag models with ^ in the composer. The resulting session-local m1, m2, … pseudonyms are accepted as agent by task, eval agent(), and workpool(); each uses the bundled task template pinned to the tagged selector. See user-tagged model agents for persistence, boundaries, and precedence.
Runtime stays permissive: the flat form is accepted even while task.batch is on (internal callers such as the commit flow's analyze_files, and stale transcripts). The model only ever sees one shape.
There is no legacy per-call schema parameter. Use outputSchema and optional schemaMode; when absent, structured output falls back to the agent definition's output frontmatter and then the inherited parent session schema.
The tool returns one text block plus details: TaskToolDetails.
Background response (async.enabled=true):
content:Spawned agent `<id>` (job `<jobId>`).plus auto-delivery guidance: usewaitonly when blocked,read proc://<id>for non-consuming inspection,write proc://<id>/killto cancel, andwrite agent://<id>to coordinate when peer messaging is enabled. A batch call instead returnsSpawned N background agents using <agent types>. ...(the deduped per-item agent types, comma-joined) with a per-agent-(job)listing.details:{ projectAgentsDir, results, totalDurationMs, progress: [<AgentProgress per spawn>], async: { state, jobId, type: "task" } }. The call keeps one sharedprogress[]snapshot;async.jobIdis the first started job andasync.stateaggregates over the async spawns ("running" until every job settles, "failed" if any spawn failed) — jobs that settled before the call returned are already reflected. A mixed call'sresultscarries the blocking spawns' inlineSingleResults (pure background calls returnresults: []).- Live progress keeps streaming into the same tool block via
onUpdate(...); each final result arrives later as an async-result injection into the parent conversation. The delivery text appends a follow-up hint:<id> is now idle — message it via `write agent://<id>` to follow up; transcript at history://<id>when messaging is enabled (aborted variant points at the transcript only).
Settled response (async.enabled=false, no job manager, every item's agent blocking: true, or async job body):
content: summary rendered frompackages/coding-agent/src/prompts/tools/task-summary.mdwith a preview capped at 5000 chars;agent://<id>holds the full output. A sync batch concatenates the per-spawn summaries.details.results: oneSingleResultper spawn;usage,outputPathspopulated (aggregated across spawns for a sync batch).
SingleResult includes:
- identity:
index,id,agent,agentSource,task,description, optionalassignment(internal payload names; the wire fields arename/agent/task) - status:
exitCode, optionalerror, optionalaborted, optionalabortReason, optionalretryFailure - output:
output,stderr,truncated,durationMs,tokens,requests, optionalcontextTokens/contextWindow,usage - model: optional
modelOverride,resolvedModel,resolvedModelIsFallback - structured result: optional
structuredOutputwith schema source/mode, validation status, parseddata, and validationerror - artifact metadata:
outputPath?,patchPath?,branchName?,branchBaseSha?,nestedPatches?,outputMeta? - extracted tool data:
extractedToolData?from registered subprocess tool handlers such asyield
Artifacts and side channels:
- Every subagent with an artifacts dir writes
<id>.md;agent://<id>resolves to that file. - A subagent's own children are dot-qualified (
<id>.<child>);agent://<id>.<child>reads that nested output. A slash path is always JSON extraction:agent://<id>/<key>/<index>/…extracts that value from a JSON output (e.g.agent://<id>.<child>/reports/0/data). - Each subagent gets
<id>.jsonlsession history when the parent persists artifacts;history://<id>renders it as a concise transcript (works for live and parked agents). - Isolated patch mode writes
<id>.patchbefore merge.
TaskTool.create(...)discovers agents once per cwd through a process-level memo (discoverAgentsForCreate) to render the dynamic prompt description.execute(...)repairs raw params (repairTaskParams), then validates:schemais always rejected;tasks/contextare rejected unlesstask.batchis on; batch calls need a non-emptytasks(ataskper item, unique provided names), a non-empty sharedcontext, and no top-leveltaskalongsidetasks; flat calls needtask. The call is then normalized into its spawn list (resolveSpawnItems).- Per-item execution split: items whose agent type declares
blocking: truerun inline; the rest become background jobs. The whole call runs sync whenasync.enabled=false, the session has noAsyncJobManager(orphaned host), or every item is blocking; inline spawns run asSpawnRuns (src/task/spawn-run.ts), each holding a session-scoped semaphore permit until it settles. - Background execution (any non-blocking item with
async.enabled=trueand anAsyncJobManager):- agent ids are allocated up front via
AgentOutputManager.allocate(...)— each item'sname, or a generated AdjectiveNoun name — one per spawn; - one
type: "task"job per spawn is registered withsession.asyncJobManager(id= agent id,queued: true,ownerId= caller agent id) and the tool returns immediately; - each job body starts — or adopts, after a speculative launch — a
SpawnRun, which acquires the session-scopedSemaphore(one perTaskToolinstance, resized in place from the livetask.maxConcurrencysetting before every acquire and release); the job is marked running once the permit is held and reports progress through the sharedbuildAsyncDetails/onUpdate; - a failed or aborted run throws
TaskJobErrorso the job landsfailed, but the agent itself stays registered and interrogable. - a mixed call registers the async jobs first, then runs its blocking items inline and returns once they settle — the text combines the inline summaries with the spawned-job listing, and the block keeps rendering the still-running background rows beside the inline results.
- agent ids are allocated up front via
- Each
SpawnRunruns the spawn path (#runSpawn), which rediscovers agents from disk, so runtime resolution can differ from the create-time description. - It resolves each spawn's requested
agenttype, rejects unknown or settings-disabled agents, and enforces parent spawn policy plusPI_BLOCKED_AGENTself-recursion prevention. - Model priority:
task.agentModelOverrides→ agent frontmatter → configured task role/session fallback. Output schema priority: per-calloutputSchema→ agent frontmatteroutput→ inherited parent session schema. - Plan mode swaps in an
effectiveAgentwith a read-only tool subset and plan-mode prompt;runSubprocess(...)receives the effective agent. - If
isolated, it requires a git repo (getRepoRoot(...)/captureBaseline(...)), mapsisolation.backendto a backend-kind hint (parseIsolationBackend), and materializes the workspace via the natives PAL (ensureIsolation→isoResolve/isoStart), walking the candidate list when a backend is unavailable. - Artifacts dir comes from the parent session file when available, otherwise a temp dir. When the session is executing an approved plan, the plan reference is handed to the subagent.
- Non-isolated spawns call
runSubprocess(...)directly with parent cwd; isolated spawns run inside the isolation workspace, then commit to a branch (mergeMode === "branch") or capture a patch, and always clean up the workspace. runSubprocess(...)creates a child agent session with an isolated settings snapshot (parent settings inherited —async.enabledandbash.autoBackground.enabledare inherited from the parent, not force-disabled;tier.openai/tier.anthropic/tier.googleare first re-resolved throughtier.subagent, then the child session resolves an exacttask.agentServiceTierOverrides[agentName]entry handed over by task/eval dispatch against its final model and persists the result;tools.approvalModeis forced toyolobecause headless subagents have no UI to confirm prompts against;advisor.enabledis forced off unless the spawn opts in per agent; per-spawn overrides may disable read summarization and clear extra workspace roots for isolated runs), childagentIdequal to the allocated id, child internal URL router/AgentOutputManager, output schema, the sharedcontext(batch calls) in the system prompt'sCONTEXTsection, and the IRC peer roster in the system prompt.- Child tool availability: explicit
agent.toolsif provided; auto-addtaskwhen the agent hasspawnsand depth allows; striptaskattask.maxRecursionDepth; injectwaitwhen async jobs, peer messaging, or supervised services are available; peer messaging viawriterequires that tool in an explicit list; expandexectoeval+bash; strip parent-ownedtodo— unless the spawn is prewalk-armed, whose plan nudge + todo gate need the child to commit its own todo list before the model hand-off. - The child must finish through the hidden
yieldtool; up to 3 reminder prompts, the last forcingtoolChoice = yieldwhen supported.finalizeSubprocessOutput(...)reconciles raw text,yieldpayloads, structured schemas, and abort states. - End-of-run lifecycle (keep-alive, in the run finalizer):
- caller signal, wall-clock timeout, or internal hard abort → registry status
aborted, session disposed — terminal; - soft-request-budget abort on a non-isolated kept-alive agent → treated as resumable: the agent becomes
idleand may receive a follow-up/revival; - isolated run → status
parkedwithout a reviver (workspace is merged + cleaned, so the session is not revivable; transcript stays readable viahistory://), then session disposed and detached; - everything else (success and failure alike) → status
idlewith the live session attached, andAgentLifecycleManager.global().adopt(id, { idleTtlMs, revive })arms the park timer. The reviver reopens the session JSONL.
- caller signal, wall-clock timeout, or internal hard abort → registry status
- Lifecycle thereafter:
idleagents are parked aftertask.agentIdleTtlMs(session disposed;AgentRef+ session file retained);write agent://<id>or the Agent Hub revives them back toidle."Main"is never parked.
- Execution mode
- Background job —
async.enabled=true; non-blocking spawns go throughAsyncJobManager. - Sync inline —
async.enabled=false, no job manager, or the item's agent declaresblocking: true(per item: a mixed call runs both modes).
- Background job —
- Batch mode (
task.batch, default on)- on —
{ context, tasks[] }: one independent spawn per item, requiredcontextshared across the call's spawns, withagent,outputSchema, andschemaModeper item.effortappears only when its setting enables it;isolatedalso requires plan mode to be disabled. Lifecycle, revival, and concurrency semantics match N parallel single calls. - off — single spawn per call;
tasks/contextare rejected and removed from the schema, with the same conditionaleffort/isolatedfields.
- on —
- Speculative launch (
task.speculativeLaunch, default on; batch mode only) — while a{ context, tasks[] }call streams, the tool's stream session (src/task/speculative-launch.ts) starts each item'sSpawnRunas soon as that item's JSON object closes (contextmust already have closed), and starts the remainder when the call finishes streaming. Dispatch adopts runs whose normalized spawn params still match; an invalid finished call, launched items that differ from the finished call, a blocking hook, or an aborted turn aborts every launched run. Launches need host authorization (authorizeLaunch): auto-allowedtaskapproval and no extensiontool_call/tool_result/approval lifecycle handlers. - Isolation is enabled with
task.isolation.enabled;isolation.backendselectsauto,apfs,btrfs,zfs,reflink,overlayfs,projfs,block-clone, orrcopy, and the PAL resolves the actual backend with fallback. - Isolation merge strategy: patch mode (capture/apply root patches) or branch mode (commit to
omp/task/<id>, cherry-pick into parent). - Agent source precedence is first-wins by exact name: project
.omp/agents; user.omp/agent/agents; OMP extension-packageagents/roots in CLI → project settings → user settings → installed npm/link plugin order; Claude marketplace plugin agents (project before user); then bundled (scout,reviewer,security-reviewer,task,sonic). - Prewalk: agent frontmatter
prewalkortask.agentPrewalk[agentName]can start on the normal model and hand off to a cheaper resolved model at the first edit/write.task.prewalk(default off) arms this behavior for the bundled generictaskagent. Missing/unconfigured targets and exact model+effort no-ops skip the handoff rather than failing the spawn. - Advisor: agent frontmatter
advisorortask.agentAdvisor[agentName]("on"/"off"/ model pattern) pairs the child session with an advisor; an explicit pattern lands on the child'smodelRoles.advisor. Subagents default to no advisor.
- Filesystem
- Writes
<id>.jsonland<id>.mdunder the session artifacts dir or a temp task dir; isolated patch mode writes<id>.patch. - Creates/removes worktrees or overlay mount directories; branch mode creates temporary worktrees and task branches.
- Writes
- Network
- Child sessions may use whichever networked tools/models their active tool set permits.
- MCP proxy tools can call existing parent MCP connections with a 60_000 ms timeout.
- Subprocesses / native bindings
- Isolation backends run through the
pi-nativesPAL (crates/pi-iso): kerneloverlaywithfuse-overlayfs/fusermount[3]fallback on Linux, APFS/Btrfs/ZFS/reflink clones, ProjFS on Windows, recursive copy as last resort. - Git operations for baseline capture, patch apply, worktrees, branches, stash, cherry-pick, commits.
- Isolation backends run through the
- Session state (transcript, memory, jobs, checkpoints, registries)
- Creates child
AgentSessioninstances with isolated settings snapshots; finished sessions stay registered in the process-globalAgentRegistryasidle/parkeduntil process teardown or explicit release. - With
async.enabled=true, registers one async job per spawn insession.asyncJobManager; completion is injected into the parent as an async-result message. - Arms idle-TTL timers in
AgentLifecycleManager(unref'd; they never hold the process open). - Emits
task:subagent:event,task:subagent:progress, andtask:subagent:lifecycleon the parent event bus. - Allocates session-scoped output ids through
AgentOutputManagersoagent://stays unique across invocations. - Shares the parent
local://root andArtifactManagerwith subagents.
- Creates child
- Background work / cancellation
write proc://<jobId>/kill(nocontentneeded) or parent tool-call abort cancels background jobs; parent tool-call abort cancels sync runs through the call signal. A hard-aborted run landsabortedand is torn down. An owned running subagent without a job can be cancelled throughproc://<agentId>/kill, which aborts and releases its session.- Missing-
yieldrecovery sends up to three internal reminder prompts to the child session.
- Per-spawn effort is opt-in:
task.enableEffortdefaults tofalse; when false,effortis omitted from the dynamic model-facing schema. - Concurrency: one session-scoped
Semaphoreis resized in place from the livetask.maxConcurrencysetting before every acquire and release, then bounds concurrent subagents across paralleltaskcalls — everySpawnRun(async jobs, the sync fallback, and speculative launches) acquires it. Mid-session setting changes therefore affect new spawns and work already queued on the semaphore. - Idle TTL:
task.agentIdleTtlMs, default420_000ms (7 min);<= 0disables parking and keeps idle sessions liv 4EA0 e until exit. - Per-subagent output truncation:
MAX_OUTPUT_BYTES = 500_000andMAX_OUTPUT_LINES = 5000inpackages/coding-agent/src/task/types.ts(overridable viaPI_TASK_MAX_OUTPUT_BYTES/PI_TASK_MAX_OUTPUT_LINES). Full raw output is still written to<id>.md. - Progress coalescing:
PROGRESS_COALESCE_MS = 150; recent-output tail:RECENT_OUTPUT_TAIL_BYTES = 8 * 1024(last 8 non-empty lines). - Missing-
yieldreminder retries:MAX_YIELD_RETRIES = 3; MCP proxy timeout:MCP_CALL_TIMEOUT_MS = 60_000— both inpackages/coding-agent/src/task/executor.ts. - Soft request budget:
task.softRequestBudgetdefaults to 200 requests (0disables). Crossing it injects a wrap-up notice whentask.softRequestBudgetNoticeis enabled; at 1.5× the budget the run is force-stopped to yield partial findings. Bundled scout/sonic agents may impose a lower built-in cap. - Hard wall clock:
task.maxRuntimeMsapplies to every spawn; default0disables it. - Recursion depth gate:
task.maxRecursionDepth;packages/coding-agent/src/tools/index.tshides thetasktool at or beyond the limit, andrunSubprocess(...)also strips childtaskaccess at max depth. - Final inline summary preview uses
fullOutputThreshold = 5000chars inpackages/coding-agent/src/task/index.ts;agent://<id>points to the full artifact.
- Parameter validation failures are returned as normal tool text with empty
results:schema(never accepted)tasks/contextwhiletask.batchis disabled- batch calls: missing/empty
tasks, an item withouttask, duplicate provided names, missing sharedcontext, top-leveltaskalongsidetasks - flat calls: missing/empty
task - unknown or settings-disabled agent type, spawn-policy denial, requesting
isolatedwhile isolation mode isnone
- Isolated execution without a git repo returns
Isolated task execution requires a git repository. ...; unavailable backends fall back through the PAL candidate list (reported viafellBack/fallbackReason), other backend errors rethrow, and exhausting every candidate errors with the fallback reason. - Job registration failure returns
Failed to start background task job(s): ...; a batch that schedules only some jobs reports the failed ids in the immediate text and keeps the started ones running. - Child failures surface as
SingleResult.exitCode = 1withstderr/errorpopulated; the async job is marked failed but the delivery text still carries the output plus a follow-up/transcript hint. - If the child omits
yield,finalizeSubprocessOutput(...)injects warnings such asSYSTEM WARNING: Subagent exited without calling yield tool after 3 reminders. agent://<id>resolution errors are model-visible when another tool reads them: no session, no artifacts dir, missing id, conflicting extraction syntax, or invalid JSON for extraction.
- Parallelism is parallel
taskcalls in one assistant message — or, withtask.batch, atasks[]batch in one call; either way the session-scoped semaphore bounds the fan-out. Withasync.enabled=true, each spawn is an independent background job. - Shared background convention without batch mode: write it once to a
local://file and reference that path in each spawn'stask— subagents share the parent'slocal://root. Withtask.batch, the requiredcontextparameter carries the shared background directly into each spawn's system prompt. - Prefer messaging an existing agent via
write agent://<id>over a fresh spawn for follow-up work: it already holds the relevant context. Barehistory://discovers registered transcripts; messaging a parked agent revives it.history://<id>shows what an agent has done. - Peer-messaging availability is derived, not configured (
isIrcEnabledin the messaging helper): it requires a caller withwriteand someone to message — the session can spawn subagents, or it is a subagent itself. Without peer messaging, the follow-up hint does not suggest it. - Agent discovery precedence is first-wins by exact name: project
.ompagents before user.omp, then OMP extension-packageagents/roots inlistOmpExtensionRootsorder (CLI, project setting, user setting, installed npm/link plugins), Claude marketplace plugin agents (project before user), and bundled agents. Direct.claude/agents,.codex/agents, and.gemini/agentsroots are skipped. Create-time discovery is memoized per cwd for the prompt description; execution-time discovery stays fresh. - Child sessions do not inherit conversation history. Built-in carry-over is the workspace tree/skills/context files, the shared
local://root, and the approved-plan reference when one exists. - When the parent passes
mcpManager, child sessions disable standalone MCP discovery and get proxy tools that reuse parent connections. - Branch-mode merge temporarily stashes the parent repo before cherry-picking; a stash-pop conflict does not unmerge the cherry-picked commits — they stay on HEAD, the stash entry is preserved, and the conflict is surfaced separately as
stashConflict. Patch mode only applies the combined root patch whengit.patch.canApplyText(...)succeeds; failures leave the.patchartifact for manual handling. - Nested git repos are diffed independently inside isolated workspaces and merged separately with
applyNestedPatches(...). agent://ids are name-based (Taskfirst,Task-2/Task-3only when the name repeats, nested likeParent.Child) byAgentOutputManager; this is what prevents artifact collisions across repeated or nested invocations.