feat: implement delegate tool for background agent management

- Add delegate tool with list/launch/status operations
- Validate agent names against available configs
- Run agents silently in background with output capture
- Store execution state in ~/.aws/amazonq/.subagents/
- Include PID monitoring for crash detection
- Require experimental flag enablement

Author: abhraina-aws

.gitignore

@@ -8,6 +8,10 @@ xcuserdata/
 .DS_Store
 node_modules/
 .eslintcache
+
+# Conversation/data files
+/delegate
+/delegatetool
 yarn-error.log
 yarn.lock
 package-lock.json

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.rs

@@ -0,0 +1,132 @@
+use std::path::PathBuf;
+use eyre::Result;
+use serde_json;
+
+use crate::cli::chat::tools::delegate::types::{AgentConfig, AgentExecution};
+use crate::cli::chat::tools::delegate::ui::{display_agent_info, get_user_confirmation};
+use crate::os::Os;
+
+fn home_dir(os: &Os) -> Result<PathBuf> {
+    os.env.home().ok_or_else(|| eyre::eyre!("Could not determine home directory"))
+}
+
+pub async fn validate_agent_availability(_os: &Os, _agent: &str) -> Result<()> {
+    // For now, accept any agent name (no need to print here, will show in approval)
+    Ok(())
+}
+
+pub async fn request_user_approval(os: &Os, agent: &str, task: &str) -> Result<()> {
+    let config = load_agent_config(os, agent).await;
+    display_agent_info(agent, task, &config)?;
+    get_user_confirmation()?;
+    Ok(())
+}
+
+async fn load_agent_config(os: &Os, agent: &str) -> AgentConfig {
+    match load_real_agent_config(os, agent).await {
+        Ok(config) => config,
+        Err(_) => AgentConfig {
+            description: Some(format!("Agent '{}' (no config found)", agent)),
+            allowed_tools: vec!["No tools specified".to_string()],
+        },
+    }
+}
+
+async fn load_real_agent_config(os: &Os, agent: &str) -> Result<AgentConfig> {
+    let cli_agents_dir = home_dir(os)?
+        .join(".aws")
+        .join("amazonq") 
+        .join("cli-agents");
+    
+    let config_path = cli_agents_dir.join(format!("{}.json", agent));
+    if config_path.exists() {
+        let content = os.fs.read_to_string(&config_path).await?;
+        let config: serde_json::Value = serde_json::from_str(&content)?;
+        
+        return Ok(AgentConfig {
+            description: config.get("description")
+                .and_then(|d| d.as_str())
+                .map(|s| s.to_string()),
+            allowed_tools: config.get("allowedTools")
+                .and_then(|t| t.as_array())
+                .map(|arr| arr.iter()
+                    .filter_map(|v| v.as_str())
+                    .map(|s| s.to_string())
+                    .collect())
+                .or_else(|| {
+                    // Fallback to "tools" if "allowedTools" not found
+                    config.get("tools")
+                        .and_then(|t| t.as_array())
+                        .map(|arr| arr.iter()
+                            .filter_map(|v| v.as_str())
+                            .map(|s| s.to_string())
+                            .collect())
+                })
+                .unwrap_or_else(|| vec!["No tools specified".to_string()]),
+        });
+    }
+    
+    Err(eyre::eyre!("Agent config not found"))
+}
+
+pub async fn list_available_agents(os: &Os) -> Result<Vec<String>> {
+    let cli_agents_dir = home_dir(os)?
+        .join(".aws")
+        .join("amazonq") 
+        .join("cli-agents");
+    
+    if !cli_agents_dir.exists() {
+        return Ok(vec![]);
+    }
+    
+    let mut agents = vec![];
+    let mut entries = os.fs.read_dir(&cli_agents_dir).await?;
+    
+    while let Some(entry) = entries.next_entry().await? {
+        let path = entry.path();
+        if let Some(extension) = path.extension() {
+            if extension == "json" {
+                if let Some(stem) = path.file_stem() {
+                    if let Some(agent_name) = stem.to_str() {
+                        agents.push(agent_name.to_string());
+                    }
+                }
+            }
+        }
+    }
+    
+    agents.sort();
+    Ok(agents)
+}
+
+pub async fn load_agent_execution(os: &Os, agent: &str) -> Result<Option<AgentExecution>> {
+    let file_path = agent_file_path(os, agent).await?;
+    
+    if file_path.exists() {
+        let content = os.fs.read_to_string(&file_path).await?;
+        let execution: AgentExecution = serde_json::from_str(&content)?;
+        Ok(Some(execution))
+    } else {
+        Ok(None)
+    }
+}
+
+pub async fn save_agent_execution(os: &Os, execution: &AgentExecution) -> Result<()> {
+    let file_path = agent_file_path(os, &execution.agent).await?;
+    let content = serde_json::to_string_pretty(execution)?;
+    os.fs.write(&file_path, content).await?;
+    Ok(())
+}
+
+async fn agent_file_path(os: &Os, agent: &str) -> Result<PathBuf> {
+    let subagents_dir = subagents_dir(os).await?;
+    Ok(subagents_dir.join(format!("{}.json", agent)))
+}
+
+async fn subagents_dir(os: &Os) -> Result<PathBuf> {
+    let subagents_dir = home_dir(os)?.join(".aws").join("amazonq").join(".subagents");
+    if !subagents_dir.exists() {
+        os.fs.create_dir_all(&subagents_dir).await?;
+    }
+    Ok(subagents_dir)
+}

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

