spawn_subagent_tool.cpp

#include "spawn_subagent_tool.hpp"

#include "config/config.hpp"
#include "session/session_client.hpp"
#include "session_host/session_registry.hpp"
#include "skills/skill_init.hpp"
#include "skills/skill_registry.hpp"
#include "utils/encoding.hpp"
#include "utils/logger.hpp"
#include "skills/skill_command_expander.hpp"
#include "worktree/worktree_core.hpp"
#include "worktree/worktree_manager.hpp"

#include <chrono>
#include <sstream>
#include <thread>

namespace acecode {

namespace {

using nlohmann::json;

ToolResult error_result(const std::string& message) {
    ToolResult r;
    r.success = false;
    r.output = message;
    return r;
}

// 子代理工具的视觉摘要。作用有二:
//   1. 让工具结果带 tool_summary 落盘 —— resume/reload 时前端才能把这条
//      tool_result 重建成 kind:'tool' 项(否则 spawn 结果退化成灰色系统行,
//      「调用了 N 个智能体」分组就抓不到它)。
//   2. object 兜底子会话标题:前端优先用后台任务列表里的实时标题,拿不到时
//      退到这里的 prompt 摘要。
// icon="agent" 与前端后台任务面板的智能体语义对齐(前端分组不走 ToolBlock,
// 该图标仅在极端兜底渲染时可见)。
ToolSummary subagent_summary(const std::string& object_text) {
    ToolSummary s;
    s.icon = "agent";
    s.verb = "子代理";
    s.object = truncate_utf8_prefix(object_text, 80);
    return s;
}

// 从子会话的持久化消息里取最后一条非空 assistant 答复。
std::string last_assistant_text(SessionManager& sm) {
    auto messages = sm.load_active_messages();
    for (auto it = messages.rbegin(); it != messages.rend(); ++it) {
        if (it->role == "assistant" && !it->content.empty()) return it->content;
    }
    return {};
}

enum class WaitKind { Completed, Aborted, Timeout, Gone, ChildInterrupted, ChildFailed };

struct WaitOutcome {
    WaitKind    kind = WaitKind::Completed;
    std::string final_text;
    // ChildFailed:子会话回合的错误文案(AgentLoop::last_turn_error)。
    std::string error;
};

// 轮询等待子会话本轮结束。
//
// 完成判定的两个细节:
//   - send_input 是异步入队,worker 线程稍后才置 busy —— 只看 !is_busy()
//     会在"还没开始"时误判完成。观察到过 busy(observed_busy)后回落才算;
//     兜底:2 秒内从未观测到 busy(极快 turn 在轮询间隙内完成)时,以
//     "出现了新的 assistant 消息"为完成信号。
//   - 父会话 abort(用户 Esc / 停止按钮)→ 传播给子会话 loop->abort(),
//     但**不**销毁子会话:已产生的工作保留在侧栏里,用户可接管。
WaitOutcome wait_for_subagent(SessionRegistry& registry,
                              const std::string& session_id,
                              const std::atomic<bool>* abort_flag,
                              int timeout_seconds,
                              std::size_t baseline_message_count) {
    using clock = std::chrono::steady_clock;
    const auto started = clock::now();
    bool observed_busy = false;

    while (true) {
        if (abort_flag && abort_flag->load()) {
            if (auto entry = registry.acquire(session_id); entry && entry->loop) {
                entry->loop->abort();
            }
            return {WaitKind::Aborted, {}};
        }

        auto entry = registry.acquire(session_id);
        if (!entry || !entry->loop || !entry->sm) return {WaitKind::Gone, {}};

        const bool busy = entry->loop->is_busy();
        if (busy) observed_busy = true;

        const auto elapsed = clock::now() - started;
        if (!busy) {
            // 子会话在自己的回合结束后仍处于 abort 请求态(abort_requested_ 只在
            // 下次 submit 时清)→ 说明它是被中断的(如用户在后台任务面板点「中止」,
            // 或权限被中止),而非正常跑完。此时不能报 Completed/success,要给父会话
            // 一条明确的「被中断」信号,由父 agent loop 决定重派/换法/上报用户。
            const bool child_interrupted = entry->loop->is_aborting();
            const bool grace_passed = elapsed >= std::chrono::seconds(2);
            // 回合结束但不是正常跑完(provider 报错 / 上下文超限 / 空回复耗尽 /
            // max_iterations / hook 拦截)→ ChildFailed 而不是 Completed。曾经
            // 这里一律报 completed,父会话把子会话临终前的一句"Now let me read
            // ..."当成果,还以为任务做完了。
            auto finished = [&]() -> WaitOutcome {
                if (child_interrupted) {
                    return {WaitKind::ChildInterrupted, last_assistant_text(*entry->sm), {}};
                }
                if (entry->loop->last_turn_failed()) {
                    return {WaitKind::ChildFailed, last_assistant_text(*entry->sm),
                            entry->loop->last_turn_error()};
                }
                return {WaitKind::Completed, last_assistant_text(*entry->sm), {}};
            };
            if (observed_busy) {
                // 曾观测到运行、现已空闲 → 本轮结束。final_text 可能为空
                // (turn 失败或被 UI 中止),由调用方给出对应文案,不死等。
                return finished();
            }
            if (grace_passed) {
                // 从未观测到 busy:要么 turn 快到在轮询间隙内完成(有新消息 /
                // 已有失败结论),要么 submit 后压根没跑起来,要么在观测到 busy
                // 前就被中止。
                if (child_interrupted || entry->loop->last_turn_failed()) {
                    return finished();
                }
                if (entry->sm->load_active_messages().size() > baseline_message_count) {
                    return finished();
                }
                if (elapsed >= std::chrono::seconds(60)) {
                    return {WaitKind::Timeout, {}};
                }
            }
        }

        if (timeout_seconds > 0 &&
            elapsed >= std::chrono::seconds(timeout_seconds)) {
            return {WaitKind::Timeout, {}};
        }
        std::this_thread::sleep_for(std::chrono::milliseconds(250));
    }
}

// prompt 以 '/' 开头时按子会话 cwd 做 skill 命令展开(与 Web 输入框 /
// POST messages 同一套 try_expand_skill_command 语义)。
void expand_skill_prompt(const SubagentToolDeps& deps,
                         const std::string& cwd,
                         std::string& prompt,
                         std::string& display_text,
                         const SkillRegistry* session_skills = nullptr) {
    if (prompt.empty() || prompt[0] != '/' || !deps.config) return;
    SkillRegistry tmp;
    if (!session_skills) initialize_skill_registry(tmp, *deps.config, cwd);
    const SkillRegistry& skills = session_skills ? *session_skills : tmp;
    auto expansion = web::try_expand_skill_command(prompt, skills);
    if (expansion.expanded) {
        display_text = prompt;
        prompt = std::move(expansion.text);
    }
}

int parse_timeout_seconds(const json& args) {
    if (!args.contains("timeout_seconds")) return 0;
    if (args["timeout_seconds"].is_number_integer()) {
        int v = args["timeout_seconds"].get<int>();
        return v > 0 ? v : 0;
    }
    return 0;
}

ToolResult describe_wait_outcome(const WaitOutcome& outcome,
                                 const std::string& session_id) {
    ToolResult r;
    r.metadata["subagent_session_id"] = session_id;
    switch (outcome.kind) {
        case WaitKind::Completed:
            r.success = true;
            if (outcome.final_text.empty()) {
                r.output = "[subagent " + session_id +
                           "] finished without a final assistant reply "
                           "(possibly aborted from the UI).";
            } else {
                r.output = "[subagent " + session_id + " completed]\n\n" +
                           outcome.final_text;
            }
            return r;
        case WaitKind::Aborted:
            r.success = false;
            r.output = "[subagent " + session_id +
                       "] wait aborted; the subagent session was asked to stop "
                       "but is preserved in the session list.";
            return r;
        case WaitKind::ChildInterrupted:
            r.success = false;
            if (outcome.final_text.empty()) {
                r.output = "[subagent " + session_id +
                           "] was interrupted before finishing and produced no "
                           "final reply. Decide whether to retry it, continue "
                           "differently, or report the interruption to the user.";
            } else {
                r.output = "[subagent " + session_id +
                           "] was interrupted before finishing. Its partial "
                           "output follows; decide how to proceed:\n\n" +
                           outcome.final_text;
            }
            return r;
        case WaitKind::ChildFailed:
            r.success = false;
            r.output = "[subagent " + session_id + "] failed before finishing" +
                       (outcome.error.empty() ? std::string(".") : ": " + outcome.error);
            if (outcome.final_text.empty()) {
                r.output += "\nIt produced no usable final reply. Decide whether to retry "
                            "it, continue differently, or report the failure to the user.";
            } else {
                r.output += "\nIts last output follows; treat it as partial work, not a "
                            "completed result. Decide whether to retry it, continue "
                            "differently, or report the failure to the user:\n\n" +
                            outcome.final_text;
            }
            return r;
        case WaitKind::Timeout:
            r.success = false;
            r.output = "[subagent " + session_id +
                       "] still running after the timeout. It keeps running in "
                       "the background; call wait_subagent later with this "
                       "session_id to collect the result.";
            return r;
        case WaitKind::Gone:
        default:
            r.success = false;
            r.output = "[subagent " + session_id +
                       "] session no longer exists (destroyed).";
            return r;
    }
}

} // namespace

namespace {

// 子会话结束后对比主 checkout 的 git status:worktree 之外新出现的改动说明
// 有写入绕过了边界(bash 脚本 / 动态目标 —— 工具层守卫抓不到的那类),附进
// 父会话的工具结果里,让父代理当场知道,而不是等用户发现主仓脏了。并发的
// 子会话共享同一个主 checkout,这里只能说"在它运行期间出现",不能断言就
// 是它写的。基线随之前移,再次 wait 只报告新增的部分。
void append_workspace_watch_report(SessionRegistry& registry,
                                   const std::string& child_id,
                                   ToolResult& result) {
    auto entry = registry.acquire(child_id);
    if (!entry || entry->workspace_watch_cwd.empty()) return;
    auto after = worktree::list_status_lines(entry->workspace_watch_cwd);
    if (!after) return;
    const std::vector<std::string> touched =
        worktree::newly_changed_paths(entry->workspace_watch_baseline, *after);
    entry->workspace_watch_baseline = std::move(*after);
    if (touched.empty()) return;

    result.metadata["workspace_touched"] = touched;
    std::ostringstream oss;
    oss << "\n\nWARNING: the main checkout " << entry->workspace_watch_cwd
        << " changed while this subagent ran (" << touched.size()
        << " path(s)). These writes bypassed the worktree write boundary; verify "
           "them before trusting the result:";
    constexpr std::size_t kMaxListed = 20;
    for (std::size_t i = 0; i < touched.size(); ++i) {
        if (i == kMaxListed) {
            oss << "\n  ... (+" << (touched.size() - kMaxListed) << " more)";
            break;
        }
        oss << "\n  - " << touched[i];
    }
    result.output += oss.str();
    LOG_WARN("[subagent] " + child_id + " ran while the main checkout gained " +
             std::to_string(touched.size()) + " changed path(s) outside the worktree");
}

} // namespace

ToolImpl create_spawn_subagent_tool(std::shared_ptr<SubagentToolDeps> deps) {
    ToolImpl tool;
    tool.definition.name = "spawn_subagent";
    tool.definition.description =
        "Start a sub-agent in a NEW isolated session (its own context window, "
        "shown in this session's background-tasks panel). Use it to delegate a "
        "self-contained task without polluting the current context, or to kick "
        "off the next stage of a pipeline. The prompt may be a skill command like "
        "'/my-skill args'. With wait=true (default) this blocks until the "
        "sub-agent finishes its turn and returns its final reply; with "
        "wait=false it returns immediately with the new session_id "
        "(fire-and-forget; combine with wait_subagent to join later). "
        "Sub-agents cannot spawn further sub-agents.";
    tool.definition.parameters = json{
        {"type", "object"},
        {"properties", json{
            {"prompt", json{
                {"type", "string"},
                {"description", "First user message for the sub-agent session. "
                                "May be a '/skill-name args' command."}}},
            {"wait", json{
                {"type", "boolean"},
                {"description", "true (default): block until the sub-agent "
                                "finishes and return its final reply. false: "
                                "return immediately with the session_id."}}},
            {"model", json{
                {"type", "string"},
                {"description", "Optional saved model name for the sub-agent "
                                "session (defaults to the parent's current model)."}}},
            {"expert_member", json{
                {"type", "string"},
                {"description", "Optional selected expert ID from the current "
                                "team expert. Only a team lead may use it."}}},
            {"sampling", model_sampling_overrides_schema()},
            {"timeout_seconds", json{
                {"type", "integer"},
                {"description", "Optional wait timeout. 0 or omitted = wait "
                                "indefinitely (parent abort still cancels)."}}},
        }},
        {"required", json::array({"prompt"})},
    };
    // spawn 本身不触碰文件系统;子会话内部的危险操作由子会话自己的
    // PermissionManager 把关(权限模式继承父会话)。所以这里自动放行,
    // 避免流水线每次接力都弹确认。
    tool.is_read_only = true;

    tool.execute = [deps](const std::string& arguments_json,
                          const ToolContext& ctx) -> ToolResult {
        if (!deps || !deps->registry || !deps->client) {
            return error_result("spawn_subagent is only available in daemon mode.");
        }

        json args;
        try {
            args = json::parse(arguments_json);
        } catch (const std::exception& e) {
            return error_result(std::string("invalid arguments: ") + e.what());
        }
        const std::string prompt =
            args.contains("prompt") && args["prompt"].is_string()
                ? args["prompt"].get<std::string>() : std::string{};
        if (prompt.empty()) return error_result("prompt is required");
        const bool wait =
            !args.contains("wait") || !args["wait"].is_boolean() ||
            args["wait"].get<bool>();
        const std::string model_name =
            args.contains("model") && args["model"].is_string()
                ? args["model"].get<std::string>() : std::string{};
        const std::string expert_member =
            args.contains("expert_member") && args["expert_member"].is_string()
                ? args["expert_member"].get<std::string>() : std::string{};
        const int timeout_seconds = parse_timeout_seconds(args);
        std::optional<ModelSamplingOptions> sampling;
        if (args.contains("sampling")) {
            std::string error;
            sampling = parse_model_sampling_overrides(args["sampling"], error);
            if (!sampling) return error_result(error);
        }

        // 深度限制:子代理不能再派生。父会话 id 从注入的 SessionManager 拿。
        std::string parent_id;
        if (ctx.session_manager) parent_id = ctx.session_manager->current_session_id();
        std::string parent_permission_mode;
        bool parent_in_registry = false;
        std::shared_ptr<SessionEntry> parent_entry;
        if (!parent_id.empty()) {
            if (auto parent = deps->registry->acquire(parent_id)) {
                parent_entry = parent;
                parent_in_registry = true;
                if (parent->subagent_depth >= 1) {
                    return error_result(
                        "sub-agents cannot spawn further sub-agents");
                }
                if (parent->perm) {
                    parent_permission_mode =
                        PermissionManager::mode_name(parent->perm->mode());
                }
            }
        }
        if (!expert_member.empty()) {
            if (!parent_entry || !parent_entry->expert ||
                parent_entry->expert->type != ExpertType::Team ||
                !parent_entry->expert_member_id.empty()) {
                return error_result(
                    "expert_member is only available to a team expert lead");
            }
            if (!parent_entry->expert->is_declared_member(expert_member)) {
                return error_result("expert is not selected for this team: " +
                                    expert_member);
            }
        }
        if (!parent_in_registry && deps->fallback_permissions) {
            // TUI 主会话不在 registry 里:权限模式从进程级 PermissionManager
            // 继承(与 daemon 的父会话继承语义一致)。
            parent_permission_mode = PermissionManager::mode_name(
                deps->fallback_permissions->mode());
        }

        // 父会话在 worktree 里时,子会话共享同一个 worktree:身份(inherited)
        // 进子会话 meta,AgentLoop cwd 由 registry 切进 worktree;而 opts.cwd
        // 传父会话进 worktree 前的 workspace cwd,让子会话与父会话落在同一个
        // project dir —— 否则「后台任务」面板按父会话 cwd 扫盘找不到已结束的
        // 子任务。父会话的写边界(worktree / LOOP)一并透传,子会话在 Yolo 下
        // 才不会裸奔到主 checkout 里写东西。
        WorktreeSessionInfo parent_worktree;
        if (ctx.session_manager) {
            parent_worktree = ctx.session_manager->active_worktree();
        }
        SessionOptions opts;
        opts.cwd = ctx.cwd;
        if (parent_worktree.active()) {
            opts.inherited_worktree = parent_worktree;
            if (!parent_worktree.original_cwd.empty()) {
                opts.cwd = parent_worktree.original_cwd;
            }
        }
        opts.write_root = ctx.write_root;
        if (parent_entry && parent_entry->loop_execution) {
            // LOOP 运行派生的子会话仍属于这次 run:继承执行策略(写边界 +
            // <loop-execution> 系统上下文)与 run 身份。
            opts.loop_execution = true;
            opts.loop_id = parent_entry->loop_id;
            opts.loop_run_id = parent_entry->loop_run_id;
            if (parent_entry->loop) {
                opts.loop_system_context =
                    parent_entry->loop->loop_execution_policy().system_context;
            }
        }
        opts.model_name = model_name;
        opts.sampling = sampling;
        if (opts.model_name.empty() && ctx.session_manager) {
            // Read the live parent selection, including TUI parents outside the
            // registry. An empty preset preserves the configured fallback.
            opts.model_name = ctx.session_manager->current_model_preset();
        }
        opts.permission_mode = parent_permission_mode;
        opts.subagent_depth = 1;
        // 父会话 id 持久化到子会话 meta:子会话从常规列表隐藏,归入父会话
        // 的「后台任务」面板;daemon 重启后依然识别为后台任务。
        opts.parent_session_id = parent_id;
        if (!expert_member.empty()) {
            opts.expert_id = parent_entry->expert_id;
            opts.expert_member_id = expert_member;
        }

        std::string child_id;
        try {
            child_id = deps->registry->create(opts);
        } catch (const std::exception& e) {
            return error_result(std::string("failed to create subagent session: ") +
                                e.what());
        }
        if (child_id.empty()) {
            return error_result("failed to create subagent session");
        }
        if (parent_worktree.active() && !parent_worktree.original_cwd.empty()) {
            // 主 checkout 快照:读不到(非仓库 / git 缺失)就不监视,空基线会把
            // 整仓的脏文件都报成子会话写的。
            if (auto child = deps->registry->acquire(child_id)) {
                if (auto status = worktree::list_status_lines(parent_worktree.original_cwd)) {
                    child->workspace_watch_cwd = parent_worktree.original_cwd;
                    child->workspace_watch_baseline = std::move(*status);
                }
            }
        }

        std::size_t baseline = 0;
        if (auto child = deps->registry->acquire(child_id); child && child->sm) {
            baseline = child->sm->load_active_messages().size();
        }

        std::string send_text = prompt;
        std::string display_text;
        const SkillRegistry* child_skills = nullptr;
        if (auto child = deps->registry->acquire(child_id)) {
            child_skills = child->skill_registry.get();
        }
        expand_skill_prompt(*deps, ctx.cwd, send_text, display_text, child_skills);
        if (deps->on_spawn) {
            deps->on_spawn(child_id, prompt);
        }
        if (!deps->client->send_input(child_id, send_text, display_text)) {
            return error_result("failed to send prompt to subagent session " +
                                child_id);
        }
        LOG_INFO("[subagent] spawned session " + child_id + " (wait=" +
                 (wait ? std::string("true") : std::string("false")) + ")");

        if (!wait) {
            ToolResult r;
            r.success = true;
            r.metadata["subagent_session_id"] = child_id;
            r.summary = subagent_summary(prompt);
            r.output = "Subagent session started: " + child_id +
                       "\nIt runs in its own isolated session (shown in the "
                       "background-tasks panel). Use wait_subagent with this "
                       "session_id if you need its result later.";
            return r;
        }

        auto outcome = wait_for_subagent(*deps->registry, child_id,
                                         ctx.abort_flag, timeout_seconds,
                                         baseline);
        ToolResult r = describe_wait_outcome(outcome, child_id);
        append_workspace_watch_report(*deps->registry, child_id, r);
        r.summary = subagent_summary(prompt);
        return r;
    };
    return tool;
}

ToolImpl create_wait_subagent_tool(std::shared_ptr<SubagentToolDeps> deps) {
    ToolImpl tool;
    tool.definition.name = "wait_subagent";
    tool.definition.description =
        "Wait for a sub-agent session (started earlier with spawn_subagent "
        "wait=false) to finish its current turn, then return its latest reply. "
        "Use after fanning out several sub-agents in parallel.";
    tool.definition.parameters = json{
        {"type", "object"},
        {"properties", json{
            {"session_id", json{
                {"type", "string"},
                {"description", "The subagent session id returned by spawn_subagent."}}},
            {"timeout_seconds", json{
                {"type", "integer"},
                {"description", "Optional timeout. 0 or omitted = wait indefinitely."}}},
        }},
        {"required", json::array({"session_id"})},
    };
    tool.is_read_only = true;

    tool.execute = [deps](const std::string& arguments_json,
                          const ToolContext& ctx) -> ToolResult {
        if (!deps || !deps->registry) {
            return error_result("wait_subagent is only available in daemon mode.");
        }
        json args;
        try {
            args = json::parse(arguments_json);
        } catch (const std::exception& e) {
            return error_result(std::string("invalid arguments: ") + e.what());
        }
        const std::string session_id =
            args.contains("session_id") && args["session_id"].is_string()
                ? args["session_id"].get<std::string>() : std::string{};
        if (session_id.empty()) return error_result("session_id is required");
        if (!deps->registry->acquire(session_id)) {
            return error_result("unknown session: " + session_id);
        }
        const int timeout_seconds = parse_timeout_seconds(args);

        // baseline=0:wait_subagent 语义是"取最新答复",只要存在 assistant
        // 消息即可返回,不要求本次调用之后新产生。
        auto outcome = wait_for_subagent(*deps->registry, session_id,
                                         ctx.abort_flag, timeout_seconds,
                                         /*baseline_message_count=*/0);
        ToolResult r = describe_wait_outcome(outcome, session_id);
        append_workspace_watch_report(*deps->registry, session_id, r);
        // object 留空:等待某个已知子会话,标题由前端从后台任务列表解析。
        r.summary = subagent_summary("");
        return r;
    };
    return tool;
}

} // namespace acecode