feat: agent-to-agent handoff and delegation

* feat: add agent-to-agent delegation tool

Add `delegate` tool enabling multi-agent workflows where a primary agent
can hand off subtasks to specialized sub-agents with different
provider/model configurations.

- New `DelegateAgentConfig` in config schema with provider, model,
  system_prompt, api_key, temperature, and max_depth fields
- `delegate` tool with recursion depth limits to prevent infinite loops
- Agents configured via `[agents.<name>]` TOML sections
- Sub-agents use `ReliableProvider` with fallback API key support
- Backward-compatible: empty agents map when section is absent

Closes #218

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: encrypt agent API keys and tighten delegation input validation

Address CodeRabbit review comments on PR #224:

1. Agent API key encryption (schema.rs):
   - Config::load_or_init() now decrypts agents.*.api_key via SecretStore
   - Config::save() encrypts plaintext agent API keys before writing
   - Updated doc comment to document encryption behavior
   - Added tests for encrypt-on-save and plaintext-when-disabled

2. Delegation input validation (delegate.rs):
   - Added "additionalProperties": false to schema
   - Added "minLength": 1 for agent and prompt fields
   - Trim agent/prompt/context inputs, reject empty after trim
   - Added tests for blank agent, blank prompt, whitespace trimming

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(delegate): replace mutable depth counter with immutable field

- Replace `current_depth: Arc<AtomicU32>` with `depth: u32` set at
  construction time, eliminating TOCTOU race and cancel/panic safety
  issues from fetch_add/fetch_sub pattern
- When sub-agents get their own tool registry, construct via
  `with_depth(agents, key, parent.depth + 1)` for proper propagation
- Add tokio::time::timeout (120s) around provider calls to prevent
  indefinite blocking from misbehaving sub-agent providers
- Rename misleading test whitespace_agent_name_not_found →
  whitespace_agent_name_trimmed_and_found

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* style: fix rustfmt formatting issues

Fixed all formatting issues reported by cargo fmt to pass CI lint checks.
- Line length adjustments
- Chain formatting consistency
- Trailing whitespace cleanup

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Edvard <ecschoye@stud.ntnu.no>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

src/tools/delegate.rs