@@ -0,0 +1,126 @@
+use std::process::Command;
+use eyre::Result;
+use chrono::Utc;
+
+use crate::cli::chat::tools::delegate::types::{AgentExecution, AgentStatus};
+use crate::cli::chat::tools::delegate::agent::{save_agent_execution, load_agent_execution};
+use crate::os::Os;
+
+pub async fn spawn_agent_process(os: &Os, agent: &str, task: &str) -> Result<AgentExecution> {
+    let now = Utc::now().to_rfc3339();
+    
+    // Run Q chat with specific agent in background, non-interactive
+    let mut cmd = tokio::process::Command::new("q");
+    cmd.args(["chat", "--agent", agent, task]);
+    
+    // Redirect to capture output (runs silently)
+    cmd.stdout(std::process::Stdio::piped());
+    cmd.stderr(std::process::Stdio::piped());
+    cmd.stdin(std::process::Stdio::null()); // No user input
+    
+    let child = cmd.spawn()?;
+    let pid = child.id().unwrap_or(0);
+    
+    let execution = AgentExecution {
+        agent: agent.to_string(),
+        task: task.to_string(),
+        status: AgentStatus::Running,
+        launched_at: now,
+        completed_at: None,
+        pid,
+        exit_code: None,
+        output: String::new(),
+    };
+
+    save_agent_execution(os, &execution).await?;
+    
+    // Start monitoring with the actual child process
+    tokio::spawn(monitor_child_process(child, execution.clone(), os.clone()));
+    
+    Ok(execution)
+}
+
+async fn monitor_child_process(child: tokio::process::Child, mut execution: AgentExecution, os: Os) {
+    match child.wait_with_output().await {
+        Ok(output) => {
+            execution.status = if output.status.success() {
+                AgentStatus::Completed
+            } else {
+                AgentStatus::Failed
+            };
+            execution.completed_at = Some(Utc::now().to_rfc3339());
+            execution.exit_code = output.status.code();
+            
+            // Combine stdout and stderr into the output field
+            let stdout = String::from_utf8_lossy(&output.stdout);
+            let stderr = String::from_utf8_lossy(&output.stderr);
+            execution.output = if stderr.is_empty() {
+                stdout.to_string()
+            } else {
+                format!("STDOUT:\n{}\n\nSTDERR:\n{}", stdout, stderr)
+            };
+            
+            // Save to ~/.aws/amazonq/.subagents/{agent}.json
+            if let Err(e) = save_agent_execution(&os, &execution).await {
+                eprintln!("Failed to save agent execution: {}", e);
+            }
+        }
+        Err(e) => {
+            execution.status = AgentStatus::Failed;
+            execution.completed_at = Some(Utc::now().to_rfc3339());
+            execution.exit_code = Some(-1);
+            execution.output = format!("Failed to wait for process: {}", e);
+            
+            // Save to ~/.aws/amazonq/.subagents/{agent}.json
+            if let Err(e) = save_agent_execution(&os, &execution).await {
+                eprintln!("Failed to save agent execution: {}", e);
+            }
+        }
+    }
+}
+
+pub async fn status_agent(os: &Os, agent: &str) -> Result<String> {
+    match load_agent_execution(os, agent).await? {
+        Some(mut execution) => {
+            // If status is running, check if PID is still alive
+            if execution.status == AgentStatus::Running {
+                if execution.pid != 0 && !is_process_alive(execution.pid) {
+                    // Process died, mark as failed
+                    execution.status = AgentStatus::Failed;
+                    execution.completed_at = Some(chrono::Utc::now().to_rfc3339());
+                    execution.exit_code = Some(-1);
+                    execution.output = "Process terminated unexpectedly (PID not found)".to_string();
+                    
+                    // Save the updated status
+                    save_agent_execution(os, &execution).await?;
+                }
+            }
+            
+            Ok(execution.format_status())
+        },
+        None => Ok(format!("No execution found for agent '{}'", agent)),
+    }
+}
+
+pub async fn status_all_agents(_os: &Os) -> Result<String> {
+    // For now, just return a simple message
+    Ok("Use --agent <name> to check specific agent status".to_string())
+}
+
+fn is_process_alive(pid: u32) -> bool {
+    #[cfg(unix)]
+    {
+        // Use `kill -0` to check if process exists without actually killing it
+        Command::new("kill")
+            .args(["-0", &pid.to_string()])
+            .output()
+            .map(|output| output.status.success())
+            .unwrap_or(false)
+    }
+    
+    #[cfg(not(unix))]
+    {
+        // For non-Unix systems, assume process is alive (fallback)
+        true
+    }
+}