ARCANAArcana's subagent system is how a single user request becomes parallel work. When the agent determines that a task is large enough to benefit from decomposition, it delegates subtasks to child sessions that run concurrently and report back.
Think of it like a team lead assigning tasks. You give the agent a high-level goal: "Refactor the authentication module, update the tests, and refresh the documentation." Instead of doing all three sequentially, the agent spawns subagents to work on each piece in parallel. The results come back to the parent, which merges them into a coherent whole.
This is not just about speed. Parallel execution means the agent can work on multiple parts of a codebase simultaneously, which reduces the chance of conflicts between changes. It also means the parent agent retains a high-level view of the work while children handle the details.
How Delegation Works
The parent agent retains a reference to each child session. Children run independently, with their own context windows and tool access. The parent can read child outputs, approve or reject actions, and merge results.
Each child session is a full Arcana session. It has its own conversation history, its own tool access, and its own context window. The child does not share context with the parent or with other children. This isolation is important: it means a context limit hit in one child does not affect the others.
In the TUI, child sessions appear as expandable spine entries. You can click to expand and see the child's full conversation, or watch the live progress indicator as work happens. The spine entry shows the child's name, current status, and a summary of what it has accomplished so far.
Live Progress
Each subagent spine entry shows real-time status: which tools it is calling, what files it is reading, and a progress summary. This is not a post-hoc log but a live stream. You see the child working as it works.
The live progress display updates as the child makes tool calls. When the child reads a file, you see the file path. When it runs a command, you see the command. When it writes a change, you see the diff. This transparency is valuable for understanding what the agent is actually doing, especially when you delegated a complex task and want to verify the child is on the right track.
Approval Attribution
When a child session needs permission (file edit, git commit, network request), the approval prompt shows which subagent is asking and why. The parent session's approval decisions propagate to children. Approve once at the parent level and the child continues without interruption.
This attribution matters. Without it, you would see a permission prompt and not know whether the parent or a child was asking. With attribution, you can make informed decisions: approve the child that is editing test files, but reject the one that is trying to modify production config.
Self-Healing Resolution
If a child session encounters an error (API timeout, tool failure, context limit), it does not just fail. The subagent system attempts resolution: retrying with backoff, falling back to alternative tools, or asking the parent for guidance. Only unrecoverable failures propagate upward.
The self-healing system follows a hierarchy:
- Retry. Transient failures (network timeouts, rate limits) are retried with exponential backoff. Most transient failures resolve within 2-3 retries.
- Fallback. If a tool fails, the child tries an alternative approach. If the primary search tool fails, it falls back to file reading. If the primary model is rate-limited, it switches to a secondary model.
- Escalate. If retry and fallback both fail, the child asks the parent for guidance. The parent can provide context, adjust the task, or abort the child.
Session Linking
Parent and child sessions share a session graph. You can navigate between them in the TUI, see the full delegation tree, and trace how a high-level request decomposed into specific actions. This is valuable for debugging and for understanding what the agent actually did.
The session graph also enables cross-child communication. If one child completes a task that another child needs, the parent can relay information between them. This is not automatic (the parent decides what to relay) but it enables coordinated work across parallel sessions.
When to Use Subagents
Subagents add overhead. Each child session consumes API tokens, occupies a context window, and requires coordination from the parent. A single-file edit does not benefit from delegation.
Subagents make sense when:
- Multi-file refactors. Changes that span many files benefit from parallel execution. The parent coordinates while children handle individual files.
- Research tasks. Tasks that require reading many documents, searching multiple codebases, or comparing several sources are natural candidates for delegation.
- Mixed workflows. Tasks that combine code changes with documentation updates, testing, and deployment checks can be split across specialized children.
- Long-running tasks. Tasks that take minutes to complete benefit from delegation because the parent remains responsive to user input while children work in the background.
The agent decides when to delegate based on task complexity. You can also force delegation with /delegate in the TUI. This command works identically on Linux, macOS, and Windows.