@@ -0,0 +1,426 @@
+use super::traits::{Tool, ToolResult};
+use crate::config::DelegateAgentConfig;
+use crate::providers::{self, Provider};
+use async_trait::async_trait;
+use serde_json::json;
+use std::collections::HashMap;
+use std::sync::Arc;
+use std::time::Duration;
+
+/// Default timeout for sub-agent provider calls.
+const DELEGATE_TIMEOUT_SECS: u64 = 120;
+
+/// Tool that delegates a subtask to a named agent with a different
+/// provider/model configuration. Enables multi-agent workflows where
+/// a primary agent can hand off specialized work (research, coding,
+/// summarization) to purpose-built sub-agents.
+pub struct DelegateTool {
+    agents: Arc<HashMap<String, DelegateAgentConfig>>,
+    /// Global API key fallback (from config.api_key)
+    fallback_api_key: Option<String>,
+    /// Depth at which this tool instance lives in the delegation chain.
+    depth: u32,
+}
+
+impl DelegateTool {
+    pub fn new(
+        agents: HashMap<String, DelegateAgentConfig>,
+        fallback_api_key: Option<String>,
+    ) -> Self {
+        Self {
+            agents: Arc::new(agents),
+            fallback_api_key,
+            depth: 0,
+        }
+    }
+
+    /// Create a DelegateTool for a sub-agent (with incremented depth).
+    /// When sub-agents eventually get their own tool registry, construct
+    /// their DelegateTool via this method with `depth: parent.depth + 1`.
+    pub fn with_depth(
+        agents: HashMap<String, DelegateAgentConfig>,
+        fallback_api_key: Option<String>,
+        depth: u32,
+    ) -> Self {
+        Self {
+            agents: Arc::new(agents),
+            fallback_api_key,
+            depth,
+        }
+    }
+}
+
+#[async_trait]
+impl Tool for DelegateTool {
+    fn name(&self) -> &str {
+        "delegate"
+    }
+
+    fn description(&self) -> &str {
+        "Delegate a subtask to a specialized agent. Use when: a task benefits from a different model \
+         (e.g. fast summarization, deep reasoning, code generation). The sub-agent runs a single \
+         prompt and returns its response."
+    }
+
+    fn parameters_schema(&self) -> serde_json::Value {
+        let agent_names: Vec<&str> = self.agents.keys().map(|s: &String| s.as_str()).collect();
+        json!({
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "agent": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": format!(
+                        "Name of the agent to delegate to. Available: {}",
+                        if agent_names.is_empty() {
+                            "(none configured)".to_string()
+                        } else {
+                            agent_names.join(", ")
+                        }
+                    )
+                },
+                "prompt": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "The task/prompt to send to the sub-agent"
+                },
+                "context": {
+                    "type": "string",
+                    "description": "Optional context to prepend (e.g. relevant code, prior findings)"
+                }
+            },
+            "required": ["agent", "prompt"]
+        })
+    }
+
+    async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult> {
+        let agent_name = args
+            .get("agent")
+            .and_then(|v| v.as_str())
+            .map(str::trim)
+            .ok_or_else(|| anyhow::anyhow!("Missing 'agent' parameter"))?;
+
+        if agent_name.is_empty() {
+            return Ok(ToolResult {
+                success: false,
+                output: String::new(),
+                error: Some("'agent' parameter must not be empty".into()),
+            });
+        }
+
+        let prompt = args
+            .get("prompt")
+            .and_then(|v| v.as_str())
+            .map(str::trim)
+            .ok_or_else(|| anyhow::anyhow!("Missing 'prompt' parameter"))?;
+
+        if prompt.is_empty() {
+            return Ok(ToolResult {
+                success: false,
+                output: String::new(),
+                error: Some("'prompt' parameter must not be empty".into()),
+            });
+        }
+
+        let context = args
+            .get("context")
+            .and_then(|v| v.as_str())
+            .map(str::trim)
+            .unwrap_or("");
+
+        // Look up agent config
+        let agent_config = match self.agents.get(agent_name) {
+            Some(cfg) => cfg,
+            None => {
+                let available: Vec<&str> =
+                    self.agents.keys().map(|s: &String| s.as_str()).collect();
+                return Ok(ToolResult {
+                    success: false,
+                    output: String::new(),
+                    error: Some(format!(
+                        "Unknown agent '{agent_name}'. Available agents: {}",
+                        if available.is_empty() {
+                            "(none configured)".to_string()
+                        } else {
+                            available.join(", ")
+                        }
+                    )),
+                });
+            }
+        };
+
+        // Check recursion depth (immutable — set at construction, incremented for sub-agents)
+        if self.depth >= agent_config.max_depth {
+            return Ok(ToolResult {
+                success: false,
+                output: String::new(),
+                error: Some(format!(
+                    "Delegation depth limit reached ({depth}/{max}). \
+                     Cannot delegate further to prevent infinite loops.",
+                    depth = self.depth,
+                    max = agent_config.max_depth
+                )),
+            });
+        }
+
+        // Create provider for this agent
+        let api_key = agent_config
+            .api_key
+            .as_deref()
+            .or(self.fallback_api_key.as_deref());
+
+        let provider: Box<dyn Provider> =
+            match providers::create_provider(&agent_config.provider, api_key) {
+                Ok(p) => p,
+                Err(e) => {
+                    return Ok(ToolResult {
+                        success: false,
+                        output: String::new(),
+                        error: Some(format!(
+                            "Failed to create provider '{}' for agent '{agent_name}': {e}",
+                            agent_config.provider
+                        )),
+                    });
+                }
+            };
+
+        // Build the message
+        let full_prompt = if context.is_empty() {
+            prompt.to_string()
+        } else {
+            format!("[Context]\n{context}\n\n[Task]\n{prompt}")
+        };
+
+        let temperature = agent_config.temperature.unwrap_or(0.7);
+
+        // Wrap the provider call in a timeout to prevent indefinite blocking
+        let result = tokio::time::timeout(
+            Duration::from_secs(DELEGATE_TIMEOUT_SECS),
+            provider.chat_with_system(
+                agent_config.system_prompt.as_deref(),
+                &full_prompt,
+                &agent_config.model,
+                temperature,
+            ),
+        )
+        .await;
+
+        let result = match result {
+            Ok(inner) => inner,
+            Err(_elapsed) => {
+                return Ok(ToolResult {
+                    success: false,
+                    output: String::new(),
+                    error: Some(format!(
+                        "Agent '{agent_name}' timed out after {DELEGATE_TIMEOUT_SECS}s"
+                    )),
+                });
+            }
+        };
+
+        match result {
+            Ok(response) => Ok(ToolResult {
+                success: true,
+                output: format!(
+                    "[Agent '{agent_name}' ({provider}/{model})]\n{response}",
+                    provider = agent_config.provider,
+                    model = agent_config.model
+                ),
+                error: None,
+            }),
+            Err(e) => Ok(ToolResult {
+                success: false,
+                output: String::new(),
+                error: Some(format!("Agent '{agent_name}' failed: {e}",)),
+            }),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn sample_agents() -> HashMap<String, DelegateAgentConfig> {
+        let mut agents = HashMap::new();
+        agents.insert(
+            "researcher".to_string(),
+            DelegateAgentConfig {
+                provider: "ollama".to_string(),
+                model: "llama3".to_string(),
+                system_prompt: Some("You are a research assistant.".to_string()),
+                api_key: None,
+                temperature: Some(0.3),
+                max_depth: 3,
+            },
+        );
+        agents.insert(
+            "coder".to_string(),
+            DelegateAgentConfig {
+                provider: "openrouter".to_string(),
+                model: "anthropic/claude-sonnet-4-20250514".to_string(),
+                system_prompt: None,
+                api_key: Some("sk-test".to_string()),
+                temperature: None,
+                max_depth: 2,
+            },
+        );
+        agents
+    }
+
+    #[test]
+    fn name_and_schema() {
+        let tool = DelegateTool::new(sample_agents(), None);
+        assert_eq!(tool.name(), "delegate");
+        let schema = tool.parameters_schema();
+        assert!(schema["properties"]["agent"].is_object());
+        assert!(schema["properties"]["prompt"].is_object());
+        assert!(schema["properties"]["context"].is_object());
+        let required = schema["required"].as_array().unwrap();
+        assert!(required.contains(&json!("agent")));
+        assert!(required.contains(&json!("prompt")));
+        assert_eq!(schema["additionalProperties"], json!(false));
+        assert_eq!(schema["properties"]["agent"]["minLength"], json!(1));
+        assert_eq!(schema["properties"]["prompt"]["minLength"], json!(1));
+    }
+
+    #[test]
+    fn description_not_empty() {
+        let tool = DelegateTool::new(sample_agents(), None);
+        assert!(!tool.description().is_empty());
+    }
+
+    #[test]
+    fn schema_lists_agent_names() {
+        let tool = DelegateTool::new(sample_agents(), None);
+        let schema = tool.parameters_schema();
+        let desc = schema["properties"]["agent"]["description"]
+            .as_str()
+            .unwrap();
+        assert!(desc.contains("researcher") || desc.contains("coder"));
+    }
+
+    #[tokio::test]
+    async fn missing_agent_param() {
+        let tool = DelegateTool::new(sample_agents(), None);
+        let result = tool.execute(json!({"prompt": "test"})).await;
+        assert!(result.is_err());
+    }
+
+    #[tokio::test]
+    async fn missing_prompt_param() {
+        let tool = DelegateTool::new(sample_agents(), None);
+        let result = tool.execute(json!({"agent": "researcher"})).await;
+        assert!(result.is_err());
+    }
+
+    #[tokio::test]
+    async fn unknown_agent_returns_error() {
+        let tool = DelegateTool::new(sample_agents(), None);
+        let result = tool
+            .execute(json!({"agent": "nonexistent", "prompt": "test"}))
+            .await
+            .unwrap();
+        assert!(!result.success);
+        assert!(result.error.unwrap().contains("Unknown agent"));
+    }
+
+    #[tokio::test]
+    async fn depth_limit_enforced() {
+        let tool = DelegateTool::with_depth(sample_agents(), None, 3);
+        let result = tool
+            .execute(json!({"agent": "researcher", "prompt": "test"}))
+            .await
+            .unwrap();
+        assert!(!result.success);
+        assert!(result.error.unwrap().contains("depth limit"));
+    }
+
+    #[tokio::test]
+    async fn depth_limit_per_agent() {
+        // coder has max_depth=2, so depth=2 should be blocked
+        let tool = DelegateTool::with_depth(sample_agents(), None, 2);
+        let result = tool
+            .execute(json!({"agent": "coder", "prompt": "test"}))
+            .await
+            .unwrap();
+        assert!(!result.success);
+        assert!(result.error.unwrap().contains("depth limit"));
+    }
+
+    #[test]
+    fn empty_agents_schema() {
+        let tool = DelegateTool::new(HashMap::new(), None);
+        let schema = tool.parameters_schema();
+        let desc = schema["properties"]["agent"]["description"]
+            .as_str()
+            .unwrap();
+        assert!(desc.contains("none configured"));
+    }
+
+    #[tokio::test]
+    async fn invalid_provider_returns_error() {
+        let mut agents = HashMap::new();
+        agents.insert(
+            "broken".to_string(),
+            DelegateAgentConfig {
+                provider: "totally-invalid-provider".to_string(),
+                model: "model".to_string(),
+                system_prompt: None,
+                api_key: None,
+                temperature: None,
+                max_depth: 3,
+            },
+        );
+        let tool = DelegateTool::new(agents, None);
+        let result = tool
+            .execute(json!({"agent": "broken", "prompt": "test"}))
+            .await
+            .unwrap();
+        assert!(!result.success);
+        assert!(result.error.unwrap().contains("Failed to create provider"));
+    }
+
+    #[tokio::test]
+    async fn blank_agent_rejected() {
+        let tool = DelegateTool::new(sample_agents(), None);
+        let result = tool
+            .execute(json!({"agent": "  ", "prompt": "test"}))
+            .await
+            .unwrap();
+        assert!(!result.success);
+        assert!(result.error.unwrap().contains("must not be empty"));
+    }
+
+    #[tokio::test]
+    async fn blank_prompt_rejected() {
+        let tool = DelegateTool::new(sample_agents(), None);
+        let result = tool
+            .execute(json!({"agent": "researcher", "prompt": "  \t  "}))
+            .await
+            .unwrap();
+        assert!(!result.success);
+        assert!(result.error.unwrap().contains("must not be empty"));
+    }
+
+    #[tokio::test]
+    async fn whitespace_agent_name_trimmed_and_found() {
+        let tool = DelegateTool::new(sample_agents(), None);
+        // " researcher " with surrounding whitespace — after trim becomes "researcher"
+        let result = tool
+            .execute(json!({"agent": " researcher ", "prompt": "test"}))
+            .await
+            .unwrap();
+        // Should find "researcher" after trim — will fail at provider level
+        // since ollama isn't running, but must NOT get "Unknown agent".
+        assert!(
+            result.error.is_none()
+                || !result
+                    .error
+                    .as_deref()
+                    .unwrap_or("")
+                    .contains("Unknown agent")
+        );
+    }
+}

src/tools/mod.rs

@@ -1,6 +1,7 @@
 pub mod browser;
 pub mod browser_open;
 pub mod composio;
+pub mod delegate;
 pub mod file_read;
 pub mod file_write;
 pub mod image_info;
@@ -14,6 +15,7 @@ pub mod traits;
 pub use browser::BrowserTool;
 pub use browser_open::BrowserOpenTool;
 pub use composio::ComposioTool;
+pub use delegate::DelegateTool;
 pub use file_read::FileReadTool;
 pub use file_write::FileWriteTool;
 pub use image_info::ImageInfoTool;
@@ -26,9 +28,11 @@ pub use traits::Tool;
 #[allow(unused_imports)]
 pub use traits::{ToolResult, ToolSpec};
 
+use crate::config::DelegateAgentConfig;
 use crate::memory::Memory;
 use crate::runtime::{NativeRuntime, RuntimeAdapter};
 use crate::security::SecurityPolicy;
+use std::collections::HashMap;
 use std::sync::Arc;
 
 /// Create the default tool registry
@@ -54,6 +58,8 @@ pub fn all_tools(
     memory: Arc<dyn Memory>,
     composio_key: Option<&str>,
     browser_config: &crate::config::BrowserConfig,
+    agents: &HashMap<String, DelegateAgentConfig>,
+    fallback_api_key: Option<&str>,
 ) -> Vec<Box<dyn Tool>> {
     all_tools_with_runtime(
         security,
@@ -61,6 +67,8 @@ pub fn all_tools(
         memory,
         composio_key,
         browser_config,
+        agents,
+        fallback_api_key,
     )
 }
 
@@ -71,6 +79,8 @@ pub fn all_tools_with_runtime(
     memory: Arc<dyn Memory>,
     composio_key: Option<&str>,
     browser_config: &crate::config::BrowserConfig,
+    agents: &HashMap<String, DelegateAgentConfig>,
+    fallback_api_key: Option<&str>,
 ) -> Vec<Box<dyn Tool>> {
     let mut tools: Vec<Box<dyn Tool>> = vec![
         Box::new(ShellTool::new(security.clone(), runtime)),
@@ -105,6 +115,14 @@ pub fn all_tools_with_runtime(
         }
     }
 
+    // Add delegation tool when agents are configured
+    if !agents.is_empty() {
+        tools.push(Box::new(DelegateTool::new(
+            agents.clone(),
+            fallback_api_key.map(String::from),
+        )));
+    }
+
     tools
 }
 
@@ -138,7 +156,7 @@ mod tests {
             session_name: None,
         };
 
-        let tools = all_tools(&security, mem, None, &browser);
+        let tools = all_tools(&security, mem, None, &browser, &HashMap::new(), None);
         let names: Vec<&str> = tools.iter().map(|t| t.name()).collect();
         assert!(!names.contains(&"browser_open"));
     }
@@ -160,7 +178,7 @@ mod tests {
             session_name: None,
         };
 
-        let tools = all_tools(&security, mem, None, &browser);
+        let tools = all_tools(&security, mem, None, &browser, &HashMap::new(), None);
         let names: Vec<&str> = tools.iter().map(|t| t.name()).collect();
         assert!(names.contains(&"browser_open"));
     }
