# `ExAthena.Tools.SpawnAgent`
[🔗](https://github.com/udin-io/ex_athena/blob/v0.7.1/lib/ex_athena/tools/spawn_agent.ex#L1)

Synchronously run a sub-agent-loop with its own prompt, tools, and budget.

Useful for delegating a bounded task (exploring a codebase, summarising a
file) to a fresh conversation with its own message history — so the parent
loop doesn't pay the token cost of the sub-task's intermediate steps.

Arguments:

  * `prompt` (required) — the sub-agent's opening message.
  * `agent` (optional) — name of an `ExAthena.Agents` definition (e.g.
    `"explore"`). The definition's `model`, `provider`, `tools`,
    `permissions`, `mode`, `isolation`, and system-prompt body apply
    automatically; explicit args still override.
  * `tools` (optional) — list of tool names to expose to the sub-agent; defaults
    to whatever the parent had (minus PlanMode + SpawnAgent to avoid loops).
  * `max_iterations` (optional, default 10) — cap on agent-loop iterations.
  * `system_prompt` (optional) — system prompt override for the sub-agent.

Inherits the parent's provider / model / permissions unless overridden in
`ctx.assigns[:spawn_agent_opts]`.

## Worktree isolation

When the chosen agent definition declares `isolation: :worktree` and the
parent's cwd is a clean git repo with `git` on PATH, the subagent runs
in a freshly-created worktree under `~/.cache/ex_athena/worktrees/<sess>/<name>-<n>`.
If safety checks fail, the subagent transparently falls back to
`:in_process` — no error.

---

*Consult [api-reference.md](api-reference.md) for complete listing*