feat: implement delegate tool for agent task management

- Add delegate tool for launching and managing asynchronous agent processes
- Support agent validation with approval UI for security
- Enable status checking for individual agents or all agents
- Implement background process monitoring and execution tracking
- Store execution state in ~/.aws/amazonq/.subagents/
- Support both global (~/.aws/amazonq/cli-agents/) and local (.amazonq/cli-agents/) agent configurations
- Add experimental flag for delegate functionality
- Clean error handling with proper agent not found messages
- Unicode characters instead of emojis for better terminal compatibility

The delegate tool allows users to offload tasks to specialized agents that run independently,
enabling parallel work and better task organization. Agents require user approval before
execution for security, and the tool provides comprehensive status tracking.

Author: abhraina-aws

crates/chat-cli/src/cli/chat/cli/experiment.rs

@@ -50,6 +50,11 @@ static AVAILABLE_EXPERIMENTS: &[Experiment] = &[
         description: "Enables Q to create todo lists that can be viewed and managed using /todos",
         setting_key: Setting::EnabledTodoList,
     },
+    Experiment {
+        name: "Delegate",
+        description: "Enables launching and managing asynchronous subagent processes",
+        setting_key: Setting::EnabledDelegate,
+    },
 ];
 
 #[derive(Debug, PartialEq, Args)]

crates/chat-cli/src/cli/chat/tool_manager.rs

@@ -71,6 +71,7 @@ use crate::cli::chat::server_messenger::{
     UpdateEventMessage,
 };
 use crate::cli::chat::tools::custom_tool::CustomTool;
+use crate::cli::chat::tools::delegate::Delegate;
 use crate::cli::chat::tools::execute::ExecuteCommand;
 use crate::cli::chat::tools::fs_read::FsRead;
 use crate::cli::chat::tools::fs_write::FsWrite;
