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 anExAthena.Agentsdefinition (e.g."explore"). The definition'smodel,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.