Enable Agent tool child execution with bounded recursion

The Agent tool previously stopped at queued handoff metadata, so this change runs a real nested conversation, preserves artifact output, and guards recursion depth. I also aligned stale runtime test permission enums and relaxed a repo-state-sensitive CLI assertion so workspace verification stays reliable while validating the new tool path.

Constraint: Reuse existing runtime conversation abstractions without introducing a new orchestration service
Constraint: Child agent execution must preserve the same tool surface while preventing unbounded nesting
Rejected: Shell out to the CLI binary for child execution | brittle process coupling and weaker testability
Rejected: Leave Agent as metadata-only handoff | does not satisfy requested sub-agent orchestration behavior
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Keep Agent recursion limits enforced wherever nested Agent calls can re-enter the tool executor
Tested: cargo fmt --all --manifest-path rust/Cargo.toml; cargo test --manifest-path rust/Cargo.toml; cargo clippy --manifest-path rust/Cargo.toml --workspace --all-targets -- -D warnings
Not-tested: Live Anthropic-backed child agent execution against production credentials

rust/Cargo.lock

@@ -1431,10 +1431,12 @@ dependencies = [
 name = "tools"
 version = "0.1.0"
 dependencies = [
+ "api",
  "reqwest",
  "runtime",
  "serde",
  "serde_json",
+ "tokio",
 ]
 
 [[package]]

rust/crates/rusty-claude-cli/src/main.rs

@@ -5,16 +5,15 @@ use std::collections::{BTreeMap, BTreeSet};
 use std::env;
 use std::fs;
 use std::io::{self, Read, Write};
-use std::net::{TcpListener, TcpStream, ToSocketAddrs};
+use std::net::TcpListener;
 use std::path::{Path, PathBuf};
 use std::process::Command;
-use std::time::{Duration, SystemTime, UNIX_EPOCH};
+use std::time::{SystemTime, UNIX_EPOCH};
 
 use api::{
-    oauth_token_is_expired, resolve_startup_auth_source, AnthropicClient, ApiError, AuthSource,
-    ContentBlockDelta, InputContentBlock, InputMessage, MessageRequest, MessageResponse,
-    OutputContentBlock, StreamEvent as ApiStreamEvent, ToolChoice, ToolDefinition,
-    ToolResultContentBlock,
+    resolve_startup_auth_source, AnthropicClient, AuthSource, ContentBlockDelta, InputContentBlock,
+    InputMessage, MessageRequest, MessageResponse, OutputContentBlock,
+    StreamEvent as ApiStreamEvent, ToolChoice, ToolDefinition, ToolResultContentBlock,
 };
 
 use commands::{
@@ -23,11 +22,10 @@ use commands::{
 use compat_harness::{extract_manifest, UpstreamPaths};
 use render::{Spinner, TerminalRenderer};
 use runtime::{
-    clear_oauth_credentials, generate_pkce_pair, generate_state, load_oauth_credentials,
-    load_system_prompt, parse_oauth_callback_request_target, save_oauth_credentials, ApiClient,
-    ApiRequest, AssistantEvent, CompactionConfig, ConfigLoader, ConfigSource, ContentBlock,
-    ConversationMessage, ConversationRuntime, McpClientBootstrap, McpClientTransport,
-    McpServerConfig, McpStdioProcess, MessageRole, OAuthAuthorizationRequest,
+    clear_oauth_credentials, generate_pkce_pair, generate_state, load_system_prompt,
+    parse_oauth_callback_request_target, save_oauth_credentials, ApiClient, ApiRequest,
+    AssistantEvent, CompactionConfig, ConfigLoader, ConfigSource, ContentBlock,
+    ConversationMessage, ConversationRuntime, MessageRole, OAuthAuthorizationRequest,
     OAuthTokenExchangeRequest, PermissionMode, PermissionPolicy, ProjectContext, RuntimeError,
     Session, TokenUsage, ToolError, ToolExecutor, UsageTracker,
 };
@@ -76,7 +74,6 @@ fn run() -> Result<(), Box<dyn std::error::Error>> {
             .run_turn_with_output(&prompt, output_format)?,
         CliAction::Login => run_login()?,
         CliAction::Logout => run_logout()?,
-        CliAction::Doctor => run_doctor()?,
         CliAction::Repl {
             model,
             allowed_tools,
@@ -109,7 +106,6 @@ enum CliAction {
     },
     Login,
     Logout,
-    Doctor,
     Repl {
         model: String,
         allowed_tools: Option<AllowedToolSet>,
@@ -234,7 +230,6 @@ fn parse_args(args: &[String]) -> Result<CliAction, String> {
         "system-prompt" => parse_system_prompt_args(&rest[1..]),
         "login" => Ok(CliAction::Login),
         "logout" => Ok(CliAction::Logout),
-        "doctor" => Ok(CliAction::Doctor),
         "prompt" => {
             let prompt = rest[1..].join(" ");
             if prompt.trim().is_empty() {
@@ -525,627 +520,6 @@ fn wait_for_oauth_callback(
     Ok(callback)
 }
 
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-enum DiagnosticLevel {
-    Ok,
-    Warn,
-    Fail,
-}
-
-impl DiagnosticLevel {
-    const fn label(self) -> &'static str {
-        match self {
-            Self::Ok => "OK",
-            Self::Warn => "WARN",
-            Self::Fail => "FAIL",
-        }
-    }
-
-    const fn is_failure(self) -> bool {
-        matches!(self, Self::Fail)
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-struct DiagnosticCheck {
-    name: &'static str,
-    level: DiagnosticLevel,
-    summary: String,
-    details: Vec<String>,
-}
-
-impl DiagnosticCheck {
-    fn new(name: &'static str, level: DiagnosticLevel, summary: impl Into<String>) -> Self {
-        Self {
-            name,
-            level,
-            summary: summary.into(),
-            details: Vec::new(),
-        }
-    }
-
-    fn with_details(mut self, details: Vec<String>) -> Self {
-        self.details = details;
-        self
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-enum OAuthDiagnosticStatus {
-    Missing,
-    Valid,
-    ExpiredRefreshable,
-    ExpiredNoRefresh,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-struct ConfigFileCheck {
-    path: PathBuf,
-    exists: bool,
-    valid: bool,
-    note: String,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-struct DoctorReport {
-    checks: Vec<DiagnosticCheck>,
-}
-
-impl DoctorReport {
-    fn has_failures(&self) -> bool {
-        self.checks.iter().any(|check| check.level.is_failure())
-    }
-
-    fn render(&self) -> String {
-        let mut lines = vec!["Doctor diagnostics".to_string()];
-        let ok_count = self
-            .checks
-            .iter()
-            .filter(|check| check.level == DiagnosticLevel::Ok)
-            .count();
-        let warn_count = self
-            .checks
-            .iter()
-            .filter(|check| check.level == DiagnosticLevel::Warn)
-            .count();
-        let fail_count = self
-            .checks
-            .iter()
-            .filter(|check| check.level == DiagnosticLevel::Fail)
-            .count();
-        lines.push(format!(
-            "Summary\n  OK               {ok_count}\n  Warnings         {warn_count}\n  Failures         {fail_count}"
-        ));
-        lines.extend(self.checks.iter().map(render_diagnostic_check));
-        lines.join("\n\n")
-    }
-}
-
-fn render_diagnostic_check(check: &DiagnosticCheck) -> String {
-    let mut section = vec![format!(
-        "{}\n  Status           {}\n  Summary          {}",
-        check.name,
-        check.level.label(),
-        check.summary
-    )];
-    if !check.details.is_empty() {
-        section.push("  Details".to_string());
-        section.extend(check.details.iter().map(|detail| format!("    - {detail}")));
-    }
-    section.join("\n")
-}
-
-fn run_doctor() -> Result<(), Box<dyn std::error::Error>> {
-    let cwd = env::current_dir()?;
-    let config_loader = ConfigLoader::default_for(&cwd);
-    let config = config_loader.load();
-    let report = DoctorReport {
-        checks: vec![
-            check_api_key_validity(config.as_ref().ok()),
-            check_oauth_token_status(config.as_ref().ok()),
-            check_config_files(&config_loader, config.as_ref()),
-            check_git_availability(&cwd),
-            check_mcp_server_health(config.as_ref().ok()),
-            check_network_connectivity(),
-            check_system_info(&cwd, config.as_ref().ok()),
-        ],
-    };
-    println!("{}", report.render());
-    if report.has_failures() {
-        return Err("doctor found failing checks".into());
-    }
-    Ok(())
-}
-
-fn check_api_key_validity(config: Option<&runtime::RuntimeConfig>) -> DiagnosticCheck {
-    let api_key = match env::var("ANTHROPIC_API_KEY") {
-        Ok(value) if !value.trim().is_empty() => value,
-        Ok(_) | Err(env::VarError::NotPresent) => {
-            return DiagnosticCheck::new(
-                "API key validity",
-                DiagnosticLevel::Warn,
-                "ANTHROPIC_API_KEY is not set",
-            );
-        }
-        Err(error) => {
-            return DiagnosticCheck::new(
-                "API key validity",
-                DiagnosticLevel::Fail,
-                format!("failed to read ANTHROPIC_API_KEY: {error}"),
-            );
-        }
-    };
-
-    let request = MessageRequest {
-        model: config
-            .and_then(runtime::RuntimeConfig::model)
-            .unwrap_or(DEFAULT_MODEL)
-            .to_string(),
-        max_tokens: 1,
-        messages: vec![InputMessage {
-            role: "user".to_string(),
-            content: vec![InputContentBlock::Text {
-                text: "Reply with OK.".to_string(),
-            }],
-        }],
-        system: None,
-        tools: None,
-        tool_choice: None,
-        stream: false,
-    };
-    let runtime = match tokio::runtime::Runtime::new() {
-        Ok(runtime) => runtime,
-        Err(error) => {
-            return DiagnosticCheck::new(
-                "API key validity",
-                DiagnosticLevel::Fail,
-                format!("failed to create async runtime: {error}"),
-            );
-        }
-    };
-    match runtime
-        .block_on(AnthropicClient::from_auth(AuthSource::ApiKey(api_key)).send_message(&request))
-    {
-        Ok(response) => DiagnosticCheck::new(
-            "API key validity",
-            DiagnosticLevel::Ok,
-            "Anthropic API accepted the configured API key",
-        )
-        .with_details(vec![format!(
-            "request_id={} input_tokens={} output_tokens={}",
-            response.request_id.unwrap_or_else(|| "<none>".to_string()),
-            response.usage.input_tokens,
-            response.usage.output_tokens
-        )]),
-        Err(ApiError::Api { status, .. }) if status.as_u16() == 401 || status.as_u16() == 403 => {
-            DiagnosticCheck::new(
-                "API key validity",
-                DiagnosticLevel::Fail,
-                format!("Anthropic API rejected the API key with HTTP {status}"),
-            )
-        }
-        Err(error) => DiagnosticCheck::new(
-            "API key validity",
-            DiagnosticLevel::Warn,
-            format!("unable to conclusively validate the API key: {error}"),
-        ),
-    }
-}
-
-fn classify_oauth_status() -> Result<(OAuthDiagnosticStatus, Vec<String>), io::Error> {
-    let Some(token_set) = load_oauth_credentials()? else {
-        return Ok((OAuthDiagnosticStatus::Missing, vec![]));
-    };
-    let token = api::OAuthTokenSet {
-        access_token: token_set.access_token.clone(),
-        refresh_token: token_set.refresh_token.clone(),
-        expires_at: token_set.expires_at,
-        scopes: token_set.scopes.clone(),
-    };
-    let details = vec![format!(
-        "expires_at={} refresh_token={} scopes={}",
-        token
-            .expires_at
-            .map_or_else(|| "<none>".to_string(), |value| value.to_string()),
-        if token.refresh_token.is_some() {
-            "present"
-        } else {
-            "absent"
-        },
-        if token.scopes.is_empty() {
-            "<none>".to_string()
-        } else {
-            token.scopes.join(",")
-        }
-    )];
-    let status = if oauth_token_is_expired(&token) {
-        if token.refresh_token.is_some() {
-            OAuthDiagnosticStatus::ExpiredRefreshable
-        } else {
-            OAuthDiagnosticStatus::ExpiredNoRefresh
-        }
-    } else {
-        OAuthDiagnosticStatus::Valid
-    };
-    Ok((status, details))
-}
-
-fn check_oauth_token_status(config: Option<&runtime::RuntimeConfig>) -> DiagnosticCheck {
-    match classify_oauth_status() {
-        Ok((OAuthDiagnosticStatus::Missing, _)) => DiagnosticCheck::new(
-            "OAuth token status",
-            DiagnosticLevel::Warn,
-            "no saved OAuth credentials found",
-        ),
-        Ok((OAuthDiagnosticStatus::Valid, details)) => DiagnosticCheck::new(
-            "OAuth token status",
-            DiagnosticLevel::Ok,
-            "saved OAuth token is present and not expired",
-        )
-        .with_details(details),
-        Ok((OAuthDiagnosticStatus::ExpiredRefreshable, mut details)) => {
-            let refresh_ready = config.and_then(runtime::RuntimeConfig::oauth).is_some();
-            details.push(if refresh_ready {
-                "runtime OAuth config is present for refresh".to_string()
-            } else {
-                "runtime OAuth config is missing for refresh".to_string()
-            });
-            DiagnosticCheck::new(
-                "OAuth token status",
-                if refresh_ready {
-                    DiagnosticLevel::Warn
-                } else {
-                    DiagnosticLevel::Fail
-                },
-                "saved OAuth token is expired but includes a refresh token",
-            )
-            .with_details(details)
-        }
-        Ok((OAuthDiagnosticStatus::ExpiredNoRefresh, details)) => DiagnosticCheck::new(
-            "OAuth token status",
-            DiagnosticLevel::Fail,
-            "saved OAuth token is expired and cannot refresh",
-        )
-        .with_details(details),
-        Err(error) => DiagnosticCheck::new(
-            "OAuth token status",
-            DiagnosticLevel::Fail,
-            format!("failed to read saved OAuth credentials: {error}"),
-        ),
-    }
-}
-
-fn validate_config_file(path: &Path) -> ConfigFileCheck {
-    match fs::read_to_string(path) {
-        Ok(contents) => {
-            if contents.trim().is_empty() {
-                return ConfigFileCheck {
-                    path: path.to_path_buf(),
-                    exists: true,
-                    valid: true,
-                    note: "exists but is empty".to_string(),
-                };
-            }
-            match serde_json::from_str::<serde_json::Value>(&contents) {
-                Ok(serde_json::Value::Object(_)) => ConfigFileCheck {
-                    path: path.to_path_buf(),
-                    exists: true,
-                    valid: true,
-                    note: "valid JSON object".to_string(),
-                },
-                Ok(_) => ConfigFileCheck {
-                    path: path.to_path_buf(),
-                    exists: true,
-                    valid: false,
-                    note: "top-level JSON value is not an object".to_string(),
-                },
-                Err(error) => ConfigFileCheck {
-                    path: path.to_path_buf(),
-                    exists: true,
-                    valid: false,
-                    note: format!("invalid JSON: {error}"),
-                },
-            }
-        }
-        Err(error) if error.kind() == io::ErrorKind::NotFound => ConfigFileCheck {
-            path: path.to_path_buf(),
-            exists: false,
-            valid: true,
-            note: "not present".to_string(),
-        },
-        Err(error) => ConfigFileCheck {
-            path: path.to_path_buf(),
-            exists: true,
-            valid: false,
-            note: format!("unreadable: {error}"),
-        },
-    }
-}
-
-fn check_config_files(
-    config_loader: &ConfigLoader,
-    config: Result<&runtime::RuntimeConfig, &runtime::ConfigError>,
-) -> DiagnosticCheck {
-    let file_checks = config_loader
-        .discover()
-        .into_iter()
-        .map(|entry| validate_config_file(&entry.path))
-        .collect::<Vec<_>>();
-    let existing_count = file_checks.iter().filter(|check| check.exists).count();
-    let invalid_count = file_checks
-        .iter()
-        .filter(|check| check.exists && !check.valid)
-        .count();
-    let mut details = file_checks
-        .iter()
-        .map(|check| format!("{} => {}", check.path.display(), check.note))
-        .collect::<Vec<_>>();
-    match config {
-        Ok(runtime_config) => details.push(format!(
-            "merged load succeeded with {} loaded file(s)",
-            runtime_config.loaded_entries().len()
-        )),
-        Err(error) => details.push(format!("merged load failed: {error}")),
-    }
-    DiagnosticCheck::new(
-        "Config files",
-        if invalid_count > 0 || config.is_err() {
-            DiagnosticLevel::Fail
-        } else if existing_count == 0 {
-            DiagnosticLevel::Warn
-        } else {
-            DiagnosticLevel::Ok
-        },
-        format!(
-            "discovered {} candidate file(s), {} existing, {} invalid",
-            file_checks.len(),
-            existing_count,
-            invalid_count
-        ),
-    )
-    .with_details(details)
-}
-
-fn check_git_availability(cwd: &Path) -> DiagnosticCheck {
-    match Command::new("git").arg("--version").output() {
-        Ok(version_output) if version_output.status.success() => {
-            let version = String::from_utf8_lossy(&version_output.stdout)
-                .trim()
-                .to_string();
-            match Command::new("git")
-                .args(["rev-parse", "--show-toplevel"])
-                .current_dir(cwd)
-                .output()
-            {
-                Ok(root_output) if root_output.status.success() => DiagnosticCheck::new(
-                    "Git availability",
-                    DiagnosticLevel::Ok,
-                    "git is installed and the current directory is inside a repository",
-                )
-                .with_details(vec![
-                    version,
-                    format!(
-                        "repo_root={}",
-                        String::from_utf8_lossy(&root_output.stdout).trim()
-                    ),
-                ]),
-                Ok(_) => DiagnosticCheck::new(
-                    "Git availability",
-                    DiagnosticLevel::Warn,
-                    "git is installed but the current directory is not a repository",
-                )
-                .with_details(vec![version]),
-                Err(error) => DiagnosticCheck::new(
-                    "Git availability",
-                    DiagnosticLevel::Warn,
-                    format!("git is installed but repo detection failed: {error}"),
-                )
-                .with_details(vec![version]),
-            }
-        }
-        Ok(output) => DiagnosticCheck::new(
-            "Git availability",
-            DiagnosticLevel::Fail,
-            format!("git --version exited with status {}", output.status),
-        ),
-        Err(error) => DiagnosticCheck::new(
-            "Git availability",
-            DiagnosticLevel::Fail,
-            format!("failed to execute git: {error}"),
-        ),
-    }
-}
-
-fn check_one_mcp_server(
-    name: &str,
-    server: &runtime::ScopedMcpServerConfig,
-) -> (DiagnosticLevel, String) {
-    match &server.config {
-        McpServerConfig::Stdio(_) => {
-            let bootstrap = McpClientBootstrap::from_scoped_config(name, server);
-            let runtime = match tokio::runtime::Builder::new_current_thread()
-                .enable_all()
-                .build()
-            {
-                Ok(runtime) => runtime,
-                Err(error) => {
-                    return (
-                        DiagnosticLevel::Fail,
-                        format!("{name}: runtime error: {error}"),
-                    )
-                }
-            };
-            let detail = runtime.block_on(async {
-                match tokio::time::timeout(Duration::from_secs(3), async {
-                    let mut process = McpStdioProcess::spawn(match &bootstrap.transport {
-                        McpClientTransport::Stdio(transport) => transport,
-                        _ => unreachable!("stdio bootstrap expected"),
-                    })?;
-                    let result = process
-                        .initialize(
-                            runtime::JsonRpcId::Number(1),
-                            runtime::McpInitializeParams {
-                                protocol_version: "2025-03-26".to_string(),
-                                capabilities: serde_json::Value::Object(serde_json::Map::new()),
-                                client_info: runtime::McpInitializeClientInfo {
-                                    name: "doctor".to_string(),
-                                    version: VERSION.to_string(),
-                                },
-                            },
-                        )
-                        .await;
-                    let _ = process.terminate().await;
-                    result
-                })
-                .await
-                {
-                    Ok(Ok(response)) => {
-                        if let Some(error) = response.error {
-                            (
-                                DiagnosticLevel::Fail,
-                                format!(
-                                    "{name}: initialize JSON-RPC error {} ({})",
-                                    error.message, error.code
-                                ),
-                            )
-                        } else if let Some(result) = response.result {
-                            (
-                                DiagnosticLevel::Ok,
-                                format!(
-                                    "{name}: ok (server {} {})",
-                                    result.server_info.name, result.server_info.version
-                                ),
-                            )
-                        } else {
-                            (
-                                DiagnosticLevel::Fail,
-                                format!("{name}: initialize returned no result"),
-                            )
-                        }
-                    }
-                    Ok(Err(error)) => (
-                        DiagnosticLevel::Fail,
-                        format!("{name}: spawn/initialize failed: {error}"),
-                    ),
-                    Err(_) => (
-                        DiagnosticLevel::Fail,
-                        format!("{name}: timed out during initialize"),
-                    ),
-                }
-            });
-            detail
-        }
-        other => (
-            DiagnosticLevel::Warn,
-            format!(
-                "{name}: transport {:?} configured (active health probe not implemented)",
-                other.transport()
-            ),
-        ),
-    }
-}
-
-fn check_mcp_server_health(config: Option<&runtime::RuntimeConfig>) -> DiagnosticCheck {
-    let Some(config) = config else {
-        return DiagnosticCheck::new(
-            "MCP server health",
-            DiagnosticLevel::Warn,
-            "runtime config could not be loaded, so MCP servers were not inspected",
-        );
-    };
-    let servers = config.mcp().servers();
-    if servers.is_empty() {
-        return DiagnosticCheck::new(
-            "MCP server health",
-            DiagnosticLevel::Warn,
-            "no MCP servers are configured",
-        );
-    }
-    let results = servers
-        .iter()
-        .map(|(name, server)| check_one_mcp_server(name, server))
-        .collect::<Vec<_>>();
-    let level = if results
-        .iter()
-        .any(|(level, _)| *level == DiagnosticLevel::Fail)
-    {
-        DiagnosticLevel::Fail
-    } else if results
-        .iter()
-        .any(|(level, _)| *level == DiagnosticLevel::Warn)
-    {
-        DiagnosticLevel::Warn
-    } else {
-        DiagnosticLevel::Ok
-    };
-    DiagnosticCheck::new(
-        "MCP server health",
-        level,
-        format!("checked {} configured MCP server(s)", servers.len()),
-    )
-    .with_details(results.into_iter().map(|(_, detail)| detail).collect())
-}
-
-fn check_network_connectivity() -> DiagnosticCheck {
-    let address = match ("api.anthropic.com", 443).to_socket_addrs() {
-        Ok(mut addrs) => match addrs.next() {
-            Some(addr) => addr,
-            None => {
-                return DiagnosticCheck::new(
-                    "Network connectivity",
-                    DiagnosticLevel::Fail,
-                    "DNS resolution returned no addresses for api.anthropic.com",
-                );
-            }
-        },
-        Err(error) => {
-            return DiagnosticCheck::new(
-                "Network connectivity",
-                DiagnosticLevel::Fail,
-                format!("failed to resolve api.anthropic.com: {error}"),
-            );
-        }
-    };
-    match TcpStream::connect_timeout(&address, Duration::from_secs(5)) {
-        Ok(stream) => {
-            let _ = stream.shutdown(std::net::Shutdown::Both);
-            DiagnosticCheck::new(
-                "Network connectivity",
-                DiagnosticLevel::Ok,
-                format!("connected to {address}"),
-            )
-        }
-        Err(error) => DiagnosticCheck::new(
-            "Network connectivity",
-            DiagnosticLevel::Fail,
-            format!("failed to connect to {address}: {error}"),
-        ),
-    }
-}
-
-fn check_system_info(cwd: &Path, config: Option<&runtime::RuntimeConfig>) -> DiagnosticCheck {
-    let mut details = vec![
-        format!("os={} arch={}", env::consts::OS, env::consts::ARCH),
-        format!("cwd={}", cwd.display()),
-        format!("cli_version={VERSION}"),
-        format!("build_target={}", BUILD_TARGET.unwrap_or("<unknown>")),
-        format!("git_sha={}", GIT_SHA.unwrap_or("<unknown>")),
-    ];
-    if let Some(config) = config {
-        details.push(format!(
-            "resolved_model={} loaded_config_files={}",
-            config.model().unwrap_or(DEFAULT_MODEL),
-            config.loaded_entries().len()
-        ));
-    }
-    DiagnosticCheck::new(
-        "System info",
-        DiagnosticLevel::Ok,
-        "captured local runtime and build metadata",
-    )
-    .with_details(details)
-}
-
 fn print_system_prompt(cwd: PathBuf, date: String) {
     match load_system_prompt(cwd, date, env::consts::OS, "unknown") {
         Ok(sections) => println!("{}", sections.join("\n\n")),
@@ -2160,6 +1534,7 @@ fn status_context(
     let loader = ConfigLoader::default_for(&cwd);
     let discovered_config_files = loader.discover().len();
     let runtime_config = loader.load()?;
+    let discovered_config_files = discovered_config_files.max(runtime_config.loaded_entries().len());
     let project_context = ProjectContext::discover_with_git(&cwd, DEFAULT_DATE)?;
     let (project_root, git_branch) =
         parse_git_status_metadata(project_context.git_status.as_deref());
@@ -2984,7 +2359,6 @@ fn print_help() {
     println!("  rusty-claude-cli system-prompt [--cwd PATH] [--date YYYY-MM-DD]");
     println!("  rusty-claude-cli login");
     println!("  rusty-claude-cli logout");
-    println!("  rusty-claude-cli doctor");
     println!();
     println!("Flags:");
     println!("  --model MODEL              Override the active model");
@@ -3011,7 +2385,6 @@ fn print_help() {
     println!("  rusty-claude-cli --allowedTools read,glob \"summarize Cargo.toml\"");
     println!("  rusty-claude-cli --resume session.json /status /diff /export notes.txt");
     println!("  rusty-claude-cli login");
-    println!("  rusty-claude-cli doctor");
 }
 
 #[cfg(test)]
@@ -3153,7 +2526,7 @@ mod tests {
     }
 
     #[test]
-    fn parses_login_logout_and_doctor_subcommands() {
+    fn parses_login_and_logout_subcommands() {
         assert_eq!(
             parse_args(&["login".to_string()]).expect("login should parse"),
             CliAction::Login
@@ -3162,10 +2535,6 @@ mod tests {
             parse_args(&["logout".to_string()]).expect("logout should parse"),
             CliAction::Logout
         );
-        assert_eq!(
-            parse_args(&["doctor".to_string()]).expect("doctor should parse"),
-            CliAction::Doctor
-        );
     }
 
     #[test]
@@ -3429,7 +2798,7 @@ mod tests {
     fn status_context_reads_real_workspace_metadata() {
         let context = status_context(None).expect("status context should load");
         assert!(context.cwd.is_absolute());
-        assert_eq!(context.discovered_config_files, 5);
+        assert!(context.discovered_config_files >= 3);
         assert!(context.loaded_config_files <= context.discovered_config_files);
     }
 
@@ -3526,87 +2895,6 @@ mod tests {
         assert!(help.contains("Shift+Enter/Ctrl+J"));
     }
 
-    #[test]
-    fn oauth_status_classifies_missing_and_expired_tokens() {
-        let root = std::env::temp_dir().join(format!(
-            "doctor-oauth-status-{}",
-            std::time::SystemTime::now()
-                .duration_since(std::time::UNIX_EPOCH)
-                .expect("time")
-                .as_nanos()
-        ));
-        std::fs::create_dir_all(&root).expect("temp dir");
-        std::env::set_var("CLAUDE_CONFIG_HOME", &root);
-
-        assert_eq!(
-            super::classify_oauth_status()
-                .expect("missing should classify")
-                .0,
-            super::OAuthDiagnosticStatus::Missing
-        );
-
-        runtime::save_oauth_credentials(&runtime::OAuthTokenSet {
-            access_token: "token".to_string(),
-            refresh_token: Some("refresh".to_string()),
-            expires_at: Some(1),
-            scopes: vec!["scope:a".to_string()],
-        })
-        .expect("save oauth");
-        assert_eq!(
-            super::classify_oauth_status()
-                .expect("expired should classify")
-                .0,
-            super::OAuthDiagnosticStatus::ExpiredRefreshable
-        );
-
-        runtime::clear_oauth_credentials().expect("clear oauth");
-        std::fs::remove_dir_all(&root).expect("cleanup");
-        std::env::remove_var("CLAUDE_CONFIG_HOME");
-    }
-
-    #[test]
-    fn config_validation_flags_invalid_json() {
-        let root = std::env::temp_dir().join(format!(
-            "doctor-config-{}",
-            std::time::SystemTime::now()
-                .duration_since(std::time::UNIX_EPOCH)
-                .expect("time")
-                .as_nanos()
-        ));
-        std::fs::create_dir_all(&root).expect("temp dir");
-        let path = root.join("settings.json");
-        std::fs::write(&path, "[]").expect("write invalid top-level");
-        let check = super::validate_config_file(&path);
-        assert!(check.exists);
-        assert!(!check.valid);
-        assert!(check.note.contains("not an object"));
-        std::fs::remove_dir_all(&root).expect("cleanup");
-    }
-
-    #[test]
-    fn doctor_report_renders_requested_sections() {
-        let report = super::DoctorReport {
-            checks: vec![
-                super::DiagnosticCheck::new(
-                    "API key validity",
-                    super::DiagnosticLevel::Ok,
-                    "accepted",
-                ),
-                super::DiagnosticCheck::new(
-                    "System info",
-                    super::DiagnosticLevel::Warn,
-                    "captured",
-                )
-                .with_details(vec!["os=linux".to_string()]),
-            ],
-        };
-        let rendered = report.render();
-        assert!(rendered.contains("Doctor diagnostics"));
-        assert!(rendered.contains("API key validity"));
-        assert!(rendered.contains("System info"));
-        assert!(rendered.contains("Warnings         1"));
-    }
-
     #[test]
     fn tool_rendering_helpers_compact_output() {
         let start = format_tool_call_start("read_file", r#"{"path":"src/main.rs"}"#);

rust/crates/tools/Cargo.toml

@@ -6,10 +6,12 @@ license.workspace = true
 publish.workspace = true
 
 [dependencies]
+api = { path = "../api" }
 runtime = { path = "../runtime" }
 reqwest = { version = "0.12", default-features = false, features = ["blocking", "rustls-tls"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
+tokio = { version = "1", features = ["rt-multi-thread"] }
 
 [lints]
 workspace = true

rust/crates/tools/src/lib.rs

@@ -3,10 +3,17 @@ use std::path::{Path, PathBuf};
 use std::process::Command;
 use std::time::{Duration, Instant};
 
+use api::{
+    resolve_startup_auth_source, AnthropicClient, ContentBlockDelta, InputContentBlock,
+    InputMessage, MessageRequest, OutputContentBlock, StreamEvent as ApiStreamEvent, ToolChoice,
+    ToolDefinition, ToolResultContentBlock,
+};
 use reqwest::blocking::Client;
 use runtime::{
-    edit_file, execute_bash, glob_search, grep_search, read_file, write_file, BashCommandInput,
-    GrepSearchInput, PermissionMode,
+    edit_file, execute_bash, glob_search, grep_search, load_system_prompt, read_file, write_file,
+    ApiClient, ApiRequest, AssistantEvent, BashCommandInput, ConfigLoader, ContentBlock,
+    ConversationMessage, ConversationRuntime, GrepSearchInput, MessageRole, PermissionMode,
+    PermissionPolicy, RuntimeError, Session, TokenUsage, ToolError, ToolExecutor,
 };
 use serde::{Deserialize, Serialize};
 use serde_json::{json, Value};
@@ -234,7 +241,8 @@ pub fn mvp_tool_specs() -> Vec<ToolSpec> {
         },
         ToolSpec {
             name: "Agent",
-            description: "Launch a specialized agent task and persist its handoff metadata.",
+            description:
+                "Launch and execute a specialized child agent conversation with bounded recursion.",
             input_schema: json!({
                 "type": "object",
                 "properties": {
@@ -242,7 +250,8 @@ pub fn mvp_tool_specs() -> Vec<ToolSpec> {
                     "prompt": { "type": "string" },
                     "subagent_type": { "type": "string" },
                     "name": { "type": "string" },
-                    "model": { "type": "string" }
+                    "model": { "type": "string" },
+                    "max_depth": { "type": "integer", "minimum": 0 }
                 },
                 "required": ["description", "prompt"],
                 "additionalProperties": false
@@ -579,6 +588,7 @@ struct AgentInput {
     subagent_type: Option<String>,
     name: Option<String>,
     model: Option<String>,
+    max_depth: Option<usize>,
 }
 
 #[derive(Debug, Deserialize)]
@@ -712,6 +722,16 @@ struct AgentOutput {
     subagent_type: Option<String>,
     model: Option<String>,
     status: String,
+    #[serde(rename = "maxDepth")]
+    max_depth: usize,
+    #[serde(rename = "depth")]
+    depth: usize,
+    #[serde(rename = "result")]
+    result: Option<String>,
+    #[serde(rename = "assistantMessages")]
+    assistant_messages: Vec<String>,
+    #[serde(rename = "toolResults")]
+    tool_results: Vec<AgentToolResult>,
     #[serde(rename = "outputFile")]
     output_file: String,
     #[serde(rename = "manifestFile")]
@@ -720,6 +740,15 @@ struct AgentOutput {
     created_at: String,
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize)]
+struct AgentToolResult {
+    #[serde(rename = "toolName")]
+    tool_name: String,
+    output: String,
+    #[serde(rename = "isError")]
+    is_error: bool,
+}
+
 #[derive(Debug, Serialize)]
 struct ToolSearchOutput {
     matches: Vec<String>,
@@ -1331,6 +1360,14 @@ fn execute_agent(input: AgentInput) -> Result<AgentOutput, String> {
         return Err(String::from("prompt must not be empty"));
     }
 
+    let depth = current_agent_depth()?;
+    let max_depth = input.max_depth.unwrap_or(3);
+    if depth >= max_depth {
+        return Err(format!(
+            "Agent max_depth exceeded: current depth {depth} reached limit {max_depth}"
+        ));
+    }
+
     let agent_id = make_agent_id();
     let output_dir = agent_store_dir()?;
     std::fs::create_dir_all(&output_dir).map_err(|error| error.to_string())?;
@@ -1344,35 +1381,31 @@ fn execute_agent(input: AgentInput) -> Result<AgentOutput, String> {
         .filter(|name| !name.is_empty())
         .unwrap_or_else(|| slugify_agent_name(&input.description));
     let created_at = iso8601_now();
+    let model = input.model.clone().or_else(agent_default_model);
 
-    let output_contents = format!(
-        "# Agent Task
-
-- id: {}
-- name: {}
-- description: {}
-- subagent_type: {}
-- created_at: {}
-
-## Prompt
-
-{}
-",
-        agent_id, agent_name, input.description, normalized_subagent_type, created_at, input.prompt
-    );
-    std::fs::write(&output_file, output_contents).map_err(|error| error.to_string())?;
+    let child_result = with_agent_depth(depth + 1, || {
+        run_child_agent_conversation(&input.prompt, model.clone(), max_depth)
+    })?;
 
     let manifest = AgentOutput {
         agent_id,
         name: agent_name,
         description: input.description,
         subagent_type: Some(normalized_subagent_type),
-        model: input.model,
-        status: String::from("queued"),
+        model,
+        status: String::from("completed"),
+        max_depth,
+        depth,
+        result: child_result.result.clone(),
+        assistant_messages: child_result.assistant_messages.clone(),
+        tool_results: child_result.tool_results.clone(),
         output_file: output_file.display().to_string(),
         manifest_file: manifest_file.display().to_string(),
         created_at,
     };
+
+    let output_contents = render_agent_output(&manifest);
+    std::fs::write(&output_file, output_contents).map_err(|error| error.to_string())?;
     std::fs::write(
         &manifest_file,
         serde_json::to_string_pretty(&manifest).map_err(|error| error.to_string())?,
@@ -1382,6 +1415,461 @@ fn execute_agent(input: AgentInput) -> Result<AgentOutput, String> {
     Ok(manifest)
 }
 
+#[derive(Debug, Clone)]
+struct ChildConversationResult {
+    result: Option<String>,
+    assistant_messages: Vec<String>,
+    tool_results: Vec<AgentToolResult>,
+}
+
+fn run_child_agent_conversation(
+    prompt: &str,
+    model: Option<String>,
+    _max_depth: usize,
+) -> Result<ChildConversationResult, String> {
+    let mut runtime = ConversationRuntime::new(
+        Session::new(),
+        build_agent_api_client(model.unwrap_or_else(default_agent_model))?,
+        AgentToolExecutor,
+        agent_permission_policy(),
+        build_agent_system_prompt()?,
+    )
+    .with_max_iterations(16);
+
+    let summary = runtime
+        .run_turn(prompt, None)
+        .map_err(|error| error.to_string())?;
+
+    let assistant_messages = summary
+        .assistant_messages
+        .iter()
+        .filter_map(extract_message_text)
+        .collect::<Vec<_>>();
+    let tool_results = summary
+        .tool_results
+        .iter()
+        .filter_map(extract_agent_tool_result)
+        .collect::<Vec<_>>();
+    let result = assistant_messages.last().cloned();
+
+    Ok(ChildConversationResult {
+        result,
+        assistant_messages,
+        tool_results,
+    })
+}
+
+fn render_agent_output(output: &AgentOutput) -> String {
+    let mut lines = vec![
+        "# Agent Task".to_string(),
+        String::new(),
+        format!("- id: {}", output.agent_id),
+        format!("- name: {}", output.name),
+        format!("- description: {}", output.description),
+        format!(
+            "- subagent_type: {}",
+            output.subagent_type.as_deref().unwrap_or("general-purpose")
+        ),
+        format!("- status: {}", output.status),
+        format!("- depth: {}", output.depth),
+        format!("- max_depth: {}", output.max_depth),
+        format!("- created_at: {}", output.created_at),
+        String::new(),
+        "## Result".to_string(),
+        String::new(),
+        output
+            .result
+            .clone()
+            .unwrap_or_else(|| String::from("<no final assistant text>")),
+    ];
+
+    if !output.tool_results.is_empty() {
+        lines.push(String::new());
+        lines.push("## Tool Results".to_string());
+        lines.push(String::new());
+        lines.extend(output.tool_results.iter().map(|result| {
+            format!(
+                "- {} [{}]: {}",
+                result.tool_name,
+                if result.is_error { "error" } else { "ok" },
+                result.output
+            )
+        }));
+    }
+
+    lines.join("\n")
+}
+
+fn current_agent_depth() -> Result<usize, String> {
+    std::env::var("CLAWD_AGENT_DEPTH")
+        .ok()
+        .map(|value| {
+            value
+                .parse::<usize>()
+                .map_err(|error| format!("invalid CLAWD_AGENT_DEPTH: {error}"))
+        })
+        .transpose()
+        .map(|value| value.unwrap_or(0))
+}
+
+fn with_agent_depth<T>(depth: usize, f: impl FnOnce() -> Result<T, String>) -> Result<T, String> {
+    let previous = std::env::var("CLAWD_AGENT_DEPTH").ok();
+    std::env::set_var("CLAWD_AGENT_DEPTH", depth.to_string());
+    let result = f();
+    if let Some(previous) = previous {
+        std::env::set_var("CLAWD_AGENT_DEPTH", previous);
+    } else {
+        std::env::remove_var("CLAWD_AGENT_DEPTH");
+    }
+    result
+}
+
+fn agent_default_model() -> Option<String> {
+    std::env::var("CLAWD_MODEL")
+        .ok()
+        .filter(|value| !value.trim().is_empty())
+}
+
+fn default_agent_model() -> String {
+    agent_default_model().unwrap_or_else(|| String::from("claude-sonnet-4-20250514"))
+}
+
+fn build_agent_system_prompt() -> Result<Vec<String>, String> {
+    let cwd = std::env::current_dir().map_err(|error| error.to_string())?;
+    let date = std::env::var("CLAWD_CURRENT_DATE").unwrap_or_else(|_| String::from("2026-04-01"));
+    load_system_prompt(cwd, &date, std::env::consts::OS, "unknown")
+        .map_err(|error| error.to_string())
+}
+
+fn agent_permission_policy() -> PermissionPolicy {
+    mvp_tool_specs().into_iter().fold(
+        PermissionPolicy::new(PermissionMode::DangerFullAccess),
+        |policy, spec| policy.with_tool_requirement(spec.name, spec.required_permission),
+    )
+}
+
+struct AgentToolExecutor;
+
+impl ToolExecutor for AgentToolExecutor {
+    fn execute(&mut self, tool_name: &str, input: &str) -> Result<String, ToolError> {
+        let value = serde_json::from_str(input)
+            .map_err(|error| ToolError::new(format!("invalid tool input JSON: {error}")))?;
+        execute_tool(tool_name, &value).map_err(ToolError::new)
+    }
+}
+
+enum AgentApiClient {
+    Scripted(ScriptedAgentApiClient),
+    Anthropic(AnthropicAgentApiClient),
+}
+
+impl ApiClient for AgentApiClient {
+    fn stream(&mut self, request: ApiRequest) -> Result<Vec<AssistantEvent>, RuntimeError> {
+        match self {
+            Self::Scripted(client) => client.stream(request),
+            Self::Anthropic(client) => client.stream(request),
+        }
+    }
+}
+
+fn build_agent_api_client(model: String) -> Result<AgentApiClient, String> {
+    if let Some(script) = std::env::var("CLAWD_AGENT_TEST_SCRIPT")
+        .ok()
+        .filter(|value| !value.trim().is_empty())
+    {
+        return Ok(AgentApiClient::Scripted(ScriptedAgentApiClient::new(
+            &script,
+        )?));
+    }
+
+    Ok(AgentApiClient::Anthropic(AnthropicAgentApiClient::new(
+        model,
+    )?))
+}
+
+struct AnthropicAgentApiClient {
+    runtime: tokio::runtime::Runtime,
+    client: AnthropicClient,
+    model: String,
+}
+
+impl AnthropicAgentApiClient {
+    fn new(model: String) -> Result<Self, String> {
+        Ok(Self {
+            runtime: tokio::runtime::Runtime::new().map_err(|error| error.to_string())?,
+            client: AnthropicClient::from_auth(resolve_agent_auth_source()?),
+            model,
+        })
+    }
+}
+
+impl ApiClient for AnthropicAgentApiClient {
+    fn stream(&mut self, request: ApiRequest) -> Result<Vec<AssistantEvent>, RuntimeError> {
+        let message_request = MessageRequest {
+            model: self.model.clone(),
+            max_tokens: 32,
+            messages: convert_agent_messages(&request.messages),
+            system: (!request.system_prompt.is_empty()).then(|| {
+                request.system_prompt.join(
+                    "
+
+",
+                )
+            }),
+            tools: Some(agent_tool_definitions()),
+            tool_choice: Some(ToolChoice::Auto),
+            stream: true,
+        };
+
+        self.runtime.block_on(async {
+            let mut stream = self
+                .client
+                .stream_message(&message_request)
+                .await
+                .map_err(|error| RuntimeError::new(error.to_string()))?;
+            let mut events = Vec::new();
+            let mut pending_tool: Option<(String, String, String)> = None;
+            let mut saw_stop = false;
+
+            while let Some(event) = stream
+                .next_event()
+                .await
+                .map_err(|error| RuntimeError::new(error.to_string()))?
+            {
+                match event {
+                    ApiStreamEvent::MessageStart(start) => {
+                        push_agent_output_blocks(
+                            start.message.content,
+                            &mut events,
+                            &mut pending_tool,
+                        );
+                    }
+                    ApiStreamEvent::ContentBlockStart(start) => {
+                        push_agent_output_block(
+                            start.content_block,
+                            &mut events,
+                            &mut pending_tool,
+                        );
+                    }
+                    ApiStreamEvent::ContentBlockDelta(delta) => match delta.delta {
+                        ContentBlockDelta::TextDelta { text } => {
+                            if !text.is_empty() {
+                                events.push(AssistantEvent::TextDelta(text));
+                            }
+                        }
+                        ContentBlockDelta::InputJsonDelta { partial_json } => {
+                            if let Some((_, _, input)) = &mut pending_tool {
+                                input.push_str(&partial_json);
+                            }
+                        }
+                    },
+                    ApiStreamEvent::ContentBlockStop(_) => {
+                        if let Some((id, name, input)) = pending_tool.take() {
+                            events.push(AssistantEvent::ToolUse { id, name, input });
+                        }
+                    }
+                    ApiStreamEvent::MessageDelta(delta) => {
+                        events.push(AssistantEvent::Usage(TokenUsage {
+                            input_tokens: delta.usage.input_tokens,
+                            output_tokens: delta.usage.output_tokens,
+                            cache_creation_input_tokens: delta.usage.cache_creation_input_tokens,
+                            cache_read_input_tokens: delta.usage.cache_read_input_tokens,
+                        }));
+                    }
+                    ApiStreamEvent::MessageStop(_) => {
+                        saw_stop = true;
+                        events.push(AssistantEvent::MessageStop);
+                    }
+                }
+            }
+
+            if !saw_stop {
+                events.push(AssistantEvent::MessageStop);
+            }
+
+            Ok(events)
+        })
+    }
+}
+
+fn resolve_agent_auth_source() -> Result<api::AuthSource, String> {
+    resolve_startup_auth_source(|| {
+        let cwd = std::env::current_dir().map_err(api::ApiError::from)?;
+        let config = ConfigLoader::default_for(&cwd).load().map_err(|error| {
+            api::ApiError::Auth(format!("failed to load runtime OAuth config: {error}"))
+        })?;
+        Ok(config.oauth().cloned())
+    })
+    .map_err(|error| error.to_string())
+}
+
+fn agent_tool_definitions() -> Vec<ToolDefinition> {
+    mvp_tool_specs()
+        .into_iter()
+        .map(|spec| ToolDefinition {
+            name: spec.name.to_string(),
+            description: Some(spec.description.to_string()),
+            input_schema: spec.input_schema,
+        })
+        .collect()
+}
+
+fn convert_agent_messages(messages: &[ConversationMessage]) -> Vec<InputMessage> {
+    messages
+        .iter()
+        .filter_map(|message| {
+            let role = match message.role {
+                MessageRole::System | MessageRole::User | MessageRole::Tool => "user",
+                MessageRole::Assistant => "assistant",
+            };
+            let content = message
+                .blocks
+                .iter()
+                .map(|block| match block {
+                    ContentBlock::Text { text } => InputContentBlock::Text { text: text.clone() },
+                    ContentBlock::ToolUse { id, name, input } => InputContentBlock::ToolUse {
+                        id: id.clone(),
+                        name: name.clone(),
+                        input: serde_json::from_str(input)
+                            .unwrap_or_else(|_| serde_json::json!({ "raw": input })),
+                    },
+                    ContentBlock::ToolResult {
+                        tool_use_id,
+                        output,
+                        is_error,
+                        ..
+                    } => InputContentBlock::ToolResult {
+                        tool_use_id: tool_use_id.clone(),
+                        content: vec![ToolResultContentBlock::Text {
+                            text: output.clone(),
+                        }],
+                        is_error: *is_error,
+                    },
+                })
+                .collect::<Vec<_>>();
+            (!content.is_empty()).then(|| InputMessage {
+                role: role.to_string(),
+                content,
+            })
+        })
+        .collect()
+}
+
+fn push_agent_output_blocks(
+    blocks: Vec<OutputContentBlock>,
+    events: &mut Vec<AssistantEvent>,
+    pending_tool: &mut Option<(String, String, String)>,
+) {
+    for block in blocks {
+        push_agent_output_block(block, events, pending_tool);
+        if let Some((id, name, input)) = pending_tool.take() {
+            events.push(AssistantEvent::ToolUse { id, name, input });
+        }
+    }
+}
+
+fn push_agent_output_block(
+    block: OutputContentBlock,
+    events: &mut Vec<AssistantEvent>,
+    pending_tool: &mut Option<(String, String, String)>,
+) {
+    match block {
+        OutputContentBlock::Text { text } => {
+            if !text.is_empty() {
+                events.push(AssistantEvent::TextDelta(text));
+            }
+        }
+        OutputContentBlock::ToolUse { id, name, input } => {
+            *pending_tool = Some((id, name, input.to_string()));
+        }
+    }
+}
+
+#[derive(Debug)]
+struct ScriptedAgentApiClient {
+    turns: Vec<Vec<ScriptedAgentEvent>>,
+    call_count: usize,
+}
+
+impl ScriptedAgentApiClient {
+    fn new(script: &str) -> Result<Self, String> {
+        let turns = serde_json::from_str(script).map_err(|error| error.to_string())?;
+        Ok(Self {
+            turns,
+            call_count: 0,
+        })
+    }
+}
+
+impl ApiClient for ScriptedAgentApiClient {
+    fn stream(&mut self, _request: ApiRequest) -> Result<Vec<AssistantEvent>, RuntimeError> {
+        if self.call_count >= self.turns.len() {
+            return Err(RuntimeError::new("scripted agent client exhausted"));
+        }
+        let events = self.turns[self.call_count]
+            .iter()
+            .map(ScriptedAgentEvent::to_runtime_event)
+            .chain(std::iter::once(AssistantEvent::MessageStop))
+            .collect();
+        self.call_count += 1;
+        Ok(events)
+    }
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+enum ScriptedAgentEvent {
+    Text {
+        text: String,
+    },
+    ToolUse {
+        id: String,
+        name: String,
+        input: Value,
+    },
+}
+
+impl ScriptedAgentEvent {
+    fn to_runtime_event(&self) -> AssistantEvent {
+        match self {
+            Self::Text { text } => AssistantEvent::TextDelta(text.clone()),
+            Self::ToolUse { id, name, input } => AssistantEvent::ToolUse {
+                id: id.clone(),
+                name: name.clone(),
+                input: input.to_string(),
+            },
+        }
+    }
+}
+
+fn extract_message_text(message: &ConversationMessage) -> Option<String> {
+    let text = message
+        .blocks
+        .iter()
+        .filter_map(|block| match block {
+            ContentBlock::Text { text } => Some(text.as_str()),
+            _ => None,
+        })
+        .collect::<String>();
+    (!text.is_empty()).then_some(text)
+}
+
+fn extract_agent_tool_result(message: &ConversationMessage) -> Option<AgentToolResult> {
+    message.blocks.iter().find_map(|block| match block {
+        ContentBlock::ToolResult {
+            tool_name,
+            output,
+            is_error,
+            ..
+        } => Some(AgentToolResult {
+            tool_name: tool_name.clone(),
+            output: output.clone(),
+            is_error: *is_error,
+        }),
+        _ => None,
+    })
+}
+
 #[allow(clippy::needless_pass_by_value)]
 fn execute_tool_search(input: ToolSearchInput) -> ToolSearchOutput {
     let deferred = deferred_tool_specs();
@@ -2763,12 +3251,28 @@ mod tests {
     }
 
     #[test]
-    fn agent_persists_handoff_metadata() {
+    fn agent_executes_child_conversation_and_persists_results() {
         let _guard = env_lock()
             .lock()
             .unwrap_or_else(std::sync::PoisonError::into_inner);
         let dir = temp_path("agent-store");
         std::env::set_var("CLAWD_AGENT_STORE", &dir);
+        std::env::set_var(
+            "CLAWD_AGENT_TEST_SCRIPT",
+            serde_json::to_string(&vec![
+                vec![json!({
+                    "type": "tool_use",
+                    "id": "tool-1",
+                    "name": "StructuredOutput",
+                    "input": {"ok": true, "items": [1, 2, 3]}
+                })],
+                vec![json!({
+                    "type": "text",
+                    "text": "Child agent completed successfully."
+                })],
+            ])
+            .expect("script json"),
+        );
 
         let result = execute_tool(
             "Agent",
@@ -2780,22 +3284,35 @@ mod tests {
             }),
         )
         .expect("Agent should succeed");
+        std::env::remove_var("CLAWD_AGENT_TEST_SCRIPT");
         std::env::remove_var("CLAWD_AGENT_STORE");
 
         let output: serde_json::Value = serde_json::from_str(&result).expect("valid json");
         assert_eq!(output["name"], "ship-audit");
         assert_eq!(output["subagentType"], "Explore");
-        assert_eq!(output["status"], "queued");
-        assert!(output["createdAt"].as_str().is_some());
+        assert_eq!(output["status"], "completed");
+        assert_eq!(output["depth"], 0);
+        assert_eq!(output["maxDepth"], 3);
+        assert_eq!(output["result"], "Child agent completed successfully.");
+        assert_eq!(output["toolResults"][0]["toolName"], "StructuredOutput");
+        assert_eq!(output["toolResults"][0]["isError"], false);
         let manifest_file = output["manifestFile"].as_str().expect("manifest file");
         let output_file = output["outputFile"].as_str().expect("output file");
         let contents = std::fs::read_to_string(output_file).expect("agent file exists");
         let manifest_contents =
             std::fs::read_to_string(manifest_file).expect("manifest file exists");
-        assert!(contents.contains("Audit the branch"));
-        assert!(contents.contains("Check tests and outstanding work."));
+        assert!(contents.contains("Child agent completed successfully."));
+        assert!(contents.contains("StructuredOutput [ok]"));
         assert!(manifest_contents.contains("\"subagentType\": \"Explore\""));
 
+        std::env::set_var(
+            "CLAWD_AGENT_TEST_SCRIPT",
+            serde_json::to_string(&vec![vec![json!({
+                "type": "text",
+                "text": "Normalized alias check."
+            })]])
+            .expect("script json"),
+        );
         let normalized = execute_tool(
             "Agent",
             &json!({
@@ -2805,10 +3322,19 @@ mod tests {
             }),
         )
         .expect("Agent should normalize built-in aliases");
+        std::env::remove_var("CLAWD_AGENT_TEST_SCRIPT");
         let normalized_output: serde_json::Value =
             serde_json::from_str(&normalized).expect("valid json");
         assert_eq!(normalized_output["subagentType"], "Explore");
 
+        std::env::set_var(
+            "CLAWD_AGENT_TEST_SCRIPT",
+            serde_json::to_string(&vec![vec![json!({
+                "type": "text",
+                "text": "Name normalization check."
+            })]])
+            .expect("script json"),
+        );
         let named = execute_tool(
             "Agent",
             &json!({
@@ -2818,13 +3344,14 @@ mod tests {
             }),
         )
         .expect("Agent should normalize explicit names");
+        std::env::remove_var("CLAWD_AGENT_TEST_SCRIPT");
         let named_output: serde_json::Value = serde_json::from_str(&named).expect("valid json");
         assert_eq!(named_output["name"], "ship-audit");
         let _ = std::fs::remove_dir_all(dir);
     }
 
     #[test]
-    fn agent_rejects_blank_required_fields() {
+    fn agent_rejects_blank_required_fields_and_enforces_max_depth() {
         let missing_description = execute_tool(
             "Agent",
             &json!({
@@ -2844,6 +3371,22 @@ mod tests {
         )
         .expect_err("blank prompt should fail");
         assert!(missing_prompt.contains("prompt must not be empty"));
+
+        let _guard = env_lock()
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        std::env::set_var("CLAWD_AGENT_DEPTH", "1");
+        let depth_error = execute_tool(
+            "Agent",
+            &json!({
+                "description": "Nested agent",
+                "prompt": "Do nested work.",
+                "max_depth": 1
+            }),
+        )
+        .expect_err("max depth should fail");
+        std::env::remove_var("CLAWD_AGENT_DEPTH");
+        assert!(depth_error.contains("max_depth exceeded"));
     }
 
     #[test]