forge_agent/

tooling.rs

//! Tool-call construction + tool-result extraction. 1:1 port of
//! upstream's `agent-sdk/src/bridge/tooling.ts` (714 `LoC`).
//!
//! Three groups of helpers:
//! 1. Front-of-tool: `create_tool_call`, `tool_title`, `normalize_tool_kind`.
//! 2. Result extraction: `build_tool_result_fields` per-tool branches
//!    (Bash / Read / Write / Edit / Agent / `ReadMcpResource`),
//!    `normalize_tool_result_text`, `extract_text`,
//!    `persisted_output_first_line`, `sanitize_sdk_rejection_text`,
//!    `extract_tool_output_metadata`.
//! 3. Helpers: `unwrap_tool_use_result`.

use serde_json::{Map, Value, json};

use forge_primitives::{
    BashOutputMetadata, ChunkContent, ToolCall, ToolCallContent, ToolCallLocation,
    ToolCallUpdateFields, ToolOutputMetadata,
};

// Tool-result preview-size cap. Only the preview limit surfaces in
// user-visible text, so a flat const suffices.
const CACHE_PREVIEW_LIMIT_BYTES: usize = 2048;

fn preview_kilobyte_label() -> String {
    let whole_kb = CACHE_PREVIEW_LIMIT_BYTES / 1024;
    let remainder = CACHE_PREVIEW_LIMIT_BYTES % 1024;
    if remainder == 0 {
        format!("{whole_kb}KB")
    } else {
        // Render as e.g. 1.5KB without going through f64. Only one
        // decimal place - match the previous Display behaviour.
        let tenths = (remainder * 10) / 1024;
        format!("{whole_kb}.{tenths}KB")
    }
}

/// Block types the CLI uses for tool results. Mirrors upstream's
/// `TOOL_RESULT_TYPES` set in tooling.ts:5.
const TOOL_RESULT_TYPES: &[&str] = &[
    "tool_result",
    "tool_search_tool_result",
    "web_fetch_tool_result",
    "web_search_tool_result",
    "code_execution_tool_result",
    "bash_code_execution_tool_result",
    "text_editor_code_execution_tool_result",
    "mcp_tool_result",
];

pub fn is_tool_result_block_type(block_type: &str) -> bool {
    TOOL_RESULT_TYPES.contains(&block_type)
}

/// Mirrors `normalizeToolKind`. Maps tool name to the typed
/// `ToolKind` consumed by a view's tool-card renderer.
fn normalize_tool_kind(name: &str) -> forge_primitives::ToolKind {
    use forge_primitives::ToolKind;
    match name {
        "Bash" => ToolKind::Execute,
        "Read" | "ReadMcpResource" => ToolKind::Read,
        "Write" | "Edit" => ToolKind::Edit,
        "Delete" => ToolKind::Delete,
        "Move" => ToolKind::Move,
        "Glob" | "Grep" => ToolKind::Search,
        "WebFetch" => ToolKind::Fetch,
        "ExitPlanMode" => ToolKind::SwitchMode,
        // "Task" / "Agent" fall through to the "think" default.
        _ => ToolKind::Think,
    }
}

/// Mirrors `toolTitle(name, input)`. Produces the human-friendly
/// title shown on the tool card header (e.g. Bash → command, Glob →
/// pattern + path, etc.).
fn tool_title(name: &str, input: &Value) -> String {
    let record = input.as_object();
    let s =
        |k: &str| -> &str { record.and_then(|r| r.get(k)).and_then(Value::as_str).unwrap_or("") };

    match name {
        "Bash" => {
            let command = s("command");
            if command.is_empty() { "Terminal".to_owned() } else { command.to_owned() }
        }
        "Glob" => {
            let pattern = s("pattern");
            let path = s("path");
            match (pattern.is_empty(), path.is_empty()) {
                (false, false) => format!("Glob {pattern} in {path}"),
                (false, true) => format!("Glob {pattern}"),
                (true, false) => format!("Glob {path}"),
                (true, true) => name.to_owned(),
            }
        }
        "WebFetch" => {
            let url = s("url");
            if url.is_empty() { name.to_owned() } else { format!("WebFetch {url}") }
        }
        "WebSearch" => {
            let query = s("query");
            if query.is_empty() { name.to_owned() } else { format!("WebSearch {query}") }
        }
        "Read" | "Write" | "Edit" | "Delete" => {
            let file_path = s("file_path");
            if file_path.is_empty() { name.to_owned() } else { format!("{name} {file_path}") }
        }
        "Move" => {
            let from = s("from_path");
            let to = s("to_path");
            match (from.is_empty(), to.is_empty()) {
                (false, false) => format!("Move {from} -> {to}"),
                (false, true) => format!("Move {from}"),
                (true, false) => format!("Move {to}"),
                (true, true) => name.to_owned(),
            }
        }
        "LSP" => {
            let operation = s("operation");
            let file_path = s("filePath");
            match (operation.is_empty(), file_path.is_empty()) {
                (false, false) => format!("LSP {operation} {file_path}"),
                (false, true) => format!("LSP {operation}"),
                (true, false) => format!("LSP {file_path}"),
                (true, true) => name.to_owned(),
            }
        }
        "PushNotification" => {
            let message = s("message");
            if message.is_empty() { name.to_owned() } else { format!("PushNotification {message}") }
        }
        "ReadMcpResource" => {
            let uri = s("uri");
            let server = s("server");
            match (server.is_empty(), uri.is_empty()) {
                (false, false) => format!("ReadMcpResource {server} {uri}"),
                (true, false) => format!("ReadMcpResource {uri}"),
                _ => name.to_owned(),
            }
        }
        // ToolSearch surfaces with two wire shapes that both render
        // as the same card: the server `ServerToolUse` discriminator
        // (`tool_search_tool_regex` / `_bm25`) AND the CLIENT tool_use
        // a forge agent calls via deferred tools (wire name literal
        // `"ToolSearch"`, input `{query, max_results}`). Pair them in
        // one arm so the title carries the query regardless of which
        // side of the wire the call comes from. Mirror of
        // `theme::tool_name_label`'s `"ToolSearch" |
        // "tool_search_tool_regex" | "tool_search_tool_bm25"` pairing.
        "ToolSearch" | "tool_search_tool_regex" | "tool_search_tool_bm25" => {
            let query = s("query");
            if query.is_empty() { "ToolSearch".to_owned() } else { format!("ToolSearch {query}") }
        }
        "web_search" => {
            let query = s("query");
            if query.is_empty() { "WebSearch".to_owned() } else { format!("WebSearch {query}") }
        }
        // Wire shape: `{skill: "<name>", args?: "<free text>"}`. The
        // args ride the title like Bash's command; the render clips.
        "Skill" => {
            let skill = s("skill");
            if skill.is_empty() {
                name.to_owned()
            } else {
                let args = s("args");
                if args.is_empty() {
                    format!("Skill {skill}")
                } else {
                    format!("Skill {skill} {args}")
                }
            }
        }
        "web_fetch" => {
            let url = s("url");
            if url.is_empty() { "WebFetch".to_owned() } else { format!("WebFetch {url}") }
        }
        "advisor" => {
            let query = s("query");
            if query.is_empty() { "Advisor".to_owned() } else { format!("Advisor {query}") }
        }
        _ => name.to_owned(),
    }
}

