Subagent Orchestration

In a nutshell: keep the main conversation in control and delegate concrete implementation to Claude Code, Codex, or regular subagents — they can run independently, feed results back, and be brought to the foreground at any time.

When to break a task into subagents

• Complex engineering tasks that require architecture, implementation, and review in parallel.
• Long-running background work where you still want to monitor progress.
• Avoiding the main conversation being buried in implementation details.

Spawning a subagent — minimum steps

1. Select an Orchestrator-type Agent, or enable the "spawn subagents" tool in any Agent.
2. The main agent calls claude_code / codex / create_subagent, naming them as needed.
3. Subagents run in the background; the main conversation can switch back at any time or continue receiving messages.
4. When a subagent finishes or waits for input, it automatically flows back to the main conversation.

Three types of subagents to choose from

• Claude Code subagent: calls the Claude Code SDK. Best for architecture / Review / multi-file refactors.
• Codex subagent: calls the Codex CLI. Best for code generation / refactoring / testing.
• Regular subagent: runs a mini-session inside Claw; can be resumed later (subagent transcript).

Naming constraints and backflow identification

Subagent name must be ≤ 30 characters, using only lowercase alphanumeric characters and hyphens. Include intent in the name (e.g., code-reviewer / architect-orderflow) so it is easy to identify in the backflow.

Foreground / background mode

The main agent can specify whether a subagent runs in foreground or background:

• Foreground: the user can interact with it directly (interleaved bubbles within the same session).
• Background: runs silently; flows back to the main agent on completion or when waiting for input.

Credential inheritance order

When a subagent calls an LLM, credentials are inherited in this order:

1. The Connection explicitly assigned to that tool in the Agent configuration.
2. The main agent's current LLM Connection.
3. The user's default Connection.

Claude Code subagents additionally support the local reclaude mode (see LLM & Credentials).

Resumability and transcript

Subagents retain a backingId. Users can explicitly resume them from the session history panel at any time. The full message log is viewable via the Client's "Subagent Detail" modal and can be read as a virtual transcript at /.agent/{id}/transcript.txt.

Waiting for input and TASK_COMPLETE

• When a subagent generates an ask_user_question, the main agent is automatically woken to a waiting state.
• Users can also proactively jump into the subagent conversation to reply directly.
• On completion, the attached TASK_COMPLETE signal is rendered as a completion card in Client / Mobile.

Current known limitations

Related

• Agent Configuration
• LLM & Credentials
• Cross-conversation Memory