feat: agent team

docs/tools_configuration.md

@@ -21,6 +21,9 @@ PicoClaw's tools configuration is located in the `tools` field of `config.json`.
     },
     "skills": {
       ...
+    },
+    "team": {
+      ...
     }
   }
 }
@@ -302,6 +305,44 @@ The skills tool configures skill discovery and installation via registries like
 }
 ```
 
+## Team Tool
+
+The team tool allows PicoClaw to orchestrate multiple agents using strategies like Sequential, Parallel, DAG, and Evaluator-Optimizer.
+
+### Global Config
+
+| Config | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `enabled` | bool | false | Enable the Team tool |
+| `max_members` | int | 5 | Max agents in a single team |
+| `max_team_tokens` | int | 0 | Hard ceiling for total token usage per team call (0 = no limit) |
+| `max_evaluator_loops`| int | 5 | Max retries for `evaluator_optimizer` strategy |
+| `max_timeout_minutes`| int | 15 | Max execution time for team tasks |
+| `max_context_runes` | int | 8000 | Max dependency context size between workers |
+| `disable_auto_reviewer` | bool | false | Skip automatic QA reviewer step |
+| `reviewer_model` | string | - | Specifically assigned model for the reviewer step |
+| `allowed_strategies` | array | [] | Whitelist of allowed strategies (empty = all) |
+| `allowed_models` | array | [] | Whitelist of models team members can use |
+
+### Configuration Example
+
+```json
+{
+  "tools": {
+    "team": {
+      "enabled": true,
+      "max_members": 5,
+      "max_team_tokens": 100000,
+      "reviewer_model": "gpt-4o-mini",
+      "allowed_models": [
+        { "name": "gpt-4o", "tags": ["vision", "code"] },
+        { "name": "claude-3-5-sonnet", "tags": ["precise"] }
+      ]
+    }
+  }
+}
+```
+
 ## Environment Variables
 
 All configuration options can be overridden via environment variables with the format `PICOCLAW_TOOLS_<SECTION>_<KEY>`:
@@ -312,6 +353,6 @@ For example:
 - `PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false`
 - `PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10`
 - `PICOCLAW_TOOLS_MCP_ENABLED=true`
+- `PICOCLAW_TOOLS_TEAM_MAX_TEAM_TOKENS=50000`
 
-Note: Nested map-style config (for example `tools.mcp.servers.<name>.*`) is configured in `config.json` rather than
-environment variables.
+Note: Nested map-style config (for example `tools.mcp.servers.<name>.*` or `tools.team.allowed_models`) is configured in `config.json` rather than environment variables.

pkg/agent/context.go

@@ -105,6 +105,8 @@ Your workspace is at: %s
 
 4. **Context summaries** - Conversation summaries provided as context are approximate references only. They may be incomplete or outdated. Always defer to explicit user instructions over summary content.
 
+5. **Team delegation** - For any task that is non-trivial, multi-step, or involves distinct concerns (e.g. "convert React to Vue", "build a feature", "analyze and report"), you MUST use the 'team' tool to delegate and parallelize. Do NOT attempt to handle complex tasks inline by calling tools one by one yourself. Decompose first, delegate second, then report the outcome.
+
 %s`,
 		version, workspacePath, workspacePath, workspacePath, workspacePath, workspacePath, toolDiscovery)
 }
@@ -123,7 +125,7 @@ func (cb *ContextBuilder) getDiscoveryRule() string {
 	}
 
 	return fmt.Sprintf(
-		`5. **Tool Discovery** - Your visible tools are limited to save memory, but a vast hidden library exists. If you lack the right tool for a task, BEFORE giving up, you MUST search using the %s tool. Do not refuse a request unless the search returns nothing. Found tools will temporarily unlock for your next turn.`,
+		`6. **Tool Discovery** - Your visible tools are limited to save memory, but a vast hidden library exists. If you lack the right tool for a task, BEFORE giving up, you MUST search using the %s tool. Do not refuse a request unless the search returns nothing. Found tools will temporarily unlock for your next turn.`,
 		strings.Join(toolNames, " or "),
 	)
 }

pkg/agent/context_cache_test.go

