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

@@ -1091,11 +1091,8 @@ dependencies = [
  "compat-harness",
  "crossterm",
  "pulldown-cmark",
- "reqwest",
  "runtime",
- "serde",
  "serde_json",
- "sha2",
  "syntect",
  "tokio",
  "tools",
@@ -1434,10 +1431,12 @@ dependencies = [
 name = "tools"
 version = "0.1.0"
 dependencies = [
+ "api",
  "reqwest",
  "runtime",
  "serde",
  "serde_json",
+ "tokio",
 ]
 
 [[package]]

rust/README.md

@@ -84,15 +84,6 @@ cargo run -p rusty-claude-cli -- logout
 
 This removes only the stored OAuth credentials and preserves unrelated JSON fields in `credentials.json`.
 
-### Self-update
-
-```bash
-cd rust
-cargo run -p rusty-claude-cli -- self-update
-```
-
-The command checks the latest GitHub release for `instructkr/clawd-code`, compares it to the current binary version, downloads the matching binary asset plus checksum manifest, verifies SHA-256, replaces the current executable, and prints the release changelog. If no published release or matching asset exists, it exits safely with an explanatory message.
-
 ## Usage examples
 
 ### 1) Prompt mode
@@ -171,7 +162,6 @@ cargo run -p rusty-claude-cli -- --resume session.json /memory /config
 - `dump-manifests` — print extracted upstream manifest counts
 - `bootstrap-plan` — print the current bootstrap skeleton
 - `system-prompt [--cwd PATH] [--date YYYY-MM-DD]` — render the synthesized system prompt
-- `self-update` — update the installed binary from the latest GitHub release when a matching asset is available
 - `--help` / `-h` — show CLI help
 - `--version` / `-V` — print the CLI version and build info locally (no API call)
 - `--output-format text|json` — choose non-interactive prompt output rendering

rust/crates/rusty-claude-cli/Cargo.toml

@@ -11,11 +11,8 @@ commands = { path = "../commands" }
 compat-harness = { path = "../compat-harness" }
 crossterm = "0.28"
 pulldown-cmark = "0.13"
-reqwest = { version = "0.12", default-features = false, features = ["blocking", "json", "rustls-tls"] }
 runtime = { path = "../runtime" }
-serde = { version = "1", features = ["derive"] }
 serde_json = "1"
-sha2 = "0.10"
 syntect = "5"
 tokio = { version = "1", features = ["rt-multi-thread", "time"] }
 tools = { path = "../tools" }

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

@@ -3,7 +3,6 @@ mod render;
 
 use std::collections::{BTreeMap, BTreeSet};
 use std::env;
-use std::fmt::Write as _;
 use std::fs;
 use std::io::{self, Read, Write};
 use std::net::TcpListener;
@@ -22,7 +21,6 @@ use commands::{
 };
 use compat_harness::{extract_manifest, UpstreamPaths};
 use render::{Spinner, TerminalRenderer};
-use reqwest::blocking::Client;
 use runtime::{
     clear_oauth_credentials, generate_pkce_pair, generate_state, load_system_prompt,
     parse_oauth_callback_request_target, save_oauth_credentials, ApiClient, ApiRequest,
@@ -31,9 +29,7 @@ use runtime::{
     OAuthTokenExchangeRequest, PermissionMode, PermissionPolicy, ProjectContext, RuntimeError,
     Session, TokenUsage, ToolError, ToolExecutor, UsageTracker,
 };
-use serde::Deserialize;
 use serde_json::json;
-use sha2::{Digest, Sha256};
 use tools::{execute_tool, mvp_tool_specs, ToolSpec};
 
 const DEFAULT_MODEL: &str = "claude-sonnet-4-20250514";
@@ -43,18 +39,6 @@ const DEFAULT_OAUTH_CALLBACK_PORT: u16 = 4545;
 const VERSION: &str = env!("CARGO_PKG_VERSION");
 const BUILD_TARGET: Option<&str> = option_env!("TARGET");
 const GIT_SHA: Option<&str> = option_env!("GIT_SHA");
-const SELF_UPDATE_REPOSITORY: &str = "instructkr/clawd-code";
-const SELF_UPDATE_LATEST_RELEASE_URL: &str =
-    "https://api.github.com/repos/instructkr/clawd-code/releases/latest";
-const SELF_UPDATE_USER_AGENT: &str = "rusty-claude-cli-self-update";
-const CHECKSUM_ASSET_CANDIDATES: &[&str] = &[
-    "SHA256SUMS",
-    "SHA256SUMS.txt",
-    "sha256sums",
-    "sha256sums.txt",
-    "checksums.txt",
-    "checksums.sha256",
-];
 
 type AllowedToolSet = BTreeSet<String>;
 
@@ -76,7 +60,6 @@ fn run() -> Result<(), Box<dyn std::error::Error>> {
         CliAction::BootstrapPlan => print_bootstrap_plan(),
         CliAction::PrintSystemPrompt { cwd, date } => print_system_prompt(cwd, date),
         CliAction::Version => print_version(),
-        CliAction::SelfUpdate => run_self_update()?,
         CliAction::ResumeSession {
             session_path,
             commands,
@@ -110,7 +93,6 @@ enum CliAction {
         date: String,
     },
     Version,
-    SelfUpdate,
     ResumeSession {
         session_path: PathBuf,
         commands: Vec<String>,
@@ -246,7 +228,6 @@ fn parse_args(args: &[String]) -> Result<CliAction, String> {
         "dump-manifests" => Ok(CliAction::DumpManifests),
         "bootstrap-plan" => Ok(CliAction::BootstrapPlan),
         "system-prompt" => parse_system_prompt_args(&rest[1..]),
-        "self-update" => Ok(CliAction::SelfUpdate),
         "login" => Ok(CliAction::Login),
         "logout" => Ok(CliAction::Logout),
         "prompt" => {
@@ -553,375 +534,6 @@ fn print_version() {
     println!("{}", render_version_report());
 }
 
-#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
-struct GitHubRelease {
-    tag_name: String,
-    #[serde(default)]
-    body: String,
-    #[serde(default)]
-    assets: Vec<GitHubReleaseAsset>,
-}
-
-#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
-struct GitHubReleaseAsset {
-    name: String,
-    browser_download_url: String,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-struct SelectedReleaseAssets {
-    binary: GitHubReleaseAsset,
-    checksum: GitHubReleaseAsset,
-}
-
-fn run_self_update() -> Result<(), Box<dyn std::error::Error>> {
-    let Some(release) = fetch_latest_release()? else {
-        println!(
-            "{}",
-            render_update_report(
-                "No published release available",
-                Some(VERSION),
-                None,
-                Some("GitHub latest release endpoint returned no published release for instructkr/clawd-code."),
-                None,
-            )
-        );
-        return Ok(());
-    };
-
-    let latest_version = normalize_version_tag(&release.tag_name);
-    if !is_newer_version(VERSION, &latest_version) {
-        println!(
-            "{}",
-            render_update_report(
-                "Already up to date",
-                Some(VERSION),
-                Some(&latest_version),
-                Some("Current binary already matches the latest published release."),
-                Some(&release.body),
-            )
-        );
-        return Ok(());
-    }
-
-    let selected = match select_release_assets(&release) {
-        Ok(selected) => selected,
-        Err(message) => {
-            println!(
-                "{}",
-                render_update_report(
-                    "Release found, but no installable asset matched this platform",
-                    Some(VERSION),
-                    Some(&latest_version),
-                    Some(&message),
-                    Some(&release.body),
-                )
-            );
-            return Ok(());
-        }
-    };
-
-    let client = build_self_update_client()?;
-    let binary_bytes = download_bytes(&client, &selected.binary.browser_download_url)?;
-    let checksum_manifest = download_text(&client, &selected.checksum.browser_download_url)?;
-    let expected_checksum = parse_checksum_for_asset(&checksum_manifest, &selected.binary.name)
-        .ok_or_else(|| {
-            format!(
-                "checksum manifest did not contain an entry for {}",
-                selected.binary.name
-            )
-        })?;
-    let actual_checksum = sha256_hex(&binary_bytes);
-    if actual_checksum != expected_checksum {
-        return Err(format!(
-            "downloaded asset checksum mismatch for {} (expected {}, got {})",
-            selected.binary.name, expected_checksum, actual_checksum
-        )
-        .into());
-    }
-
-    replace_current_executable(&binary_bytes)?;
-
-    println!(
-        "{}",
-        render_update_report(
-            "Update installed",
-            Some(VERSION),
-            Some(&latest_version),
-            Some(&format!(
-                "Installed {} from GitHub release assets for {}.",
-                selected.binary.name,
-                current_target()
-            )),
-            Some(&release.body),
-        )
-    );
-    Ok(())
-}
-
-fn fetch_latest_release() -> Result<Option<GitHubRelease>, Box<dyn std::error::Error>> {
-    let client = build_self_update_client()?;
-    let response = client
-        .get(SELF_UPDATE_LATEST_RELEASE_URL)
-        .header(reqwest::header::ACCEPT, "application/vnd.github+json")
-        .send()?;
-
-    if response.status() == reqwest::StatusCode::NOT_FOUND {
-        return Ok(None);
-    }
-
-    let response = response.error_for_status()?;
-    Ok(Some(response.json()?))
-}
-
-fn build_self_update_client() -> Result<Client, reqwest::Error> {
-    Client::builder().user_agent(SELF_UPDATE_USER_AGENT).build()
-}
-
-fn download_bytes(client: &Client, url: &str) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
-    let response = client.get(url).send()?.error_for_status()?;
-    Ok(response.bytes()?.to_vec())
-}
-
-fn download_text(client: &Client, url: &str) -> Result<String, Box<dyn std::error::Error>> {
-    let response = client.get(url).send()?.error_for_status()?;
-    Ok(response.text()?)
-}
-
-fn normalize_version_tag(version: &str) -> String {
-    version.trim().trim_start_matches('v').to_string()
-}
-
-fn is_newer_version(current: &str, latest: &str) -> bool {
-    compare_versions(latest, current).is_gt()
-}
-
-fn current_target() -> String {
-    BUILD_TARGET.map_or_else(default_target_triple, str::to_string)
-}
-
-fn release_asset_candidates() -> Vec<String> {
-    let mut candidates = target_name_candidates()
-        .into_iter()
-        .flat_map(|target| {
-            let mut names = vec![format!("rusty-claude-cli-{target}")];
-            if env::consts::OS == "windows" {
-                names.push(format!("rusty-claude-cli-{target}.exe"));
-            }
-            names
-        })
-        .collect::<Vec<_>>();
-    if env::consts::OS == "windows" {
-        candidates.push("rusty-claude-cli.exe".to_string());
-    }
-    candidates.push("rusty-claude-cli".to_string());
-    candidates.sort();
-    candidates.dedup();
-    candidates
-}
-
-fn select_release_assets(release: &GitHubRelease) -> Result<SelectedReleaseAssets, String> {
-    let binary = release_asset_candidates()
-        .into_iter()
-        .find_map(|candidate| {
-            release
-                .assets
-                .iter()
-                .find(|asset| asset.name == candidate)
-                .cloned()
-        })
-        .ok_or_else(|| {
-            format!(
-                "no binary asset matched target {} (expected one of: {})",
-                current_target(),
-                release_asset_candidates().join(", ")
-            )
-        })?;
-
-    let checksum = CHECKSUM_ASSET_CANDIDATES
-        .iter()
-        .find_map(|candidate| {
-            release
-                .assets
-                .iter()
-                .find(|asset| asset.name == *candidate)
-                .cloned()
-        })
-        .ok_or_else(|| {
-            format!(
-                "release did not include a checksum manifest (expected one of: {})",
-                CHECKSUM_ASSET_CANDIDATES.join(", ")
-            )
-        })?;
-
-    Ok(SelectedReleaseAssets { binary, checksum })
-}
-
-fn parse_checksum_for_asset(manifest: &str, asset_name: &str) -> Option<String> {
-    manifest.lines().find_map(|line| {
-        let trimmed = line.trim();
-        if trimmed.is_empty() {
-            return None;
-        }
-        if let Some((left, right)) = trimmed.split_once(" = ") {
-            return left
-                .strip_prefix("SHA256 (")
-                .and_then(|value| value.strip_suffix(')'))
-                .filter(|file| *file == asset_name)
-                .map(|_| right.to_ascii_lowercase());
-        }
-        let mut parts = trimmed.split_whitespace();
-        let checksum = parts.next()?;
-        let file = parts
-            .next_back()
-            .or_else(|| parts.next())?
-            .trim_start_matches('*');
-        (file == asset_name).then(|| checksum.to_ascii_lowercase())
-    })
-}
-
-fn sha256_hex(bytes: &[u8]) -> String {
-    format!("{:x}", Sha256::digest(bytes))
-}
-
-fn replace_current_executable(binary_bytes: &[u8]) -> Result<(), Box<dyn std::error::Error>> {
-    let current = env::current_exe()?;
-    replace_executable_at(&current, binary_bytes)
-}
-
-fn replace_executable_at(
-    current: &Path,
-    binary_bytes: &[u8],
-) -> Result<(), Box<dyn std::error::Error>> {
-    let temp_path = current.with_extension("download");
-    let backup_path = current.with_extension("bak");
-
-    if backup_path.exists() {
-        fs::remove_file(&backup_path)?;
-    }
-    fs::write(&temp_path, binary_bytes)?;
-    copy_executable_permissions(current, &temp_path)?;
-
-    fs::rename(current, &backup_path)?;
-    if let Err(error) = fs::rename(&temp_path, current) {
-        let _ = fs::rename(&backup_path, current);
-        let _ = fs::remove_file(&temp_path);
-        return Err(format!("failed to replace current executable: {error}").into());
-    }
-
-    if let Err(error) = fs::remove_file(&backup_path) {
-        eprintln!(
-            "warning: failed to remove self-update backup {}: {error}",
-            backup_path.display()
-        );
-    }
-    Ok(())
-}
-
-#[cfg(unix)]
-fn copy_executable_permissions(
-    source: &Path,
-    destination: &Path,
-) -> Result<(), Box<dyn std::error::Error>> {
-    use std::os::unix::fs::PermissionsExt;
-
-    let mode = fs::metadata(source)?.permissions().mode();
-    fs::set_permissions(destination, fs::Permissions::from_mode(mode))?;
-    Ok(())
-}
-
-#[cfg(not(unix))]
-fn copy_executable_permissions(
-    _source: &Path,
-    _destination: &Path,
-) -> Result<(), Box<dyn std::error::Error>> {
-    Ok(())
-}
-
-fn render_update_report(
-    result: &str,
-    current_version: Option<&str>,
-    latest_version: Option<&str>,
-    detail: Option<&str>,
-    changelog: Option<&str>,
-) -> String {
-    let mut report = String::from(
-        "Self-update
-",
-    );
-    let _ = writeln!(report, "  Repository       {SELF_UPDATE_REPOSITORY}");
-    let _ = writeln!(report, "  Result           {result}");
-    if let Some(current_version) = current_version {
-        let _ = writeln!(report, "  Current version  {current_version}");
-    }
-    if let Some(latest_version) = latest_version {
-        let _ = writeln!(report, "  Latest version   {latest_version}");
-    }
-    if let Some(detail) = detail {
-        let _ = writeln!(report, "  Detail           {detail}");
-    }
-    let trimmed = changelog.map(str::trim).filter(|value| !value.is_empty());
-    if let Some(changelog) = trimmed {
-        report.push_str(
-            "
-Changelog
-",
-        );
-        report.push_str(changelog);
-    }
-    report.trim_end().to_string()
-}
-
-fn compare_versions(left: &str, right: &str) -> std::cmp::Ordering {
-    let left = normalize_version_tag(left);
-    let right = normalize_version_tag(right);
-    let left_parts = version_components(&left);
-    let right_parts = version_components(&right);
-    let max_len = left_parts.len().max(right_parts.len());
-    for index in 0..max_len {
-        let left_part = *left_parts.get(index).unwrap_or(&0);
-        let right_part = *right_parts.get(index).unwrap_or(&0);
-        match left_part.cmp(&right_part) {
-            std::cmp::Ordering::Equal => {}
-            ordering => return ordering,
-        }
-    }
-    std::cmp::Ordering::Equal
-}
-
-fn version_components(version: &str) -> Vec<u64> {
-    version
-        .split(['.', '-'])
-        .map(|part| {
-            part.chars()
-                .take_while(char::is_ascii_digit)
-                .collect::<String>()
-        })
-        .filter(|part| !part.is_empty())
-        .filter_map(|part| part.parse::<u64>().ok())
-        .collect()
-}
-
-fn default_target_triple() -> String {
-    let os = match env::consts::OS {
-        "linux" => "unknown-linux-gnu",
-        "macos" => "apple-darwin",
-        "windows" => "pc-windows-msvc",
-        other => other,
-    };
-    format!("{}-{os}", env::consts::ARCH)
-}
-
-fn target_name_candidates() -> Vec<String> {
-    let mut candidates = Vec::new();
-    if let Some(target) = BUILD_TARGET {
-        candidates.push(target.to_string());
-    }
-    candidates.push(default_target_triple());
-    candidates.push(format!("{}-{}", env::consts::ARCH, env::consts::OS));
-    candidates
-}
-
 fn resume_session(session_path: &Path, commands: &[String]) {
     let session = match Session::load_from_path(session_path) {
         Ok(session) => session,
@@ -1922,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());
@@ -2746,8 +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 self-update");
-    println!("      Update the installed binary from the latest GitHub release");
     println!();
     println!("Flags:");
     println!("  --model MODEL              Override the active model");
@@ -2774,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 self-update");
 }
 
 #[cfg(test)]
@@ -2783,11 +2393,10 @@ mod tests {
         filter_tool_specs, format_compact_report, format_cost_report, format_init_report,
         format_model_report, format_model_switch_report, format_permissions_report,
         format_permissions_switch_report, format_resume_report, format_status_report,
-        format_tool_call_start, format_tool_result, is_newer_version, normalize_permission_mode,
-        normalize_version_tag, parse_args, parse_checksum_for_asset, parse_git_status_metadata,
-        render_config_report, render_init_claude_md, render_memory_report, render_repl_help,
-        render_update_report, resume_supported_slash_commands, select_release_assets,
-        status_context, CliAction, CliOutputFormat, SlashCommand, StatusUsage, DEFAULT_MODEL,
+        format_tool_call_start, format_tool_result, normalize_permission_mode, parse_args,
+        parse_git_status_metadata, render_config_report, render_init_claude_md,
+        render_memory_report, render_repl_help, resume_supported_slash_commands, status_context,
+        CliAction, CliOutputFormat, SlashCommand, StatusUsage, DEFAULT_MODEL,
     };
     use runtime::{ContentBlock, ConversationMessage, MessageRole, PermissionMode};
     use std::path::{Path, PathBuf};
@@ -2856,64 +2465,6 @@ mod tests {
         );
     }
 
-    #[test]
-    fn parses_self_update_subcommand() {
-        assert_eq!(
-            parse_args(&["self-update".to_string()]).expect("self-update should parse"),
-            CliAction::SelfUpdate
-        );
-    }
-
-    #[test]
-    fn normalize_version_tag_trims_v_prefix() {
-        assert_eq!(normalize_version_tag("v0.1.0"), "0.1.0");
-        assert_eq!(normalize_version_tag("0.1.0"), "0.1.0");
-    }
-
-    #[test]
-    fn detects_when_latest_version_differs() {
-        assert!(!is_newer_version("0.1.0", "v0.1.0"));
-        assert!(is_newer_version("0.1.0", "v0.2.0"));
-    }
-
-    #[test]
-    fn parses_checksum_manifest_for_named_asset() {
-        let manifest = "abc123 *rusty-claude-cli\ndef456  other-file\n";
-        assert_eq!(
-            parse_checksum_for_asset(manifest, "rusty-claude-cli"),
-            Some("abc123".to_string())
-        );
-    }
-
-    #[test]
-    fn select_release_assets_requires_checksum_file() {
-        let release = super::GitHubRelease {
-            tag_name: "v0.2.0".to_string(),
-            body: String::new(),
-            assets: vec![super::GitHubReleaseAsset {
-                name: "rusty-claude-cli".to_string(),
-                browser_download_url: "https://example.invalid/rusty-claude-cli".to_string(),
-            }],
-        };
-
-        let error = select_release_assets(&release).expect_err("missing checksum should error");
-        assert!(error.contains("checksum manifest"));
-    }
-
-    #[test]
-    fn update_report_includes_changelog_when_present() {
-        let report = render_update_report(
-            "Already up to date",
-            Some("0.1.0"),
-            Some("0.1.0"),
-            Some("No action taken."),
-            Some("- Added self-update"),
-        );
-        assert!(report.contains("Self-update"));
-        assert!(report.contains("Changelog"));
-        assert!(report.contains("- Added self-update"));
-    }
-
     #[test]
     fn parses_permission_mode_flag() {
         let args = vec!["--permission-mode=read-only".to_string()];

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]