oh-my-pi/docs/tools/task.md

task

Launch subagents for parallel, optionally isolated work.

Source

• 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.
  • packages/coding-agent/src/task/parallel.ts — concurrency-limited scheduling and async semaphore.
  • packages/coding-agent/src/task/isolation-backend.ts — isolation backend resolution and platform fallback.
  • packages/coding-agent/src/task/worktree.ts — worktree / FUSE / ProjFS setup, patch capture, branch merge.
  • packages/coding-agent/src/task/output-manager.ts — session-scoped agent:// id allocation.
  • packages/coding-agent/src/task/simple-mode.ts — default / schema-free / independent field gating.
  • packages/coding-agent/src/internal-urls/agent-protocol.ts — resolve agent://<id> to saved subagent output.
  • 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-subagent AgentOutputManager.
  • docs/task-agent-discovery.md — deeper discovery and precedence notes.
  • docs/handoff-generation-pipeline.md — session artifact/handoff persistence patterns used by the wider session layer.

Inputs

Default mode (task.simple = "default")

Field	Type	Required	Description
agent	string	Yes	Exact agent name for every task item. Resolved at execution time through discoverAgents(...).
tasks	Array<{ id: string; description: string; assignment: string }>	Yes	Batch of small, self-contained task items. id max length 48 in schema; duplicate ids are rejected case-insensitively at runtime.
context	string	No	Shared background prepended to every subagent system prompt. Trimmed before use.
schema	string	No	JSON-encoded JTD schema. Overrides agent/session output schema when this mode allows task-level schemas.
isolated	boolean	No	Only present when the tool is created with isolation enabled. Requests isolated execution for the whole batch.

tasks[].description is UI-only. tasks[].assignment is the actual per-task instruction.

Schema-free mode (task.simple = "schema-free")

Same as default, except schema is rejected by validateTaskModeParams(...) in packages/coding-agent/src/task/index.ts.

Independent mode (task.simple = "independent")

Field	Type	Required	Description
agent	string	Yes	Exact agent name.
tasks	Array<{ id: string; description: string; assignment: string }>	Yes	Same item shape, but each assignment must carry all required background because shared context is disabled.
isolated	boolean	No	Same conditional field as above.

In this mode both context and schema are rejected.

Outputs

The tool returns one text block plus details: TaskToolDetails.

details fields:

• projectAgentsDir: string | null — nearest discovered project agents/ dir.
• results: SingleResult[] — one entry per task in input order for synchronous execution; empty for async-launch responses.
• totalDurationMs: number
• usage?: Usage — sum of per-subagent assistant-message usage.
• outputPaths?: string[] — written .md artifact paths for completed subagent outputs.
• progress?: AgentProgress[] — live or final per-task progress snapshots.
• async?: { state: "running" | "completed" | "failed"; jobId: string; type: "task" } — present for background execution updates/results.

SingleResult includes:

• identity: index, id, agent, agentSource, description, optional assignment
• status: exitCode, optional error, optional aborted, optional abortReason
• output: output, stderr, truncated, durationMs, tokens
• artifact metadata: outputPath?, patchPath?, branchName?, nestedPatches?, outputMeta?
• extracted tool data: extractedToolData? from registered subprocess tool handlers such as yield and report_finding

Artifacts and side channels:

• Every subagent with an artifacts dir writes <id>.md; agent://<id> resolves to that file.
• If the output file is JSON, agent://<id>/<path> and agent://<id>?q=<query> perform JSON extraction in packages/coding-agent/src/internal-urls/agent-protocol.ts.
• When the parent session persists artifacts, each subagent also gets <id>.jsonl session history.
• Isolated patch mode writes <id>.patch per successful task before merge.
• Async mode returns immediately after job registration, then emits onUpdate(...) progress snapshots and later hands completion to the session async-job pipeline.

Flow

