Subagents

A subagent is an agent that another agent starts to handle one piece of work, such as searching the codebase, reviewing a change or writing tests. It runs in its own session with its own prompt, model and permissions, then reports back. This keeps your main conversation focused, and lets Hull work on several things in parallel.

Any primary agent can delegate work to subagents.

How subagents runCopy Anchor Link

• The main agent starts a subagent with the task tool, based on the subagent's description.
• The subagent works in a separate session with its own history. You can open it to watch.
• When it finishes, its result goes back to the main agent.
• Unless it has its own model, a subagent uses the same model as the agent that started it.

You can also start one yourself by mentioning it:

@code-reviewer check the new auth middleware for security problems

Built-in subagentsCopy Anchor Link

Create a subagentCopy Anchor Link

A subagent is a custom agent with mode: subagent. Create a Markdown file in .hull/agents/ (project) or ~/.config/hull/agents/ (global):

.hull/agents/code-reviewer.md:

---
description: Reviews code changes for bugs, security problems and readability. Use after making non-trivial changes.
mode: subagent
permission:
  edit: deny
  bash:
    "*": deny
    "git diff *": allow
    "git log *": allow
---

You are a careful code reviewer. Look for bugs, security problems,
missing error handling and unclear code. Don't change files. Report
each finding with the file, line and a suggested fix.

Or define it in hull.json:

{
  "agent": {
    "test-writer": {
      "description": "Writes tests for existing code, following the project's test patterns",
      "mode": "subagent",
      "prompt": "{file:./prompts/test-writer.md}",
      "steps": 30
    }
  }
}

Or run hull agent create and choose subagent as the mode.

Write a specific description. It's what the main agent reads when it decides whether to delegate.

See Custom agents for every option. Two are specific to subagents:

• hidden: true hides the subagent from the @ menu. Agents can still start it.
• mode: all makes an agent usable both as a primary agent and as a subagent.

Control delegationCopy Anchor Link

Use the task permission to choose which subagents an agent may start:

{
  "agent": {
    "code": {
      "permission": {
        "task": { "*": "deny", "explore": "allow", "code-reviewer": "allow" }
      }
    }
  }
}

Each subagent's own permission rules apply to what it does. See Permissions.

See your agentsCopy Anchor Link

Run hull agent list to see every agent and its mode, or hull debug agent <name> for the full configuration of one.

Change a built-in subagentCopy Anchor Link

Use its name in hull.json:

{
  "agent": {
    "explore": { "steps": 20 },
    "general": { "disable": true }
  }
}

RelatedCopy Anchor Link

• Custom agents
• Permissions
• Agent Manager, for running full sessions in parallel worktrees