From cd774ab4bd33c80533fdc212c1414579eaf51ecc Mon Sep 17 00:00:00 2001
From: Hibryda <hibryda@protonmail.com>
Date: Thu, 12 Mar 2026 05:21:26 +0100
Subject: [PATCH] feat: fix subagent delegation for Manager agents

Add multi-agent delegation documentation to Manager system prompt so
Claude knows it can spawn child agents via the Agent tool. Also inject
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 env var for Manager agents.
---
 .../components/Workspace/AgentSession.svelte  |  7 ++++-
 v2/src/lib/utils/agent-prompts.ts             | 31 ++++++++++++++++---
 2 files changed, 33 insertions(+), 5 deletions(-)

diff --git a/v2/src/lib/components/Workspace/AgentSession.svelte b/v2/src/lib/components/Workspace/AgentSession.svelte
index 2757b5c..73cd65c 100644
--- a/v2/src/lib/components/Workspace/AgentSession.svelte
+++ b/v2/src/lib/components/Workspace/AgentSession.svelte
@@ -57,9 +57,14 @@
   });
 
   // Inject BTMSG_AGENT_ID for agent projects so they can use btmsg/bttask CLIs
+  // Manager agents also get CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to enable subagent delegation
   let agentEnv = $derived.by(() => {
     if (!project.isAgent) return undefined;
-    return { BTMSG_AGENT_ID: project.id };
+    const env: Record<string, string> = { BTMSG_AGENT_ID: project.id };
+    if (project.agentRole === 'manager') {
+      env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = '1';
+    }
+    return env;
   });
 
   // Periodic context re-injection timer
diff --git a/v2/src/lib/utils/agent-prompts.ts b/v2/src/lib/utils/agent-prompts.ts
index d3549cb..47c2a31 100644
--- a/v2/src/lib/utils/agent-prompts.ts
+++ b/v2/src/lib/utils/agent-prompts.ts
@@ -317,14 +317,37 @@ function buildTeamSection(group: GroupConfig, myId: string): string {
 
 function buildWorkflowSection(role: GroupAgentRole): string {
   if (role === 'manager') {
-    return `## Your Workflow
+    return `## Multi-Agent Delegation
+
+You can spawn child agents to parallelize work across multiple tasks:
+
+\`\`\`
+Use the Agent tool to launch a subagent:
+Agent "task description for the child agent"
+\`\`\`
+
+Child agents run independently with their own context. Use delegation for:
+- **Parallel research** — send multiple agents to explore different approaches simultaneously
+- **Specialized subtasks** — delegate code review, test writing, or documentation to focused agents
+- **Exploratory analysis** — let a child agent investigate while you continue coordinating
+
+Child agent results appear in the Team Agents panel. You can monitor their progress
+and incorporate their findings into your coordination work.
+
+**When to delegate vs. do it yourself:**
+- Delegate when a task is self-contained and doesn't need your ongoing attention
+- Do it yourself when the task requires cross-project coordination or decision-making
+- Prefer delegation for tasks that would block your main coordination loop
+
+## Your Workflow
 
 1. **Check inbox:** \`btmsg inbox\` — read and respond to all messages
 2. **Review task board:** \`bttask board\` — check status of all tasks
 3. **Coordinate:** Assign new tasks, unblock agents, resolve conflicts
-4. **Monitor:** Check agent status (\`btmsg status\`), follow up on stalled work
-5. **Report:** Summarize progress to the Operator when asked
-6. **Repeat:** Check inbox again — new messages may have arrived
+4. **Delegate:** Spawn child agents for parallelizable work (see above)
+5. **Monitor:** Check agent status (\`btmsg status\`), follow up on stalled work
+6. **Report:** Summarize progress to the Operator when asked
+7. **Repeat:** Check inbox again — new messages may have arrived
 
 **Important:** You are the hub of all communication. If an agent is blocked, YOU unblock them.
 If the Operator sends a message, it's your TOP PRIORITY.`;