1. TaskTool.create(...) in packages/coding-agent/src/task/index.ts calls discoverAgents(session.cwd) once to build the dynamic prompt description from current agents and task.simple capabilities.
2. execute(...) validates mode-gated fields with validateTaskModeParams(...).
3. It decides async vs sync:
   • sync when async.enabled is false
   • sync when the selected cached agent has blocking === true
   • sync when tasks.length === 0
   • otherwise async job scheduling
4. Async path:
   • allocate unique output ids with AgentOutputManager.allocateBatch(...)
   • create one async job per task through session.asyncJobManager.register(...)
   • limit concurrent job bodies with Semaphore(task.maxConcurrency) from packages/coding-agent/src/task/parallel.ts
   • each job body calls #executeSync(...) with a one-task batch and the preallocated id
   • onUpdate(...) emits aggregate progress snapshots and details.async
5. Sync path (#executeSync(...)) rediscovers agents from disk via discoverAgents(...), so runtime resolution can differ from the earlier prompt description.
6. It resolves the requested agent with getAgent(...), rejects unknown or disabled agents, and enforces parent spawn policy plus PI_BLOCKED_AGENT self-recursion prevention.
7. It derives the effective output schema in priority order: task call schema (if allowed) → agent frontmatter output → inherited parent session schema.
8. It validates task ids: missing ids and case-insensitive duplicates are immediate errors.
9. If isolated was requested, it requires a git repo (getRepoRoot(...) / captureBaseline(...)) and resolves the actual backend through resolveIsolationBackendForTaskExecution(...).
10. It chooses an artifacts dir from the parent session when available, otherwise a temp dir, and writes context.md there when session.getCompactContext?.() returns content.
11. It allocates unique ids again if the caller did not preallocate them, then builds tasksWithUniqueIds.
12. For each task, it seeds an AgentProgress entry and runs runTask(...) through mapWithConcurrencyLimit(...) using task.maxConcurrency.
13. Non-isolated runTask(...) calls runSubprocess(...) directly with parent cwd.
14. Isolated runTask(...):

• creates an isolation workspace (ensureWorktree(...), ensureFuseOverlay(...), or ensureProjfsOverlay(...))
• applies the captured baseline for worktrees
• runs runSubprocess(...) inside that workspace
• on success, either commits to a per-task branch (mergeMode === "branch") or captures a patch with captureDeltaPatch(...)
• always cleans up the isolation workspace/backend

15. runSubprocess(...) in packages/coding-agent/src/task/executor.ts creates a child agent session with:

• isolated settings snapshot via Settings.isolated(...), forcing async.enabled = false and bash.autoBackground.enabled = false
• child agentId / parentTaskPrefix equal to the allocated task id
• child internal URL router and AgentOutputManager from packages/coding-agent/src/sdk.ts
• the shared context, optional context.md reference, optional isolation worktree path, output schema, and IRC peer roster in the system prompt template

16. Child tool availability is derived from the agent definition plus runtime guards:

• explicit agent.tools if provided
• auto-add task when the agent has spawns and recursion depth allows it
• remove task at or past task.maxRecursionDepth
• expand exec to eval and bash
• strip parent-owned todo_write after session creation

17. runSubprocess(...) subscribes to child agent events, coalesces progress updates every 150 ms, forwards lifecycle/progress events on the parent event bus, and extracts tool data through subprocessToolRegistry.
18. The child must finish through the hidden yield tool. If it does not, runSubprocess(...) sends up to 3 reminder prompts; the last reminder forces toolChoice = yield when supported.
19. Finalization uses finalizeSubprocessOutput(...) to reconcile raw assistant text, yield payloads, structured schemas, report_finding data, and abort states. Output is truncated with MAX_OUTPUT_BYTES / MAX_OUTPUT_LINES before returning to the parent, but the full raw output is still written to <id>.md.
20. After all sync tasks finish, #executeSync(...) aggregates usage, collects artifact paths, and if isolation was used merges results back:

• branch mode: cherry-pick per-task branches with mergeTaskBranches(...), then delete merged branches with cleanupTaskBranches(...)
• patch mode: combine non-empty patch artifacts, dry-check with git.patch.canApplyText(...), then apply or leave manual artifacts
• nested repo patches are applied separately with applyNestedPatches(...)

21. The final text summary is rendered from packages/coding-agent/src/prompts/tools/task-summary.md and includes agent://<id> handles for outputs that exist.

Modes / Variants

• Execution mode
  • Sync inline execution — default path.
  • Async background execution — one async job per task item when async.enabled is on and the chosen agent is not marked blocking.
• Simple mode
  • default — accepts shared context and per-call schema.
  • schema-free — accepts context, rejects schema.
  • independent — rejects context and schema; each assignment stands alone.
• Isolation backend
  • none — no isolation.
  • worktree — detached git worktree plus baseline replay.
  • fuse-overlay — Unix FUSE overlay mount.
  • fuse-projfs — Windows ProjFS overlay.
• Isolation merge strategy
  • Patch mode — capture/apply root patches, keep patch artifacts when application fails.
  • Branch mode — commit each task onto omp/task/<id> branch, cherry-pick into parent, preserve failed branches for manual resolution.
• Agent source
  • Project custom agents — nearest project config/plugin agent directories, first by source-family precedence.
  • User custom agents — user config/plugin agent directories after project dirs of the same source family.
  • Bundled agents — appended last from packages/coding-agent/src/task/agents.ts.
• Bundled agent types
  • explore — read-only scout with structured handoff output.
  • plan — architecture/planning agent; may spawn explore.
  • designer — UI/UX specialist.
  • reviewer — review agent with report_finding extraction.
  • task — general-purpose worker with full capabilities.
  • quick_task — low-reasoning mechanical worker using the same task prompt body.
  • librarian — source-grounded external API/library researcher.

Side Effects

• Filesystem
  • Writes context.md, <id>.jsonl, and <id>.md under the session artifacts dir or a temp task dir.
  • In isolated patch mode writes <id>.patch artifacts.
  • Creates/removes worktrees or overlay mount directories.
  • In branch mode creates temporary worktrees and task branches.
• 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
  • fuse-overlayfs and fusermount/fusermount3 for FUSE isolation.
  • ProjFS native bindings via @oh-my-pi/pi-natives on Windows.
  • Git operations for baseline capture, patch apply, worktrees, branches, stash, cherry-pick, commits.
• Session state (transcript, memory, jobs, checkpoints, registries)
  • Creates child AgentSession instances with isolated settings snapshots.
  • Registers async jobs in session.asyncJobManager for background task mode.
  • Emits task:subagent:event, task:subagent:progress, and task:subagent:lifecycle on the parent event bus.
  • Allocates session-scoped output ids through AgentOutputManager so agent:// remains unique across invocations and resumes.
  • Shares the parent local:// root with subagents by passing localProtocolOptions through createAgentSession(...).
• User-visible prompts / interactive UI
  • Async mode streams aggregate progress updates.
  • Missing-yield recovery sends up to three internal reminder prompts to the child session.
  • Final summaries include <system-notification> blocks for isolation fallbacks or merge failures.
• Background work / cancellation
  • Parent abort stops scheduling new work, aborts active child sessions, and marks unscheduled tasks as skipped.
  • Async jobs keep their own cancellation via AsyncJobManager.

Limits & Caps

• Per-subagent output truncation: MAX_OUTPUT_BYTES = 500_000 and MAX_OUTPUT_LINES = 5000 in packages/coding-agent/src/task/types.ts. Full raw output is still written to <id>.md before truncation is returned to the caller.
• Progress coalescing in child execution: PROGRESS_COALESCE_MS = 150 in packages/coding-agent/src/task/executor.ts.
• Recent output tail for progress: RECENT_OUTPUT_TAIL_BYTES = 8 * 1024 and recentOutput keeps the last 8 non-empty lines in packages/coding-agent/src/task/executor.ts.
• Missing-yield reminder retries: MAX_YIELD_RETRIES = 3 in packages/coding-agent/src/task/executor.ts.
• MCP proxy timeout: MCP_CALL_TIMEOUT_MS = 60_000 in packages/coding-agent/src/task/executor.ts.
• Task id schema cap: tasks[].id maxLength: 48 in packages/coding-agent/src/task/types.ts.
• Prompt text says ids should be ≤32 chars, but the runtime schema allows 48; this mismatch is real.
• Async/full sync parallelism both use task.maxConcurrency from settings:
  • sync path: mapWithConcurrencyLimit(...)
  • async path: Semaphore(...) around job bodies
• Recursion depth gate: task.maxRecursionDepth from settings; packages/coding-agent/src/tools/index.ts hides the task tool at or beyond the limit, and runSubprocess(...) also strips child task access at max depth.
• Final inline summary preview per task uses fullOutputThreshold = 5000 chars in packages/coding-agent/src/task/index.ts; longer outputs are summarized while agent://<id> points to the full artifact.

Errors

• Most validation failures are returned as normal tool text with empty results, not thrown:
  • invalid simple-mode fields
  • unknown/disabled agent
  • missing tasks
  • missing/duplicate task ids
  • spawn-policy denial
  • requesting isolated while isolation mode is none
• Isolated execution without a git repo returns Isolated task execution requires a git repository. ....
• Backend resolution can return a hard error (ProjFS isolation initialization failed...) or a non-fatal warning with fallback to worktree.
• mapWithConcurrencyLimit(...) fails fast on non-abort worker exceptions; already completed results are preserved only in the thrown path’s local state, not surfaced unless the caller catches and converts them.
• Child-session failures surface as SingleResult.exitCode = 1 with stderr/error populated.
• If the child omits yield, finalizeSubprocessOutput(...) injects warnings such as SYSTEM WARNING: Subagent exited without calling yield tool after 3 reminders.
• Async scheduling failures are accumulated per task; if no jobs start, the tool returns Failed to start background task jobs: ....
• 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.

Notes

• Agent discovery precedence is first-wins by exact name: project dirs before user dirs within a source family, plugin agent dirs after config dirs, bundled agents last. See packages/coding-agent/src/task/discovery.ts and docs/task-agent-discovery.md.
• TaskTool.create(...) caches discovered agents only for description rendering and the async blocking-agent decision. #executeSync(...) rediscovers agents each call.
• Custom agent frontmatter can override bundled agents by name. Bundled definitions are embedded at build time in packages/coding-agent/src/task/agents.ts.
• Child sessions do not inherit conversation history automatically. The only built-in carry-over is shared context, optional context.md, workspace tree/skills/context files, and shared local:// root.
• Settings.isolated(...) gives each child a session-isolated settings snapshot; tool enablement is recomputed inside the child session rather than sharing mutable parent tool state.
• When the parent passes mcpManager, child sessions disable standalone MCP discovery and instead get proxy tools that reuse the parent connections.
• Plan mode mutates an effectiveAgent with a read-only tool subset and plan-mode prompt text, but runSubprocess(...) is still invoked with agent rather than effectiveAgent. Model/thinking/schema overrides use the effective agent; prompt/tool/spawn restrictions do not fully flow through this call path.
• Branch-mode merge temporarily stashes the parent repo before cherry-picking task branches. A stash-pop conflict is treated as merge failure and leaves recovery state behind.
• Patch-mode only applies combined root patches if every successful task produced a patch and git.patch.canApplyText(...) succeeds.
• Nested git repos are handled separately from the root repo. They are copied into isolated worktrees, diffed independently, and merged later with applyNestedPatches(...) because parent git cannot track their file-level changes.
• agent:// ids are numeric-prefixed (0-Task, 1-Task, nested like 0-Parent.0-Child) by AgentOutputManager; this is what prevents artifact collisions across repeated or nested task invocations.