Sub-agents and Delegation

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.

Existing catalog specialists

The default awesome-sub-agents catalog 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:

Read Sub-agent Catalog 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.

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.

---
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.

{
  "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

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.

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:

{
  "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.

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. 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

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.