@@ -258,4 +276,53 @@ mod tests {
         assert_eq!(parsed.name, "test");
         assert_eq!(parsed.description, "A test tool");
     }
+
+    #[test]
+    fn all_tools_includes_delegate_when_agents_configured() {
+        let tmp = TempDir::new().unwrap();
+        let security = Arc::new(SecurityPolicy::default());
+        let mem_cfg = MemoryConfig {
+            backend: "markdown".into(),
+            ..MemoryConfig::default()
+        };
+        let mem: Arc<dyn Memory> =
+            Arc::from(crate::memory::create_memory(&mem_cfg, tmp.path(), None).unwrap());
+
+        let browser = BrowserConfig::default();
+
+        let mut agents = HashMap::new();
+        agents.insert(
+            "researcher".to_string(),
+            DelegateAgentConfig {
+                provider: "ollama".to_string(),
+                model: "llama3".to_string(),
+                system_prompt: None,
+                api_key: None,
+                temperature: None,
+                max_depth: 3,
+            },
+        );
+
+        let tools = all_tools(&security, mem, None, &browser, &agents, Some("sk-test"));
+        let names: Vec<&str> = tools.iter().map(|t| t.name()).collect();
+        assert!(names.contains(&"delegate"));
+    }
+
+    #[test]
+    fn all_tools_excludes_delegate_when_no_agents() {
+        let tmp = TempDir::new().unwrap();
+        let security = Arc::new(SecurityPolicy::default());
+        let mem_cfg = MemoryConfig {
+            backend: "markdown".into(),
+            ..MemoryConfig::default()
+        };
+        let mem: Arc<dyn Memory> =
+            Arc::from(crate::memory::create_memory(&mem_cfg, tmp.path(), None).unwrap());
+
+        let browser = BrowserConfig::default();
+
+        let tools = all_tools(&security, mem, None, &browser, &HashMap::new(), None);
+        let names: Vec<&str> = tools.iter().map(|t| t.name()).collect();
+        assert!(!names.contains(&"delegate"));
+    }
 }