---
title: "Sub-agents and Delegation"
source: https://docs.autohand.ai/guides/teams-and-swarms/sub-agents
---

# Sub-agents and Delegation

Give a focused worker a smaller context, a role-specific system prompt, and only the tools it needs. Delegate one task synchronously or run up to five independent tasks as a parallel swarm.

## What a sub-agent is

A sub-agent is a child Autohand agent created from a registered definition. The definition supplies a name, description, system prompt, allowed tools, and optional model override. The parent remains the lead: it chooses the worker, provides the bounded task, receives the result, and decides what to do next.

Delegation is useful for keeping broad exploration, independent review, or specialized analysis out of the lead's context. It is not a substitute for integration. Sub-agents do not share an implicit working memory; every task must include the files, question, constraints, and expected output that worker needs.

## Bundled sub-agents

Autohand ships six definitions. Use these before installing a specialist when the task already matches their tool boundary.

| Agent | Access | Use it for | Do not use it for |
|---|---|---|---|
| researcher | Read-only | Repository maps, architecture traces, conventions, and evidence with file and line references | Patches or command-driven verification |
| reviewer | Read-only | Bugs, security, error handling, performance, and convention review prioritized by severity | Silently fixing its own findings |
| tester | Read/write + commands | Tests that follow project conventions, edge cases, and test execution | Unbounded feature implementation |
| code-cleaner | Read/write + delete | Verified dead code, unused imports, and unreachable functions | Public API removal or uncertain dynamic references |
| docs-writer | Read/write | READMEs, API docs, and guides derived from source behavior | Inventing APIs that were not verified in code |
| todo-resolver | Read/write + commands | Scoped TODO, FIXME, HACK, and XXX markers with related tests | Bulk marker removal without understanding intent |

## Existing catalog specialists