/// Mirrors `editDiffContent(name, input)` - initial diff content for
/// Edit / Write tool cards (before the result lands). Empty Vec for
/// other tools.
fn edit_diff_content(name: &str, input: &Value) -> Vec<ToolCallContent> {
    let Some(record) = input.as_object() else {
        return Vec::new();
    };
    let s = |k: &str| record.get(k).and_then(Value::as_str).unwrap_or("");
    let file_path = s("file_path");
    if file_path.is_empty() {
        return Vec::new();
    }

    if name == "Edit" {
        let old_text = s("old_string");
        let new_text = s("new_string");
        if old_text.is_empty() && new_text.is_empty() {
            return Vec::new();
        }
        return vec![ToolCallContent::Diff {
            new_path: file_path.to_owned(),
            old: old_text.to_owned(),
            new: new_text.to_owned(),
            repository: None,
        }];
    }
    if name == "Write" {
        let new_text = s("content");
        if new_text.is_empty() {
            return Vec::new();
        }
        return vec![ToolCallContent::Diff {
            new_path: file_path.to_owned(),
            old: String::new(),
            new: new_text.to_owned(),
            repository: None,
        }];
    }
    Vec::new()
}

/// Mirrors `createToolCall(toolUseId, name, input, parentToolUseId)`.
/// Builds the rich `ToolCall` envelope upstream emits when the
/// assistant first invokes a tool.
pub fn create_tool_call(
    tool_use_id: &str,
    name: &str,
    input: &Value,
    parent_tool_use_id: Option<&str>,
) -> ToolCall {
    let file_path = input.as_object().and_then(|r| r.get("file_path")).and_then(Value::as_str);
    let locations = file_path.map(|p| vec![ToolCallLocation::new(p)]).unwrap_or_default();
    let meta = json!({
        "claudeCode": {
            "toolName": name,
            "parentToolUseId": parent_tool_use_id,
        }
    });

    ToolCall {
        tool_call_id: tool_use_id.to_owned(),
        title: tool_title(name, input),
        kind: normalize_tool_kind(name),
        status: forge_primitives::ToolCallStatus::Pending,
        content: edit_diff_content(name, input),
        raw_input: Some(input.clone()),
        raw_output: None,
        output_metadata: None,
        task_metadata: None,
        locations,
        meta: Some(meta),
    }
}

// ----- text extraction + persisted-output preview -----

/// Mirrors `extractText(value)` - flattens a `tool_result` content
/// payload into a single `String`. Accepts string, array of
/// `{ type: "text", text }` blocks, or a single object carrying prose
/// under one of `plan` / `description` / `summary` / `message` /
/// `text` (priority order: plan-mode-specific first, generic last).
///
/// Returns `""` for any other shape so the caller knows the value
/// can't be rendered as user-facing text - the alternative
/// (JSON-stringifying arbitrary structures) leaks raw `\n` escapes
/// into chat (bug #136).
fn extract_text(value: &Value) -> String {
    if let Some(s) = value.as_str() {
        return s.to_owned();
    }
    if let Some(arr) = value.as_array() {
        return arr
            .iter()
            .filter_map(|entry| {
                if let Some(s) = entry.as_str() {
                    return Some(s.to_owned());
                }
                entry
                    .as_object()
                    .and_then(|r| r.get("text"))
                    .and_then(Value::as_str)
                    .map(str::to_owned)
            })
            .filter(|s| !s.is_empty())
            .collect::<Vec<_>>()
            .join("\n");
    }
    if let Some(obj) = value.as_object() {
        for key in &["plan", "description", "summary", "message", "text"] {
            if let Some(s) = obj.get(*key).and_then(Value::as_str) {
                return s.to_owned();
            }
        }
    }
    String::new()
}

const PERSISTED_OUTPUT_OPEN_TAG: &str = "<persisted-output>";
const PERSISTED_OUTPUT_CLOSE_TAG: &str = "</persisted-output>";

fn persisted_output_inner_text(text: &str) -> Option<&str> {
    let lower = text.to_ascii_lowercase();
    let open = lower.find(PERSISTED_OUTPUT_OPEN_TAG)?;
    let body_start = open + PERSISTED_OUTPUT_OPEN_TAG.len();
    let close = lower[body_start..].find(PERSISTED_OUTPUT_CLOSE_TAG)? + body_start;
    Some(&text[body_start..close])
}

fn persisted_output_first_line(text: &str) -> Option<String> {
    let inner = persisted_output_inner_text(text)?;
    let expected_preview = format!("preview (first {}):", preview_kilobyte_label().to_lowercase());
    for line in inner.split(['\n', '\r']) {
        let cleaned: String = line
            .chars()
            .skip_while(|c| matches!(*c, ' ' | '\t' | '|' | '\u{2502}' | '\u{2503}' | '\u{2551}'))
            .collect();
        let cleaned = cleaned.trim();
        if cleaned.is_empty() {
            continue;
        }
        if cleaned.eq_ignore_ascii_case(&expected_preview) {
            continue;
        }
        return Some(cleaned.to_owned());
    }
    None
}

// ----- SDK rejection sanitization -----

const USER_REJECTED_TOOL_USE_EXACT: &str = "The user doesn't want to proceed with this tool use. The tool use was rejected (eg. if it was a file edit, the new_string was NOT written to the file). STOP what you are doing and wait for the user to tell you how to proceed.";
const USER_REJECTED_TOOL_USE_PREFIX: &str = "The user doesn't want to proceed with this tool use. The tool use was rejected (eg. if it was a file edit, the new_string was NOT written to the file). To tell you how to proceed, the user said:";
const PERMISSION_DENIED_TOOL_USE_EXACT: &str = "Permission for this tool use was denied. The tool use was rejected (eg. if it was a file edit, the new_string was NOT written to the file). Try a different approach or report the limitation to complete your task.";
const PERMISSION_DENIED_TOOL_USE_PREFIX: &str = "Permission for this tool use was denied. The tool use was rejected (eg. if it was a file edit, the new_string was NOT written to the file). The user said:";

