From agent-tools
When choosing how to dispatch a subagent -- consult this before firing any dispatch. Covers the two primary mechanisms (Task tool / Bash + claude -p) and when each fits: default to Task tool for in-project work, reach for Bash + claude -p when you need a different cwd, process boundary, or long-running dispatch.
How this skill is triggered — by the user, by Claude, or both
Slash command
/agent-tools:dispatch-optionsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
There is no single right way to dispatch a subagent. Pick by what
There is no single right way to dispatch a subagent. Pick by what the dispatch actually needs.
| option | how | what it gives you | what you give up |
|---|---|---|---|
| Task tool | Task(subagent_type: "explore"|"plan"|"runner", prompt: "...") | Same cwd, lowest overhead, native Claude Code integration. Pass isolation: "worktree" for same-repo branch + file work -- agent gets its own checkout, path and branch returned on completion. | No different cwd (without worktree), no scriptable exit code, child uses parent's permission state |
| Bash + claude -p | Bash: claude -p --agent X "..." | Different cwd via --add-dir or cd, process boundary, survives session crash, backgroundable with run_in_background | No retry, no typed errors, prompt visible in argv |
If you use roba,
roba -wis equivalent toisolation: "worktree"androba --traceprovides a structured JSONL trace. These docs don't assume roba is installed.
Default to Task tool when:
For same-repo runner dispatches (branch + file changes), add
isolation: "worktree". The agent gets its own checkout;
the dispatcher's working tree is unaffected. See the
worktree lifecycle pattern below.
This is the normal in-session subagent path. Use it.
Reach for Bash + claude -p when:
cd or --add-dir can.run_in_background, output file inspectable).For worker sub-dispatch from within a runner's worktree, use
cd <worktree-path> && claude -p (or claude -p from a shell
already cd'd into the worktree) rather than
cd <main-checkout> && claude -p. Anchoring the worker to the
runner's worktree path prevents it from inheriting the main
checkout's branch state; omitting this causes commits to land on
whatever branch the main checkout happens to be on.
For any same-repo Task dispatch that creates a branch and modifies
files, use isolation: "worktree". No external tool required --
the Task tool provides this natively.
# Dispatch with worktree isolation (same-repo runner work)
Task(subagent_type: "runner", isolation: "worktree", prompt: ...)
# => if agent made changes, returns {path: "/tmp/wt-xxx", branch: "fix/whatever"}
# => if agent made no changes, worktree is cleaned up automatically
# Push from the returned worktree path
git -C <returned-path> push -u origin <returned-branch>
# Dispatcher removes the worktree after push
git worktree remove <returned-path>
Cross-repo dispatches and read-only dispatches do not need worktree isolation -- there is no collision risk.
The branch + empty commit + push + draft PR setup still happens in the dispatcher's main checkout BEFORE firing the isolated runner dispatch. Only the runner's file-modification work runs inside the worktree.
subagent_type controls which tools the spawned subagent can use.
Known values:
| type | tools available | when to use |
|---|---|---|
general-purpose | all tools | default when no type specified |
explore | Glob, Grep, LS, Read, WebFetch, WebSearch (no Edit/Write/Bash) | dispatcher gather-context step; prevents accidental edits |
plan | all tools except Task, ExitPlanMode, Edit, Write, NotebookEdit | design-before-impl shapes |
bash | Bash only | scripted one-shots, CI steps |
runner / dispatcher | per the installed agent definition | this project's custom named agents under ~/.claude/agents/ |
Pass model: haiku | sonnet | opus to override the model per dispatch:
haiku -- quick reads, exploration, mechanical taskssonnet -- implementation (default for most dispatches)opus -- high-stakes design decisions, hard algorithmic problemsPass effort: low | medium | high | xhigh | max to hint at thinking budget:
low / medium -- exploration, mechanical changes, quick readshigh -- standard implementation (default)xhigh / max -- hard algorithmic problems or complex designExample combining both:
Task(subagent_type: "explore", model: "haiku", effort: "low", prompt: "...")
Task(subagent_type: "runner", model: "sonnet", effort: "high", prompt: "...")
Task tool subagents receive only what their prompt contains -- they have no access to the parent conversation history. Every piece of context needed must be in the prompt.
The Task tool spawns a subagent in the parent's cwd. There's
no way to change it without worktree isolation. If the subagent
must operate in a different directory (e.g. a project root
different from your current working directory), you MUST use a
Bash-based dispatch with -C or cd.
This is the load-bearing reason the workspace dispatcher dispatches orchestrators via Bash, not via Task tool: each dispatcher must run in its own project's cwd to pick up the right CLAUDE.md + repo state.
Task tool subagents share the parent's process and resource model. A long-running Task subagent ties up your session; if your session crashes, the subagent goes with it.
Bash-based dispatches are separate processes. They survive your
session crashing. Their state (output, exit code) is independently
inspectable. They can be backgrounded with run_in_background=true
and their completion notification re-enters your session
asynchronously.
For long-running dispatch (large refactors, multi-task batches), prefer Bash-based dispatch even when cwd doesn't require it.
Default to Task tool (with isolation: "worktree" for file-
modifying same-repo work). Reach for Bash + claude -p for
cross-project, different-cwd, or long-running work.
The two-option choice covers ~95% of real dispatch needs.
isolation: "worktree".claude -p call run in the foreground blocks your session and
produces no output until it exits. Always use run_in_background
for dispatches expected to run more than a few seconds; see
dispatch-wait-react for the
coordination pattern.cd <main-checkout> && claude -p causes the worker to inherit
the main checkout's branch state. Commits land on whatever branch
the main checkout happens to be on -- not the runner's intended
branch. Always cd into the runner's dedicated worktree path
before firing the worker.orchestration-patterns --
pick the execution shape before picking the dispatch mechanism;
the shape determines which option fits.orchestration-prompt-template
-- how to compose the prompt for the chosen dispatch mechanism.dispatch-wait-react --
coordinating with the dispatched session after it fires, including
the background + notification pattern for long-running dispatches.npx claudepluginhub joshrotenberg/agent-tools --plugin agent-toolsCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.