Subagents & Delegation

Arcana can delegate tasks to subagents — child sessions that run in parallel with their own context, tools, and governance. Subagents appear in the TUI's command spine with live progress, and their actions are attributed to the parent session for approval tracking.

How It Works

When the main agent encounters a task that can be parallelized or isolated, it spawns a subagent:

1. Delegation — The parent agent creates a child session with a specific task, scope, and capability set.
2. Execution — The subagent runs independently with its own context window and tool access.
3. Progress — Live progress appears in the TUI spine — click to expand and see child messages inline.
4. Attribution — All approval requests from the subagent are attributed to the parent session.
5. Resolution — Results flow back to the parent. If the subagent fails, self-healing retries with adjusted context.

TUI Spine Integration

Subagents appear as collapsible entries in the command spine:

• Live progress — See real-time status while the subagent runs
• Click to expand — Toggle open to reveal child session messages inline
• Child session linking — Each subagent part links to its own child session for full history
• Capability warnings — Delegation warnings surface in the task tool output

Governance & Approvals

Subagents inherit governance from the parent but with attenuated capabilities:

Approval Attribution

When a subagent needs approval for a consequential action, the request is attributed to the parent session. This means:

• The parent sees the approval request in its governance view
• Approving/denying affects the subagent's execution
• All approval history is linked to the parent for audit trails

Capability Delegation

Subagents receive a subset of the parent's capabilities:

• Attenuated permissions — Subagents cannot exceed the parent's capability scope
• Leaf capabilities — Subagents can use delegated leaf capabilities
• Revocation — Revoking the parent's capability cascades to all children

Self-Healing Resolution

When a subagent encounters an empty or failed result, Arcana applies self-healing:

1. Empty completion retry — If a subagent returns empty output, it retries with adjusted context
2. Double-empty failure — Two consecutive empty results trigger a failure with guidance
3. Task-tool happy path — Successful task-tool execution is validated before returning

File Edit Guard

Subagents are subject to the same file-edit guard as the parent agent:

• Line-level analysis — Each file edit is analyzed at the line level with stable rule IDs
• ML evidence — Guard rules are surfaced in RunProof ML evidence for audit
• Dependency manifest detection — Edits to package.json, Cargo.toml, etc. are classified as installs

Examples

Parallel Code Review

User: Review these 3 files for bugs

Agent: I'll review each file in parallel.

[subagent: review src/auth.ts]
[subagent: review src/api.ts]  
[subagent: review src/db.ts]

→ Each subagent runs independently
→ Results aggregate in the parent spine
→ Single approval covers all three reviews

Isolated Test Execution

User: Run the test suite and fix any failures

Agent: Running tests in an isolated subagent.

[subagent: run tests, capture failures, propose fixes]

→ Test execution isolated from main context
→ Failures reported back with fix suggestions
→ Parent approves/denies each fix

Configuration

Subagent behavior is configured in arcana.json:

{
  "agent": {
    "my-reviewer": {
      "description": "Code review subagent",
      "mode": "subagent",
      "permission": {
        "edit": "deny",
        "bash": "ask"
      }
    }
  }
}

Related