fn sanitize_sdk_rejection_text(text: &str) -> String {
    let normalized = text.trim();
    if normalized == USER_REJECTED_TOOL_USE_EXACT
        || normalized.starts_with(USER_REJECTED_TOOL_USE_PREFIX)
    {
        return "Cancelled by user.".to_owned();
    }
    if normalized == PERMISSION_DENIED_TOOL_USE_EXACT
        || normalized.starts_with(PERMISSION_DENIED_TOOL_USE_PREFIX)
    {
        return "Permission denied.".to_owned();
    }
    text.to_owned()
}

fn normalize_tool_result_text(value: &Value, is_error: bool) -> String {
    let text = extract_text(value);
    if text.is_empty() {
        return String::new();
    }
    let normalized = persisted_output_first_line(&text).unwrap_or(text);
    if is_error { sanitize_sdk_rejection_text(&normalized) } else { normalized }
}

// ----- Result-record candidate walking -----

fn push_record(candidates: &mut Vec<Map<String, Value>>, value: &Value) {
    if let Some(r) = value.as_object() {
        candidates.push(r.clone());
    }
}

fn push_records(candidates: &mut Vec<Map<String, Value>>, value: &Value) {
    if let Some(arr) = value.as_array() {
        for entry in arr {
            push_record(candidates, entry);
        }
        return;
    }
    push_record(candidates, value);
}

fn push_nested_records(candidates: &mut Vec<Map<String, Value>>, value: &Value) {
    if let Some(arr) = value.as_array() {
        for entry in arr {
            push_nested_records(candidates, entry);
        }
        return;
    }
    let Some(record) = value.as_object() else {
        return;
    };
    if let Some(v) = record.get("result") {
        push_records(candidates, v);
    }
    if let Some(v) = record.get("data") {
        push_records(candidates, v);
    }
    if let Some(v) = record.get("content") {
        push_records(candidates, v);
    }
}

fn result_record_candidates(
    raw_result: Option<&Value>,
    raw_content: Option<&Value>,
) -> Vec<Map<String, Value>> {
    let mut out = Vec::new();
    if let Some(v) = raw_result {
        push_records(&mut out, v);
        push_nested_records(&mut out, v);
    }
    if let Some(v) = raw_content {
        push_records(&mut out, v);
        push_nested_records(&mut out, v);
    }
    out
}

// ----- per-tool extraction -----

fn find_bash_result_record(
    raw_result: Option<&Value>,
    raw_content: Option<&Value>,
) -> Option<Map<String, Value>> {
    result_record_candidates(raw_result, raw_content).into_iter().find(|c| {
        c.contains_key("stdout")
            || c.contains_key("stderr")
            || c.contains_key("backgroundTaskId")
            || c.contains_key("backgroundedByUser")
            || c.contains_key("assistantAutoBackgrounded")
    })
}

fn bash_background_message(record: &Map<String, Value>) -> String {
    let Some(task_id) = record.get("backgroundTaskId").and_then(Value::as_str) else {
        return String::new();
    };
    if task_id.is_empty() {
        return String::new();
    }
    if record.get("assistantAutoBackgrounded").and_then(Value::as_bool) == Some(true) {
        return format!("Command was auto-backgrounded by assistant mode with ID: {task_id}.");
    }
    if record.get("backgroundedByUser").and_then(Value::as_bool) == Some(true) {
        return format!("Command was backgrounded by user with ID: {task_id}.");
    }
    format!("Command is running in background with ID: {task_id}.")
}

/// True when a `tool_result` carries a background sentinel - the same
/// fields Bash keys on (`backgroundTaskId` / `assistantAutoBackgrounded`
/// / `backgroundedByUser`).
fn result_indicates_background(raw_result: Option<&Value>, raw_content: Option<&Value>) -> bool {
    result_record_candidates(raw_result, raw_content).iter().any(|c| {
        c.get("backgroundTaskId").and_then(Value::as_str).is_some_and(|s| !s.is_empty())
            || c.get("assistantAutoBackgrounded").and_then(Value::as_bool) == Some(true)
            || c.get("backgroundedByUser").and_then(Value::as_bool) == Some(true)
    })
}

fn build_bash_display_output(record: &Map<String, Value>) -> String {
    let mut segments = Vec::new();
    if let Some(s) = record.get("stdout").and_then(Value::as_str)
        && !s.is_empty()
    {
        segments.push(s.to_owned());
    }
    if let Some(s) = record.get("stderr").and_then(Value::as_str)
        && !s.is_empty()
    {
        segments.push(s.to_owned());
    }
    if record.get("interrupted").and_then(Value::as_bool) == Some(true) {
        segments.push("Command was aborted before completion.".to_owned());
    }
    let bg = bash_background_message(record);
    if !bg.is_empty() {
        segments.push(bg);
    }
    segments.join("\n")
}

fn file_unchanged_result_text(raw_result: Option<&Value>, raw_content: Option<&Value>) -> String {
    for candidate in result_record_candidates(raw_result, raw_content) {
        if candidate.get("type").and_then(Value::as_str) != Some("file_unchanged") {
            continue;
        }
        if let Some(file_record) = candidate.get("file").and_then(Value::as_object)
            && let Some(file_path) = file_record.get("filePath").and_then(Value::as_str)
        {
            let trimmed = file_path.trim();
            if !trimmed.is_empty() {
                return format!("File unchanged: {trimmed}");
            }
        }
    }
    String::new()
}

fn agent_title_from_agent_output(
    raw_result: Option<&Value>,
    raw_content: Option<&Value>,
) -> String {
    for candidate in result_record_candidates(raw_result, raw_content) {
        if let Some(agent_type) = candidate.get("agentType").and_then(Value::as_str) {
            let trimmed = agent_type.trim();
            if !trimmed.is_empty() {
                return trimmed.to_owned();
            }
        }
    }
    String::new()
}

fn write_diff_from_input(raw_input: Option<&Value>) -> Vec<ToolCallContent> {
    let Some(record) = raw_input.and_then(Value::as_object) else {
        return Vec::new();
    };
    let file_path = record.get("file_path").and_then(Value::as_str).unwrap_or("");
    let content = record.get("content").and_then(Value::as_str).unwrap_or("");
    if file_path.is_empty() || content.is_empty() {
        return Vec::new();
    }
    vec![ToolCallContent::Diff {
        new_path: file_path.to_owned(),
        old: String::new(),
        new: content.to_owned(),
        repository: None,
    }]
}