@@ -146,11 +146,11 @@ func TestMtimeAutoInvalidation(t *testing.T) {
 			checkField: "Updated Identity",
 		},
 		{
-			name:       "memory file change",
-			file:       "memory/MEMORY.md",
-			contentV1:  "# Memory\nUser likes Go.",
-			contentV2:  "# Memory\nUser likes Rust.",
-			checkField: "User likes Rust",
+			name:       "another bootstrap file change",
+			file:       "SOUL.md",
+			contentV1:  "# Original Soul",
+			contentV2:  "# Updated Soul",
+			checkField: "Updated Soul",
 		},
 	}
 
@@ -286,10 +286,10 @@ func TestNewFileCreationInvalidatesCache(t *testing.T) {
 			checkField: "Be kind and helpful",
 		},
 		{
-			name:       "new memory file",
-			file:       "memory/MEMORY.md",
-			content:    "# Memory\nUser prefers dark mode.",
-			checkField: "User prefers dark mode",
+			name:       "new agents file",
+			file:       "AGENTS.md",
+			content:    "# Agents\nCustom agent definition.",
+			checkField: "Custom agent definition",
 		},
 	}
 

pkg/agent/instance.go

@@ -1,6 +1,7 @@
 package agent
 
 import (
+
 	"context"
 	"fmt"
 	"log"
@@ -117,6 +118,7 @@ func NewAgentInstance(
 		skillsFilter = agentCfg.Skills
 	}
 
+
 	maxIter := defaults.MaxToolIterations
 	if maxIter == 0 {
 		maxIter = 20

pkg/agent/loop.go

@@ -223,9 +223,33 @@ func registerSharedTools(
 		}
 
 		// Spawn tool with allowlist checker
+		subagentManager := tools.NewSubagentManager(provider, agent.Model, agent.Candidates, agent.Workspace, cfg.Tools.Team, msgBus)
+		subagentManager.SetLLMOptions(agent.MaxTokens, agent.Temperature)
+		spawnTool := tools.NewSpawnTool(subagentManager)
+		currentAgentID := agentID
+		spawnTool.SetAllowlistChecker(func(targetAgentID string) bool {
+			return registry.CanSpawnSubagent(currentAgentID, targetAgentID)
+		})
+		agent.Tools.Register(spawnTool)
+
+		teamTool := tools.NewTeamTool(subagentManager, cfg)
+		if cfg.Tools.IsToolEnabled("team") {
+			agent.Tools.Register(teamTool)
+		}
+
+		spawnSubAgentTool := tools.NewSpawnSubAgentTool(subagentManager)
+		if cfg.Tools.IsToolEnabled("spawn_sub_agent") {
+			agent.Tools.Register(spawnSubAgentTool)
+		}
+
+		// Direction 3: Hierarchical Decomposition.
+		// Share the fully-built registry (which includes team, spawn_sub_agent, etc.) back
+		// to the subagent manager so that all workers spawned by this agent also inherit
+		// the full toolset — enabling sub-agents to recursively call 'team' themselves.
+		subagentManager.SetTools(agent.Tools)
 		if cfg.Tools.IsToolEnabled("spawn") {
 			if cfg.Tools.IsToolEnabled("subagent") {
-				subagentManager := tools.NewSubagentManager(provider, agent.Model, agent.Workspace)
+				subagentManager := tools.NewSubagentManager(provider, agent.Model, agent.Candidates, agent.Workspace, cfg.Tools.Team, msgBus)
 				subagentManager.SetLLMOptions(agent.MaxTokens, agent.Temperature)
 				spawnTool := tools.NewSpawnTool(subagentManager)
 				currentAgentID := agentID

pkg/agent/memory.go

@@ -130,9 +130,10 @@ func (ms *MemoryStore) GetRecentDailyNotes(days int) string {
 }
 
 // GetMemoryContext returns formatted memory context for the agent prompt.
-// Includes long-term memory and recent daily notes.
+// It loads the full MEMORY.md.
 func (ms *MemoryStore) GetMemoryContext() string {
 	longTerm := ms.ReadLongTerm()
+
 	recentNotes := ms.GetRecentDailyNotes(3)
 
 	if longTerm == "" && recentNotes == "" {

pkg/config/config.go

@@ -74,6 +74,24 @@ func (f *FlexibleStringSlice) UnmarshalText(text []byte) error {
 	return nil
 }
 
+type TeamModelConfig struct {
+	Name string   `json:"name"`
+	Tags []string `json:"tags,omitempty"`
+}
+
+type TeamToolsConfig struct {
+	ToolConfig
+	MaxMembers          int               `json:"max_members"`
+	MaxTeamTokens       int               `json:"max_team_tokens"`
+	MaxEvaluatorLoops   int               `json:"max_evaluator_loops"`
+	MaxTimeoutMinutes   int               `json:"max_timeout_minutes"`
+	MaxContextRunes     int               `json:"max_context_runes"`
+	DisableAutoReviewer bool              `json:"disable_auto_reviewer"`
+	ReviewerModel       string            `json:"reviewer_model"`
+	AllowedStrategies   []string          `json:"allowed_strategies"`
+	AllowedModels       []TeamModelConfig `json:"allowed_models"`
+}
+
 type Config struct {
 	Agents    AgentsConfig    `json:"agents"`
 	Bindings  []AgentBinding  `json:"bindings,omitempty"`
@@ -750,6 +768,8 @@ type ToolsConfig struct {
 	Spawn           ToolConfig         `json:"spawn"                                                    envPrefix:"PICOCLAW_TOOLS_SPAWN_"`
 	SPI             ToolConfig         `json:"spi"                                                      envPrefix:"PICOCLAW_TOOLS_SPI_"`
 	Subagent        ToolConfig         `json:"subagent"                                                 envPrefix:"PICOCLAW_TOOLS_SUBAGENT_"`
+	SpawnSubAgent   ToolConfig         `json:"spawn_sub_agent"                                          envPrefix:"PICOCLAW_TOOLS_SPAWN_SUB_AGENT_"`
+	Team            TeamToolsConfig    `json:"team"                                                     envPrefix:"PICOCLAW_TOOLS_TEAM_"`
 	WebFetch        ToolConfig         `json:"web_fetch"                                                envPrefix:"PICOCLAW_TOOLS_WEB_FETCH_"`
 	WriteFile       ToolConfig         `json:"write_file"                                               envPrefix:"PICOCLAW_TOOLS_WRITE_FILE_"`
 }

pkg/tools/edit.go

@@ -2,9 +2,7 @@ package tools
 
 import (
 	"context"
-	"errors"
 	"fmt"
-	"io/fs"
 	"regexp"
 	"strings"
 )
@@ -75,6 +73,12 @@ func (t *EditFileTool) Execute(ctx context.Context, args map[string]any) *ToolRe
 	return SilentResult(fmt.Sprintf("File edited: %s", path))
 }
 
+func (t *EditFileTool) UpgradeToConcurrent() Tool {
+	return &EditFileTool{
+		fs: &ConcurrentFS{baseFS: t.fs},
+	}
+}
+
 type AppendFileTool struct {
 	fs fileSystem
 }
@@ -129,31 +133,25 @@ func (t *AppendFileTool) Execute(ctx context.Context, args map[string]any) *Tool
 	return SilentResult(fmt.Sprintf("Appended to %s", path))
 }
 
-// editFile reads the file via sysFs, performs the replacement, and writes back.
-// It uses a fileSystem interface, allowing the same logic for both restricted and unrestricted modes.
-func editFile(sysFs fileSystem, path, oldText, newText string) error {
-	content, err := sysFs.ReadFile(path)
-	if err != nil {
-		return err
-	}
-
-	newContent, err := replaceEditContent(content, oldText, newText)
-	if err != nil {
-		return err
+func (t *AppendFileTool) UpgradeToConcurrent() Tool {
+	return &AppendFileTool{
+		fs: &ConcurrentFS{baseFS: t.fs},
 	}
+}
 
-	return sysFs.WriteFile(path, newContent)
+// editFile reads the file via sysFs, performs the replacement, and writes back atomically.
+func editFile(sysFs fileSystem, path, oldText, newText string) error {
+	return sysFs.EditFile(path, func(content []byte) ([]byte, error) {
+		return replaceEditContent(content, oldText, newText)
+	})
 }
 
-// appendFile reads the existing content (if any) via sysFs, appends new content, and writes back.
+// appendFile reads the existing content (if any) via sysFs, appends new content, and writes back atomically.
 func appendFile(sysFs fileSystem, path, appendContent string) error {
-	content, err := sysFs.ReadFile(path)
-	if err != nil && !errors.Is(err, fs.ErrNotExist) {
-		return err
-	}
-
-	newContent := append(content, []byte(appendContent)...)
-	return sysFs.WriteFile(path, newContent)
+	return sysFs.EditFile(path, func(content []byte) ([]byte, error) {
+		newContent := append(content, []byte(appendContent)...)
+		return newContent, nil
+	})
 }
 
 // replaceEditContent handles the core logic of finding and replacing a single occurrence of oldText.