The default [awesome-sub-agents catalog](https://github.com/autohandai/awesome-sub-agents) adds narrower roles. Catalog contents evolve, so ask Autohand to search the live registry before depending on a name. The current catalog is organized into these areas:

| Area | Examples of existing definitions | Typical boundary |
|---|---|---|
| Core development | api-designer, code-mapper, frontend-developer, backend-developer, ui-fixer | Design, map, or implement one application path |
| Language specialists | typescript-pro, golang-pro, rust-engineer, rails-expert, swift-expert | Language- or framework-specific implementation |
| Infrastructure | cloud-architect, kubernetes-specialist, terraform-engineer, sre-engineer | Deployment, reliability, networking, and infrastructure review |
| Quality and security | accessibility-tester, security-auditor, performance-engineer, test-automator | Independent verification and risk findings |
| Data and AI | postgres-pro, database-optimizer, llm-architect, mlops-engineer | Data systems, models, and ML operations |
| Developer experience | build-engineer, dependency-manager, mcp-developer, legacy-modernizer | Build, tooling, migrations, and developer workflows |
| Specialized domains | payment-integration, fintech-engineer, hipaa-compliance, embedded-systems | A regulated or platform-specific domain |
| Business and product | business-analyst, product-manager, technical-writer, ux-researcher | Requirements, prioritization, or audience-facing artifacts |
| Meta orchestration | agent-organizer, multi-agent-coordinator, knowledge-synthesizer, task-distributor | Plan or combine other agents' work |
| Research and analysis | docs-researcher, competitive-analyst, scientific-literature-researcher, research-analyst | Evidence gathering and synthesis |
| AI governance and safety | ai-governance-auditor, model-risk-manager, policy-guardrail-designer | Controls, accountability, and misuse risk |
| Platform engineering | idp-architect, golden-path-designer, backstage-specialist | Internal platform and self-service design |
| LLMOps and evals | eval-engineer, ai-observability-engineer, prompt-regression-tester | Agent evaluation, tracing, and factuality failures |

Read [Sub-agent Catalog](/docs/guides/sub-agent-catalog.html) for approval, persistence, and installation behavior.

## Definition discovery and precedence

Run `/agents definitions` to see the definitions registered for the current session. File-based definitions are loaded first-match-wins in this order:

1.  User definitions in `~/.autohand/agents/`.
2.  Configured external agent directories, in the order listed in configuration.
3.  Bundled Autohand definitions.

Session definitions passed as inline JSON through `--agents` override file-based definitions with the same name. This lets CI or a one-off run inject a narrow role without modifying a persistent user file. Autohand Code does not automatically scan project or Codex agent directories; add any shared project directory through `externalAgents.paths`.

**Override deliberately.** Reusing the name `reviewer` in a higher-priority location replaces the bundled reviewer for that session. Use a distinct name when you want both definitions available.

## Create a custom definition

Use `/agents new` for the interactive wizard; it saves a generated Markdown file under `~/.autohand/agents/`. You can also create a Markdown definition directly. The filename becomes the agent name.

``` markdown
---
description: Reviews billing changes for contract and webhook regressions
tools: read_file, fff_grep, fff_find
model: gpt-5.4
---

You are the billing-contract reviewer for this repository.

For every task:
1. Trace the request from UI to API, provider call, webhook, and persisted state.
2. Treat webhook-confirmed state as authoritative where the repository does.
3. Report findings with file paths, line numbers, and the violated contract.
4. Do not edit files.

Return: severity, evidence, user impact, and the smallest safe correction.
```

Save it as `~/.autohand/agents/billing-contract-reviewer.md` for normal user-wide discovery. Markdown (`.md` or `.markdown`) and JSON definitions are supported. If a Markdown definition omits `tools`, it is treated as unrestricted, so declare the narrowest useful set explicitly.

### Load a repository-owned definition directory

To keep definitions with a project, create a directory such as `.autohand/agents/` and enable it in `~/.autohand/config.json`. Relative paths resolve from the directory where Autohand runs.

``` json
{
  "externalAgents": {
    "enabled": true,
    "paths": [".autohand/agents"]
  }
}
```

External directories load after user definitions, so a same-named user definition still wins. Use distinct names when both roles must remain available.

### Inject a one-run agent

``` bash
autohand --agents '{
  "release-auditor": {
    "description": "Checks release evidence without editing files",
    "prompt": "Verify version, changelog, build, package, and install proof. Cite commands and artifacts.",
    "tools": ["read_file", "fff_grep", "fff_find"]
  }
}' -p "Audit this checkout for release readiness with the release-auditor agent"
```

## Delegate one focused task

Ask the lead to use the named definition and state the task contract. `delegate_task` is a model-facing tool; you describe the delegation in your prompt rather than typing the tool name as a slash command.

``` text
Delegate this to the researcher sub-agent:

Question: Trace how a password reset token is created, stored, validated,
expired, and consumed.
Scope: src/auth, src/mail, and database migrations only.
Mutation policy: read-only.
Output: a numbered flow with file and line references, trust boundaries,
and any missing expiry or replay protection. Do not propose a patch yet.
```

The lead's tool call is equivalent to this payload:

``` json
{
  "agent_name": "researcher",
  "task": "Trace password reset creation, persistence, validation, expiry, and consumption..."
}
```

## Delegate independent tasks in parallel

`delegate_parallel` accepts at most five tasks. Use it when workers do not depend on each other's output and, for write-capable workers, do not touch the same files.

``` text
Use parallel delegation for four independent, read-only reviews of the
current diff:

1. reviewer — correctness, regressions, and error handling.
2. security-auditor — authorization, secrets, injection, and data exposure.
3. accessibility-tester — keyboard, focus, semantics, contrast, and labels.
4. performance-engineer — avoidable I/O, rendering, queries, and hot paths.

Every worker must cite file and line evidence and return only actionable
findings. After all four return, deduplicate them, resolve disagreements,
and order the combined report by severity.
```

Parallel delegation is synchronous from the lead's perspective: the lead receives one labeled result after all child runs settle. If compatible workers need incremental status, task dependencies, reassignment, or direct follow-up messages, use an [Agent Team](/docs/guides/teams-and-swarms/agent-teams.html). Keep direct delegation when exact named roles must receive exact tasks.

## Runtime guardrails

-   **Parallel width:** one `delegate_parallel` call accepts no more than five workers.
-   **Delegation depth:** the default maximum nesting depth is three, preventing recursive agent trees from expanding indefinitely.
-   **Tool filtering:** every child is constrained by the definition's tool list and the active client context.
-   **Approvals:** child tool calls inherit the session's approval path. A delegated task does not bypass permission policy.
-   **Model override:** a definition may request a model, but the task should not depend on model-specific behavior without verification.
-   **Stop events:** successful and failed child completion can emit sub-agent lifecycle data for hooks and observability.

## Write tasks that integrate cleanly

| Weak task | Operational task |
|---|---|
| “Review the backend.” | “Review the current diff in src/api/auth/** for authorization bypasses. Read-only. Return severity, file:line, exploit path, and remediation.” |
| “Fix tests.” | “Own tests/billing/**. Reproduce the three named failures, patch tests only unless production behavior is proven wrong, run the focused suite, and report commands and results.” |
| “Research queues.” | “Compare three durable queue options for Node 24, PostgreSQL persistence, at-least-once delivery, and self-hosting. Cite primary docs and write an ADR-ready matrix.” |

A complete task states the outcome, evidence source, scope, mutation policy, expected artifact, validation command, and stop condition. If two workers need the same file, make their work sequential or give one worker review-only access.

## Troubleshooting

### The agent name is not found

Run `/agents definitions`. Check the filename, `~/.autohand/agents/`, and whether the intended external directory is enabled. For a catalog role, ask Autohand to find and install the exact name first.

### A child tries to use a missing tool

Inspect the definition's `tools` field. Add only the capability the task requires, then reload or restart the session as appropriate. Do not solve a read-only review problem by granting blanket write access.

### Parallel workers return contradictory results

Have the lead compare the underlying evidence, not vote by agent count. Delegate a narrow verification question to a read-only reviewer when the disagreement is load-bearing.

### Parallel edits conflict

Stop the overlapping work, assign explicit file ownership, and rerun sequentially or in isolated worktrees. Never resolve conflicts by discarding a worker's branch without inspecting it.