fn edit_diff_from_input(raw_input: Option<&Value>) -> Vec<ToolCallContent> {
    let Some(record) = raw_input.and_then(Value::as_object) else {
        return Vec::new();
    };
    let file_path = record.get("file_path").and_then(Value::as_str).unwrap_or("");
    let old_text = record
        .get("old_string")
        .or_else(|| record.get("oldString"))
        .and_then(Value::as_str)
        .unwrap_or("");
    let new_text = record
        .get("new_string")
        .or_else(|| record.get("newString"))
        .and_then(Value::as_str)
        .unwrap_or("");
    if file_path.is_empty() || (old_text.is_empty() && new_text.is_empty()) {
        return Vec::new();
    }
    vec![ToolCallContent::Diff {
        new_path: file_path.to_owned(),
        old: old_text.to_owned(),
        new: new_text.to_owned(),
        repository: None,
    }]
}

fn write_diff_from_result(raw_content: Option<&Value>) -> Vec<ToolCallContent> {
    let candidates: Vec<&Value> = match raw_content {
        Some(v) => v.as_array().map_or_else(|| vec![v], |a| a.iter().collect()),
        None => Vec::new(),
    };
    for candidate in candidates {
        let Some(record) = candidate.as_object() else {
            continue;
        };
        let file_path = record
            .get("filePath")
            .or_else(|| record.get("file_path"))
            .and_then(Value::as_str)
            .unwrap_or("");
        let content = record.get("content").and_then(Value::as_str).unwrap_or("");
        let original_raw = record.get("originalFile").or_else(|| record.get("original_file"));
        let git_diff = record.get("gitDiff").and_then(Value::as_object);
        let repository = git_diff
            .and_then(|g| g.get("repository"))
            .and_then(Value::as_str)
            .map(str::trim)
            .filter(|s| !s.is_empty())
            .map(str::to_owned);

        if file_path.is_empty() || content.is_empty() || original_raw.is_none() {
            continue;
        }
        let original = original_raw.and_then(Value::as_str).map_or_else(String::new, str::to_owned);
        return vec![ToolCallContent::Diff {
            new_path: file_path.to_owned(),
            old: original,
            new: content.to_owned(),
            repository,
        }];
    }
    Vec::new()
}

fn edit_diff_from_result(
    raw_result: Option<&Value>,
    raw_input: Option<&Value>,
) -> Vec<ToolCallContent> {
    let Some(input_record) = raw_input.and_then(Value::as_object) else {
        return edit_diff_from_input(raw_input);
    };
    let file_path = input_record.get("file_path").and_then(Value::as_str).unwrap_or("");
    let old_text = input_record
        .get("old_string")
        .or_else(|| input_record.get("oldString"))
        .and_then(Value::as_str)
        .unwrap_or("");
    let new_text = input_record
        .get("new_string")
        .or_else(|| input_record.get("newString"))
        .and_then(Value::as_str)
        .unwrap_or("");
    if file_path.is_empty() || (old_text.is_empty() && new_text.is_empty()) {
        return Vec::new();
    }
    for candidate in result_record_candidates(raw_result, None) {
        let candidate_path = candidate
            .get("filePath")
            .or_else(|| candidate.get("file_path"))
            .and_then(Value::as_str)
            .unwrap_or("");
        let git_diff = candidate.get("gitDiff").and_then(Value::as_object);
        if candidate_path.is_empty() && git_diff.is_none() {
            continue;
        }
        if !candidate_path.is_empty() && candidate_path != file_path {
            continue;
        }
        let repository = git_diff
            .and_then(|g| g.get("repository"))
            .and_then(Value::as_str)
            .map(str::trim)
            .filter(|s| !s.is_empty())
            .map(str::to_owned);
        return vec![ToolCallContent::Diff {
            new_path: file_path.to_owned(),
            old: old_text.to_owned(),
            new: new_text.to_owned(),
            repository,
        }];
    }
    edit_diff_from_input(raw_input)
}

fn parse_json_candidate(value: Option<&Value>) -> Option<Value> {
    let text = value.map_or_else(String::new, |v| {
        if let Some(s) = v.as_str() { s.to_owned() } else { extract_text(v) }
    });
    let trimmed = text.trim();
    if !(trimmed.starts_with('{') || trimmed.starts_with('[')) {
        return None;
    }
    serde_json::from_str(trimmed)
        .inspect_err(|e| {
            tracing::debug!(
                target: crate::logging::targets::TOOLING,
                error = %e,
                raw_prefix = %trimmed.chars().take(120).collect::<String>(),
                "tool output looked like JSON but failed to parse; falling back to plain-text rendering",
            );
        })
        .ok()
}

fn push_structured_record_candidates(candidates: &mut Vec<Map<String, Value>>, value: &Value) {
    let Some(record) = value.as_object() else {
        return;
    };
    candidates.push(record.clone());
    for key in ["result", "data", "content"] {
        if let Some(nested) = record.get(key).and_then(Value::as_object) {
            candidates.push(nested.clone());
        }
    }
}

fn mcp_resource_content_from_result(
    raw_result: Option<&Value>,
    raw_content: Option<&Value>,
) -> Vec<ToolCallContent> {
    let mut candidates: Vec<Map<String, Value>> = Vec::new();
    if let Some(v) = raw_result {
        push_structured_record_candidates(&mut candidates, v);
    }
    if let Some(v) = raw_content {
        push_structured_record_candidates(&mut candidates, v);
    }
    if let Some(v) = parse_json_candidate(raw_result) {
        push_structured_record_candidates(&mut candidates, &v);
    }
    if let Some(v) = parse_json_candidate(raw_content) {
        push_structured_record_candidates(&mut candidates, &v);
    }

    for candidate in candidates {
        let Some(contents) = candidate.get("contents").and_then(Value::as_array) else {
            continue;
        };
        if contents.is_empty() {
            continue;
        }
        let mut mapped: Vec<ToolCallContent> = Vec::new();
        for entry in contents {
            let Some(record) = entry.as_object() else {
                continue;
            };
            let Some(uri) = record.get("uri").and_then(Value::as_str) else {
                continue;
            };
            if uri.is_empty() {
                continue;
            }
            let text = record
                .get("text")
                .and_then(Value::as_str)
                .filter(|s| !s.is_empty())
                .map(str::to_owned);
            let mime_type = record
                .get("mimeType")
                .and_then(Value::as_str)
                .map(str::trim)
                .filter(|s| !s.is_empty())
                .map(str::to_owned);
            let blob_saved_to = record
                .get("blobSavedTo")
                .and_then(Value::as_str)
                .map(str::trim)
                .filter(|s| !s.is_empty())
                .map(str::to_owned);
            if text.is_none() && blob_saved_to.is_none() {
                continue;
            }
            mapped.push(ToolCallContent::McpResource {
                uri: uri.to_owned(),
                mime_type,
                text,
                blob_saved_to,
            });
        }
        if !mapped.is_empty() {
            return mapped;
        }
    }
    Vec::new()
}

// ----- output_metadata extractor -----