@@ -728,6 +729,9 @@ impl ToolManager {
             if !crate::cli::chat::tools::todo::TodoList::is_enabled(os) {
                 tool_specs.remove("todo_list");
             }
+            if !os.database.settings.get_bool(Setting::EnabledDelegate).unwrap_or(false) {
+                tool_specs.remove("delegate");
+            }
 
             #[cfg(windows)]
             {
@@ -873,6 +877,7 @@ impl ToolManager {
             "thinking" => Tool::Thinking(serde_json::from_value::<Thinking>(value.args).map_err(map_err)?),
             "knowledge" => Tool::Knowledge(serde_json::from_value::<Knowledge>(value.args).map_err(map_err)?),
             "todo_list" => Tool::Todo(serde_json::from_value::<TodoList>(value.args).map_err(map_err)?),
+            "delegate" => Tool::Delegate(serde_json::from_value::<Delegate>(value.args).map_err(map_err)?),
             // Note that this name is namespaced with server_name{DELIMITER}tool_name
             name => {
                 // Note: tn_map also has tools that underwent no transformation. In otherwords, if

crates/chat-cli/src/cli/chat/tools/delegate/agent_manager.rs

@@ -0,0 +1,92 @@
+use std::collections::HashMap;
+
+use eyre::{
+    Result,
+    eyre,
+};
+
+use crate::cli::chat::tools::delegate::agent_paths::AgentPaths;
+use crate::cli::chat::tools::delegate::errors::AgentError;
+use crate::cli::chat::tools::delegate::file_ops::{
+    load_json,
+    save_json,
+};
+use crate::cli::chat::tools::delegate::types::{
+    AgentConfig,
+    AgentExecution,
+};
+use crate::cli::chat::tools::delegate::ui::{
+    display_agent_info,
+    display_default_agent_warning,
+    get_user_confirmation,
+};
+use crate::os::Os;
+
+const DEFAULT_AGENT: &str = "default";
+
+pub async fn validate_agent_availability(os: &Os, agent: &str) -> Result<()> {
+    if let Some(existing) = load_agent_execution(os, agent).await? {
+        if existing.is_active() {
+            return Err(eyre!("{}", AgentError::already_running(agent)));
+        }
+    }
+
+    if agent != DEFAULT_AGENT {
+        let agents_config = load_available_agents(os).await?;
+        if !agents_config.contains_key(agent) {
+            let available: Vec<String> = agents_config.keys().cloned().collect();
+            return Err(eyre!("{}", AgentError::not_found(agent, &available)));
+        }
+    }
+
+    Ok(())
+}
+
+pub async fn request_user_approval(os: &Os, agent: &str, task: &str) -> Result<()> {
+    if agent != DEFAULT_AGENT {
+        let agents_config = load_available_agents(os).await?;
+        if let Some(agent_config) = agents_config.get(agent) {
+            display_agent_info(agent, task, agent_config)?;
+            if !get_user_confirmation()? {
+                return Err(eyre!("✗ Task delegation cancelled by user."));
+            }
+        }
+    } else {
+        display_default_agent_warning()?;
+    }
+    Ok(())
+}
+
+pub async fn load_agent_execution(os: &Os, agent: &str) -> Result<Option<AgentExecution>> {
+    let file_path = AgentPaths::agent_file(os, agent).await?;
+    load_json(os, &file_path).await
+}
+
+pub async fn save_agent_execution(os: &Os, execution: &AgentExecution) -> Result<()> {
+    let file_path = AgentPaths::agent_file(os, &execution.agent).await?;
+    save_json(os, &file_path, execution).await
+}
+
+pub async fn load_available_agents(os: &Os) -> Result<HashMap<String, AgentConfig>> {
+    let agents_dir = AgentPaths::cli_agents_dir(os).await?;
+    let mut agents = HashMap::new();
+
+    if agents_dir.exists() {
+        if let Ok(entries) = std::fs::read_dir(&agents_dir) {
+            for entry in entries.flatten() {
+                if let Some(file_name) = entry.file_name().to_str() {
+                    if file_name.ends_with(".json") {
+                        let agent_name = file_name.trim_end_matches(".json");
+                        if let Ok(content) = std::fs::read_to_string(entry.path()) {
+                            if let Ok(config) = serde_json::from_str::<AgentConfig>(&content) {
+                                agents.insert(agent_name.to_string(), config);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    Ok(agents)
+}

crates/chat-cli/src/cli/chat/tools/delegate/agent_paths.rs

@@ -0,0 +1,30 @@
+use std::path::PathBuf;
+
+use eyre::Result;
+
+use crate::os::Os;
+
+pub struct AgentPaths;
+
+impl AgentPaths {
+    pub async fn subagents_dir(os: &Os) -> Result<PathBuf> {
+        let home_dir = os.env.home().unwrap_or_default();
+        let agents_dir = home_dir.join(".aws").join("amazonq").join(".subagents");
+
+        if !agents_dir.exists() {
+            std::fs::create_dir_all(&agents_dir)?;
+        }
+
+        Ok(agents_dir)
+    }
+
+    pub async fn cli_agents_dir(os: &Os) -> Result<PathBuf> {
+        let home_dir = os.env.home().unwrap_or_default();
+        Ok(home_dir.join(".aws").join("amazonq").join("cli-agents"))
+    }
+
+    pub async fn agent_file(os: &Os, agent: &str) -> Result<PathBuf> {
+        let agents_dir = Self::subagents_dir(os).await?;
+        Ok(agents_dir.join(format!("{}.json", agent)))
+    }
+}

crates/chat-cli/src/cli/chat/tools/delegate/errors.rs

@@ -0,0 +1,27 @@
+pub struct AgentError;
+
+impl AgentError {
+    pub fn not_found(agent: &str, available: &[String]) -> String {
+        if available.is_empty() {
+            format!(
+                "✗ I can't find agent '{}'. No agents are configured. You need to set up agents first.",
+                agent
+            )
+        } else {
+            format!(
+                "✗ I can't find agent '{}'. Available agents: {}\n\nPlease use one of the available agents or set up the '{}' agent first.",
+                agent,
+                available.join(", "),
+                agent
+            )
+        }
+    }
+
+    pub fn already_running(agent: &str) -> String {
+        format!("Agent '{}' is already running a task", agent)
+    }
+
+    pub fn no_execution_found(agent: &str) -> String {
+        format!("No execution found for agent '{}'", agent)
+    }
+}

crates/chat-cli/src/cli/chat/tools/delegate/file_ops.rs

@@ -0,0 +1,23 @@
+use std::path::Path;
+
+use eyre::Result;
+use serde::Serialize;
+use serde::de::DeserializeOwned;
+
+use crate::os::Os;
+
+pub async fn load_json<T: DeserializeOwned>(os: &Os, path: &Path) -> Result<Option<T>> {
+    if !path.exists() {
+        return Ok(None);
+    }
+
+    let content = os.fs.read_to_string(path).await?;
+    let data: T = serde_json::from_str(&content)?;
+    Ok(Some(data))
+}
+
+pub async fn save_json<T: Serialize>(os: &Os, path: &Path, data: &T) -> Result<()> {
+    let content = serde_json::to_string_pretty(data)?;
+    os.fs.write(path, content).await?;
+    Ok(())
+}

crates/chat-cli/src/cli/chat/tools/delegate/mod.rs

@@ -0,0 +1,138 @@
+mod agent_manager;
+mod agent_paths;
+mod errors;
+mod file_ops;
+mod process;
+mod status;
+mod types;
+mod ui;
+
+// Re-export types for external use
+use std::io::Write;
+
+use agent_manager::{
+    request_user_approval,
+    validate_agent_availability,
+};
+use eyre::{
+    Result,
+    eyre,
+};
+use process::{
+    format_launch_success,
+    spawn_agent_process,
+    start_monitoring,
+};
+use serde::{
+    Deserialize,
+    Serialize,
+};
+use status::{
+    status_agent,
+    status_all_agents,
+};
+#[allow(unused_imports)]
+pub use types::{
+    AgentConfig,
+    AgentExecution,
+    AgentStatus,
+};
+
+use crate::cli::chat::tools::{
+    InvokeOutput,
+    OutputKind,
+};
+use crate::database::settings::Setting;
+use crate::os::Os;
+
+const OPERATION_LAUNCH: &str = "launch";
+const OPERATION_STATUS: &str = "status";
+const DEFAULT_AGENT: &str = "default";
+const ALL_AGENTS: &str = "all";
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Delegate {
+    /// Operation to perform: launch or status
+    pub operation: String,
+    /// Agent name to use (optional - uses "default_agent" if not specified)
+    #[serde(default)]
+    pub agent: Option<String>,
+    /// Task description (required for launch operation)
+    #[serde(default)]
+    pub task: Option<String>,
+}
+
+impl Delegate {
+    pub async fn invoke(&self, os: &Os, _stdout: &mut impl Write) -> Result<InvokeOutput> {
+        if !is_enabled(os) {
+            return Ok(InvokeOutput {
+                output: OutputKind::Text(
+                    "Delegate tool is experimental and not enabled. Use /experiment to enable it.".to_string(),
+                ),
+            });
+        }
+
+        let agent_name = self.get_agent_name();
+        let result = match self.operation.as_str() {
+            OPERATION_LAUNCH => {
+                let task = self
+                    .task
+                    .as_ref()
+                    .ok_or_else(|| eyre!("Task description required for launch operation"))?;
+                launch_agent(os, agent_name, task).await?
+            },
+            OPERATION_STATUS => {
+                if agent_name == ALL_AGENTS {
+                    status_all_agents(os).await?
+                } else {
+                    status_agent(os, agent_name).await?
+                }
+            },
+            _ => {
+                return Err(eyre!(
+                    "Invalid operation. Use: {} or {}",
+                    OPERATION_LAUNCH,
+                    OPERATION_STATUS
+                ));
+            },
+        };
+
+        Ok(InvokeOutput {
+            output: OutputKind::Text(result),
+        })
+    }
+
+    pub fn queue_description(&self, output: &mut impl Write) -> Result<()> {
+        let agent_name = self.get_agent_name();
+        match self.operation.as_str() {
+            OPERATION_LAUNCH => writeln!(output, "Launching agent '{}'", agent_name)?,
+            OPERATION_STATUS => writeln!(output, "Checking status of agent '{}'", agent_name)?,
+            _ => writeln!(
+                output,
+                "Delegate operation '{}' on agent '{}'",
+                self.operation, agent_name
+            )?,
+        }
+        Ok(())
+    }
+
+    fn get_agent_name(&self) -> &str {
+        match self.operation.as_str() {
+            OPERATION_LAUNCH => self.agent.as_deref().unwrap_or(DEFAULT_AGENT),
+            OPERATION_STATUS => self.agent.as_deref().unwrap_or(ALL_AGENTS),
+            _ => self.agent.as_deref().unwrap_or(DEFAULT_AGENT),
+        }
+    }
+}
+
+async fn launch_agent(os: &Os, agent: &str, task: &str) -> Result<String> {
+    validate_agent_availability(os, agent).await?;
+    request_user_approval(os, agent, task).await?;
+    let execution = spawn_agent_process(os, agent, task).await?;
+    start_monitoring(execution, os.clone()).await;
+    Ok(format_launch_success(agent, task))
+}
+
+fn is_enabled(os: &Os) -> bool {
+    os.database.settings.get_bool(Setting::EnabledDelegate).unwrap_or(false)
+}