fn extract_tool_output_metadata(
    tool_name: &str,
    raw_result: Option<&Value>,
    raw_content: Option<&Value>,
) -> Option<ToolOutputMetadata> {
    let candidates = result_record_candidates(raw_result, raw_content);

    if tool_name == "Bash" {
        for candidate in &candidates {
            if let Some(b) = candidate.get("assistantAutoBackgrounded").and_then(Value::as_bool) {
                return Some(ToolOutputMetadata {
                    bash: Some(BashOutputMetadata { assistant_auto_backgrounded: Some(b) }),
                });
            }
        }
        return None;
    }

    None
}

fn resolve_tool_name(base: Option<&ToolCall>) -> String {
    let Some(meta) = base.and_then(|b| b.meta.as_ref()) else {
        return String::new();
    };
    let Some(claude_code) = meta.get("claudeCode").and_then(Value::as_object) else {
        return String::new();
    };
    claude_code.get("toolName").and_then(Value::as_str).unwrap_or("").to_owned()
}

// ----- main entry: build_tool_result_fields -----

/// Mirrors `buildToolResultFields(isError, rawContent, base?, rawResult?)`.
/// The high-level entry that turns an arbitrary `tool_result` block into
/// the structured `ToolCallUpdateFields` upstream's TUI consumes.
pub fn build_tool_result_fields(
    is_error: bool,
    raw_content: Option<&Value>,
    base: Option<&ToolCall>,
    raw_result: Option<&Value>,
) -> ToolCallUpdateFields {
    let tool_name = resolve_tool_name(base);
    let mut fields = ToolCallUpdateFields {
        status: Some(if is_error {
            forge_primitives::ToolCallStatus::Failed
        } else {
            forge_primitives::ToolCallStatus::Completed
        }),
        ..Default::default()
    };

    // Read: file_unchanged shortcut. Early return.
    let file_unchanged_text = if !is_error && tool_name == "Read" {
        file_unchanged_result_text(raw_result, raw_content)
    } else {
        String::new()
    };
    if !file_unchanged_text.is_empty() {
        fields.raw_output = Some(file_unchanged_text.clone());
        fields.content = Some(vec![ToolCallContent::Content {
            content: ChunkContent::Text { text: file_unchanged_text },
        }]);
        return fields;
    }

    // Agent: title from agentType, and never stamp Completed on a
    // background sentinel while the subagent runs (mirrors Bash).
    if !is_error && tool_name == "Agent" {
        let agent_title = agent_title_from_agent_output(raw_result, raw_content);
        if !agent_title.is_empty() {
            fields.title = Some(agent_title);
        }
        if result_indicates_background(raw_result, raw_content) {
            fields.status = None;
        }
    }

    // Bash: extract structured output, otherwise normalise the text.
    let bash_record =
        if tool_name == "Bash" { find_bash_result_record(raw_result, raw_content) } else { None };
    let normalized_raw_output =
        raw_content.map(|v| normalize_tool_result_text(v, is_error)).unwrap_or_default();
    let raw_output = if let Some(record) = bash_record.as_ref() {
        build_bash_display_output(record)
    } else if !normalized_raw_output.is_empty() {
        normalized_raw_output
    } else {
        // Defensive: when `extract_text` couldn't recognize the shape,
        // only fall back for primitive string values. JSON-dumping
        // arbitrary objects/arrays leaks raw `\n` escapes into chat
        // (bug #136). `extract_text` already handles `Value::String`,
        // so this branch is effectively unreachable for well-formed
        // wire content - kept as a safe path.
        raw_content.and_then(Value::as_str).map(str::to_owned).unwrap_or_default()
    };
    if !raw_output.is_empty() {
        fields.raw_output = Some(raw_output.clone());
    }

    // output_metadata: per-tool.
    if let Some(meta) = extract_tool_output_metadata(&tool_name, raw_result, raw_content) {
        fields.output_metadata = Some(meta);
    }

    // Write: structured diff.
    if !is_error && tool_name == "Write" {
        let structured = write_diff_from_result(raw_content);
        if !structured.is_empty() {
            fields.content = Some(structured);
            return fields;
        }
        let from_input = write_diff_from_input(base.and_then(|b| b.raw_input.as_ref()));
        if !from_input.is_empty() {
            fields.content = Some(from_input);
            return fields;
        }
    }

    // Edit: structured diff (fall through to base.content if already set).
    if !is_error && tool_name == "Edit" {
        let structured = edit_diff_from_result(raw_result, base.and_then(|b| b.raw_input.as_ref()));
        if !structured.is_empty() {
            fields.content = Some(structured);
            return fields;
        }
        if base.is_some_and(|b| b.content.iter().any(|c| matches!(c, ToolCallContent::Diff { .. })))
        {
            return fields;
        }
    }

    // ReadMcpResource: structured resource content.
    if !is_error && tool_name == "ReadMcpResource" {
        let structured = mcp_resource_content_from_result(raw_result, raw_content);
        if !structured.is_empty() {
            fields.content = Some(structured);
            return fields;
        }
    }

    // ToolSearch: the deferred-tools client tool's result wire shape
    // is an array of `{type: tool_reference, tool_name: "..."}` blocks
    // that `extract_text` filters to "". Walk the array for the
    // tool_name fields directly and synthesise a compact one-line
    // summary so the card body shows what the search matched without
    // dumping the raw `<functions>` schema.
    if !is_error && tool_name == "ToolSearch" {
        let matches = tool_search_matches_from_content(raw_content);
        if !matches.is_empty() {
            let summary = format!("Found {}", matches.join(", "));
            fields.raw_output = Some(summary.clone());
            fields.content = Some(vec![ToolCallContent::Content {
                content: ChunkContent::Text { text: summary },
            }]);
            return fields;
        }
    }

    // Generic fallback: wrap raw_output as content.
    if !raw_output.is_empty() {
        fields.content = Some(vec![ToolCallContent::Content {
            content: ChunkContent::Text { text: raw_output },
        }]);
    }
    fields
}

/// Walk a `tool_result.content` array looking for the CLIENT
/// `ToolSearch` result wire shape -
/// `[{type: "tool_reference", tool_name: "..."}, ...]` - and return
/// the matched tool names in source order. Anything not a
/// tool_reference entry is skipped, so a mixed-content result still
/// surfaces the references it carried.
fn tool_search_matches_from_content(raw_content: Option<&Value>) -> Vec<String> {
    let Some(arr) = raw_content.and_then(Value::as_array) else {
        return Vec::new();
    };
    let mut out = Vec::with_capacity(arr.len());
    for entry in arr {
        let Some(record) = entry.as_object() else { continue };
        if record.get("type").and_then(Value::as_str) != Some("tool_reference") {
            continue;
        }
        if let Some(name) =
            record.get("tool_name").and_then(Value::as_str).map(str::trim).filter(|s| !s.is_empty())
        {
            out.push(name.to_owned());
        }
    }
    out
}

/// Mirrors `unwrapToolUseResult(rawResult)`. Walks the `tool_result`
/// envelope: if the value is an object, surfaces the inner `content`
/// / `result` / `text` field and the `is_error` / `error` flag.
pub struct UnwrappedToolResult {
    pub is_error: bool,
    pub content: Value,
}

pub fn unwrap_tool_use_result(raw_result: &Value) -> UnwrappedToolResult {
    let Some(record) = raw_result.as_object() else {
        return UnwrappedToolResult { is_error: false, content: raw_result.clone() };
    };
    let is_error = record.get("is_error").and_then(Value::as_bool).unwrap_or(false)
        || record.get("error").and_then(Value::as_bool).unwrap_or(false);
    if let Some(c) = record.get("content") {
        return UnwrappedToolResult { is_error, content: c.clone() };
    }
    if let Some(c) = record.get("result") {
        return UnwrappedToolResult { is_error, content: c.clone() };
    }
    if let Some(c) = record.get("text") {
        return UnwrappedToolResult { is_error, content: c.clone() };
    }
    UnwrappedToolResult { is_error, content: raw_result.clone() }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;

    fn make_base(name: &str, input: &serde_json::Value) -> ToolCall {
        create_tool_call("tu_1", name, input, None)
    }

    #[test]
    fn create_tool_call_titles_per_tool() {
        use forge_primitives::ToolKind;
        let bash = create_tool_call("tu1", "Bash", &json!({"command": "ls"}), None);
        assert_eq!(bash.title, "ls");
        assert_eq!(bash.kind, ToolKind::Execute);

        let read = create_tool_call("tu2", "Read", &json!({"file_path": "/x"}), None);
        assert_eq!(read.title, "Read /x");
        assert_eq!(read.kind, ToolKind::Read);

        let glob =
            create_tool_call("tu3", "Glob", &json!({"pattern": "*.rs", "path": "src"}), None);
        assert_eq!(glob.title, "Glob *.rs in src");
        assert_eq!(glob.kind, ToolKind::Search);

        let task = create_tool_call("tu4", "Task", &json!({}), None);
        assert_eq!(task.kind, ToolKind::Think);
    }

    /// Server-side tools (`ServerToolUse` wire blocks) - the wire `name`
    /// is the discriminator literal (e.g. `tool_search_tool_regex`,
    /// `web_search`). Without a tool_title arm the title falls back to
    /// the raw wire name and the card body is empty - the LLM's query
    /// is invisible. Pull the relevant input field (query / url) so the
    /// card carries it.
    #[test]
    fn create_tool_call_titles_server_tools_carry_query_or_url() {
        let regex = create_tool_call(
            "stu1",
            "tool_search_tool_regex",
            &json!({"query": "select:CronList"}),
            None,
        );
        assert_eq!(regex.title, "ToolSearch select:CronList");

        let bm25 = create_tool_call(
            "stu2",
            "tool_search_tool_bm25",
            &json!({"query": "notebook jupyter"}),
            None,
        );
        assert_eq!(bm25.title, "ToolSearch notebook jupyter");

        let web_search =
            create_tool_call("stu3", "web_search", &json!({"query": "rust async"}), None);
        assert_eq!(web_search.title, "WebSearch rust async");

        let web_fetch =
            create_tool_call("stu4", "web_fetch", &json!({"url": "https://example.com"}), None);
        assert_eq!(web_fetch.title, "WebFetch https://example.com");

        let advisor =
            create_tool_call("stu5", "advisor", &json!({"query": "how to handle X"}), None);
        assert_eq!(advisor.title, "Advisor how to handle X");
    }

    /// The CLI's Skill tool_use input is a `skill` name plus optional
    /// free-text `args` (live shape, reference-captures/skill.jsonl and
    /// Ved's own transcripts). Without an arm the title fell back to
    /// the bare "Skill", so the L1 card header and the L2 group child
    /// row carried no argument information.
    #[test]
    fn create_tool_call_titles_skill_carries_skill_name_and_args() {
        let with_args = create_tool_call(
            "tu_s1",
            "Skill",
            &json!({"skill": "pr-review-loop", "args": "661"}),
            None,
        );
        assert_eq!(with_args.title, "Skill pr-review-loop 661");

        let name_only = create_tool_call("tu_s2", "Skill", &json!({"skill": "code-review"}), None);
        assert_eq!(name_only.title, "Skill code-review");

        let empty = create_tool_call("tu_s3", "Skill", &json!({}), None);
        assert_eq!(empty.title, "Skill");
        assert!(
            !empty.title.ends_with(' '),
            "empty-input title must not end with whitespace; got {:?}",
            empty.title,
        );
    }

    /// Delete and Move arms per issue #848. UNVERIFIED wire shapes:
    /// zero live traffic, no reference capture, and no tool definition
    /// in the CLI bundle - the field names follow the issue's spec, and
    /// a mismatch renders the bare name exactly as the missing arm did.
    #[test]
    fn create_tool_call_titles_delete_and_move_carry_paths() {
        let delete = create_tool_call("tu_d1", "Delete", &json!({"file_path": "/x/f.rs"}), None);
        assert_eq!(delete.title, "Delete /x/f.rs");
        assert_eq!(create_tool_call("tu_d2", "Delete", &json!({}), None).title, "Delete");

        let move_both = create_tool_call(
            "tu_m1",
            "Move",
            &json!({"from_path": "/a/old.rs", "to_path": "/b/new.rs"}),
            None,
        );
        assert_eq!(move_both.title, "Move /a/old.rs -> /b/new.rs");
        assert_eq!(create_tool_call("tu_m2", "Move", &json!({}), None).title, "Move",);
    }

    /// LSP and PushNotification shapes from the reference captures
    /// (lsp.jsonl: operation + filePath + line/character;
    /// push_notification.jsonl: message + status). The title carries
    /// the discriminative fields and drops the positional ones.
    #[test]
    fn create_tool_call_titles_lsp_and_push_notification_carry_payload() {
        let lsp = create_tool_call(
            "tu_l1",
            "LSP",
            &json!({
                "operation": "documentSymbol",
                "filePath": "crates/forge-primitives/src/messages.rs",
                "line": 1,
                "character": 1,
            }),
            None,
        );
        assert_eq!(lsp.title, "LSP documentSymbol crates/forge-primitives/src/messages.rs");

        let push = create_tool_call(
            "tu_p1",
            "PushNotification",
            &json!({"message": "reference capture: forge wire shape probe", "status": "proactive"}),
            None,
        );
        assert_eq!(push.title, "PushNotification reference capture: forge wire shape probe");

        assert_eq!(create_tool_call("tu_l2", "LSP", &json!({}), None).title, "LSP");
        assert_eq!(
            create_tool_call("tu_p2", "PushNotification", &json!({}), None).title,
            "PushNotification",
        );
    }

    /// CLIENT-side `ToolSearch` (deferred-tools tool a forge agent
    /// calls itself; wire name is the literal `"ToolSearch"`, not
    /// the server `tool_search_tool_*` discriminator). Locks the
    /// client-name -> query-arm pairing - without it the card
    /// renders `\u{2316} ToolSearch ToolSearch` (duplicated label,
    /// since the generic fallback returns the bare name) and the
    /// user can't see the query the LLM searched for.
    #[test]
    fn create_tool_call_titles_client_tool_search_carries_query() {
        let with_query = create_tool_call(
            "tu_client_ts",
            "ToolSearch",
            &json!({"query": "schedule cron recurring"}),
            None,
        );
        assert_eq!(with_query.title, "ToolSearch schedule cron recurring");

        // Empty-query: stable title, no trailing space.
        let empty = create_tool_call("tu_client_ts2", "ToolSearch", &json!({}), None);
        assert_eq!(empty.title, "ToolSearch");
        assert!(
            !empty.title.ends_with(' '),
            "empty-query title must not end with whitespace; got {:?}",
            empty.title,
        );
    }

    /// Client ToolSearch's tool_result wire shape is an array of
    /// `{type: tool_reference, tool_name: "..."}` blocks - the
    /// generic `extract_text` walker filters those out (no `text`
    /// field) and the card body renders empty. A ToolSearch-aware
    /// branch in `build_tool_result_fields` should surface the
    /// matched tool names so the user sees what the search found
    /// without expanding to a raw schema dump.
    #[test]
    fn build_fields_client_tool_search_renders_compact_matched_tool_names() {
        let base = make_base("ToolSearch", &json!({"query": "select:Monitor,TaskStop"}));
        let raw_content = json!([
            {"type": "tool_reference", "tool_name": "Monitor"},
            {"type": "tool_reference", "tool_name": "TaskStop"},
        ]);
        let f = build_tool_result_fields(false, Some(&raw_content), Some(&base), None);
        let raw = f.raw_output.as_deref().expect("ToolSearch result must produce a raw_output");
        assert!(raw.contains("Monitor"), "raw_output must list Monitor; got {raw:?}");
        assert!(raw.contains("TaskStop"), "raw_output must list TaskStop; got {raw:?}");
        let Some(ToolCallContent::Content { content: ChunkContent::Text { text } }) =
            f.content.as_ref().and_then(|c| c.first())
        else {
            panic!("expected text content in ToolSearch card body, got: {:?}", f.content);
        };
        assert!(text.contains("Monitor") && text.contains("TaskStop"));
    }

    /// Defensive: a ToolSearch result with no tool_reference entries
    /// (empty matches) must not blow up. Fields stay set so the card
    /// reads as completed even with no body.
    #[test]
    fn build_fields_client_tool_search_handles_empty_matches() {
        let base = make_base("ToolSearch", &json!({"query": "select:Nothing"}));
        let raw_content = json!([]);
        let f = build_tool_result_fields(false, Some(&raw_content), Some(&base), None);
        assert_eq!(f.status, Some(forge_primitives::ToolCallStatus::Completed));
    }

    #[test]
    fn create_tool_call_locations_from_file_path() {
        let r = create_tool_call("tu", "Edit", &json!({"file_path": "/foo"}), None);
        assert_eq!(r.locations.len(), 1);
        assert_eq!(r.locations[0].path, std::path::PathBuf::from("/foo"));
    }

    #[test]
    fn edit_initial_content_is_diff() {
        let r = create_tool_call(
            "tu",
            "Edit",
            &json!({"file_path": "/f", "old_string": "a", "new_string": "b"}),
            None,
        );
        assert_eq!(r.content.len(), 1);
        let ToolCallContent::Diff { old, new, .. } = &r.content[0] else { panic!("expected diff") };
        assert_eq!(old, "a");
        assert_eq!(new, "b");
    }

    #[test]
    fn write_initial_content_is_full_diff() {
        let r =
            create_tool_call("tu", "Write", &json!({"file_path": "/f", "content": "hello"}), None);
        assert_eq!(r.content.len(), 1);
        let ToolCallContent::Diff { old, new, .. } = &r.content[0] else { panic!() };
        assert_eq!(old, "");
        assert_eq!(new, "hello");
    }

    #[test]
    fn extract_text_handles_string_array_object() {
        assert_eq!(extract_text(&json!("hi")), "hi");
        assert_eq!(
            extract_text(&json!([{"type":"text","text":"a"},{"type":"text","text":"b"}])),
            "a\nb"
        );
        assert_eq!(extract_text(&json!({"text":"o"})), "o");
        assert_eq!(extract_text(&json!(123)), "");
    }

    /// Bug #136: ExitPlanMode result is a JSON object whose plan body
    /// lives under "plan", with auxiliary fields like "allowedTools"
    /// alongside. `extract_text` historically returned "" for this
    /// shape, forcing the line-763 fallback to JSON-stringify the
    /// whole object (with literal `\n` escapes leaking into chat).
    /// Widen recognition to the conventional prose-field names.
    #[test]
    fn extract_text_widens_to_prose_carrying_object_fields() {
        assert_eq!(
            extract_text(&json!({"plan": "Step 1\nStep 2", "allowedTools": ["Bash"]})),
            "Step 1\nStep 2",
        );
        assert_eq!(extract_text(&json!({"description": "desc text"})), "desc text");
        assert_eq!(extract_text(&json!({"summary": "summary text"})), "summary text");
        assert_eq!(extract_text(&json!({"message": "message text"})), "message text");
    }

    /// Unrecognized JSON object (no prose-carrying field) returns "" -
    /// the caller path then refuses to dump the raw JSON (see
    /// `build_fields_does_not_json_dump_unrecognized_object`).
    #[test]
    fn extract_text_returns_empty_for_unrecognized_object() {
        let v = json!({"allowedTools": ["Bash"], "permissions": {"defaultBehavior": "ask"}});
        assert_eq!(extract_text(&v), "");
    }

    /// Bug #136 regression test: ExitPlanMode-shaped tool_use_result
    /// must render the plan body cleanly, not as raw-JSON-with-escapes.
    #[test]
    fn build_fields_extracts_plan_text_for_exit_plan_mode() {
        let base = make_base("ExitPlanMode", &json!({"plan": "..."}));
        let raw_content = json!({
            "plan": "Step 1: do X\nStep 2: do Y",
            "allowedTools": ["Bash", "Read"],
        });
        let f = build_tool_result_fields(false, Some(&raw_content), Some(&base), None);
        assert_eq!(f.raw_output.as_deref(), Some("Step 1: do X\nStep 2: do Y"));
        let Some(ToolCallContent::Content { content: ChunkContent::Text { text } }) =
            f.content.as_ref().and_then(|c| c.first())
        else {
            panic!("expected text content");
        };
        assert_eq!(text, "Step 1: do X\nStep 2: do Y");
    }

    /// For any other JSON-object-shaped result that carries no
    /// prose-bearing field, the fallback must NOT JSON-stringify the
    /// raw value into chat. Better to render an empty body than a
    /// literal-escape blob.
    #[test]
    fn build_fields_does_not_json_dump_unrecognized_object() {
        let base = make_base("ExitPlanMode", &json!({"plan": "..."}));
        let raw_content = json!({
            "allowedTools": ["Bash"],
            "permissions": {"defaultBehavior": "ask"},
        });
        let f = build_tool_result_fields(false, Some(&raw_content), Some(&base), None);
        assert!(
            f.raw_output.is_none(),
            "unrecognized JSON shape must not dump as raw_output, got: {:?}",
            f.raw_output
        );
        assert!(
            f.content.is_none(),
            "unrecognized JSON shape must not become content text, got: {:?}",
            f.content
        );
    }

    #[test]
    fn normalize_text_skips_persisted_preview_line() {
        let v = json!(
            "<persisted-output>\npreview (first 2kb):\n│ hello world\n│ second line\n</persisted-output>"
        );
        let out = normalize_tool_result_text(&v, false);
        assert_eq!(out, "hello world");
    }

    #[test]
    fn sanitize_user_rejected_text_collapses() {
        let v = json!(USER_REJECTED_TOOL_USE_EXACT);
        assert_eq!(normalize_tool_result_text(&v, true), "Cancelled by user.");

        let custom = format!("{USER_REJECTED_TOOL_USE_PREFIX} extra reason");
        let v2 = json!(custom);
        assert_eq!(normalize_tool_result_text(&v2, true), "Cancelled by user.");

        let pd = json!(PERMISSION_DENIED_TOOL_USE_EXACT);
        assert_eq!(normalize_tool_result_text(&pd, true), "Permission denied.");
    }

    #[test]
    fn build_fields_bash_extracts_stdout_stderr() {
        let base = make_base("Bash", &json!({"command":"echo"}));
        let raw_content =
            json!([{"type":"text","text":"<persisted-output>\n│ hello\n</persisted-output>"}]);
        let raw_result = json!({"stdout":"hello\n","stderr":"","interrupted":false});
        let f = build_tool_result_fields(false, Some(&raw_content), Some(&base), Some(&raw_result));
        assert_eq!(f.status, Some(forge_primitives::ToolCallStatus::Completed));
        assert_eq!(f.raw_output.as_deref(), Some("hello\n"));
        // generic content fallback wraps the bash output as text.
        let Some(ToolCallContent::Content { content: ChunkContent::Text { text } }) =
            f.content.as_ref().and_then(|c| c.first())
        else {
            panic!("expected text content");
        };
        assert!(text.contains("hello"));
    }

    #[test]
    fn build_fields_read_file_unchanged_shortcut() {
        let base = make_base("Read", &json!({"file_path": "/x"}));
        let raw_result = json!([{"type":"file_unchanged","file":{"filePath":"/x"}}]);
        let f = build_tool_result_fields(
            false,
            Some(&json!("ignored")),
            Some(&base),
            Some(&raw_result),
        );
        assert_eq!(f.raw_output.as_deref(), Some("File unchanged: /x"));
    }

    #[test]
    fn build_fields_write_emits_structured_diff() {
        let base = make_base("Write", &json!({"file_path":"/x","content":"new"}));
        let raw_content = json!([{"filePath":"/x","content":"new","originalFile":"old"}]);
        let f = build_tool_result_fields(false, Some(&raw_content), Some(&base), None);
        assert!(matches!(
            f.content.as_ref().and_then(|c| c.first()),
            Some(ToolCallContent::Diff { .. })
        ));
    }

    #[test]
    fn build_fields_agent_title_from_agent_type() {
        let base = make_base("Agent", &json!({}));
        let raw_result = json!([{"agentType":"researcher"}]);
        let f = build_tool_result_fields(false, Some(&json!("ok")), Some(&base), Some(&raw_result));
        assert_eq!(f.title.as_deref(), Some("researcher"));
    }

    #[test]
    fn build_fields_mcp_resource_structured() {
        let base = make_base("ReadMcpResource", &json!({"uri":"file:///x"}));
        let raw_content =
            json!({"contents":[{"uri":"file:///x","text":"hi","mimeType":"text/plain"}]});
        let f = build_tool_result_fields(false, Some(&raw_content), Some(&base), None);
        assert!(matches!(
            f.content.as_ref().and_then(|c| c.first()),
            Some(ToolCallContent::McpResource { .. })
        ));
    }

    #[test]
    fn build_fields_bash_output_metadata() {
        let base = make_base("Bash", &json!({"command":"sleep 30 &"}));
        let raw_result = json!({"backgroundTaskId":"bg1","assistantAutoBackgrounded":true});
        let f = build_tool_result_fields(
            false,
            Some(&json!("started")),
            Some(&base),
            Some(&raw_result),
        );
        let meta = f.output_metadata.expect("meta");
        assert_eq!(meta.bash.unwrap().assistant_auto_backgrounded, Some(true));
    }

    #[test]
    fn build_fields_agent_background_does_not_stamp_completed() {
        // A subagent the CLI backgrounds returns an immediate sentinel
        // tool_result carrying `backgroundTaskId` while it keeps
        // running. The card must not be stamped Completed mid-run;
        // liveness is tracked separately by the renderer's background-task
        // roster.
        let base = make_base("Agent", &json!({"subagent_type": "Explore"}));
        let raw_result = json!({"backgroundTaskId": "bg-agent-1"});
        let f = build_tool_result_fields(
            false,
            Some(&json!("Running in background with ID: bg-agent-1")),
            Some(&base),
            Some(&raw_result),
        );
        assert!(
            f.status.is_none(),
            "backgrounded Agent tool_result must not stamp a terminal status; got {:?}",
            f.status,
        );
    }

    #[test]
    fn unwrap_tool_use_result_envelopes() {
        let v = json!({"is_error": true, "content": "boom"});
        let u = unwrap_tool_use_result(&v);
        assert!(u.is_error);
        assert_eq!(u.content, json!("boom"));

        let v2 = json!({"result": "ok"});
        let u2 = unwrap_tool_use_result(&v2);
        assert!(!u2.is_error);
        assert_eq!(u2.content, json!("ok"));

        let v3 = json!("plain");
        let u3 = unwrap_tool_use_result(&v3);
        assert_eq!(u3.content, json!("plain"));
    }
}