engine.cpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
#include <entropic/core/engine.h>
#include <entropic/core/delegation.h>
#include <entropic/core/delegate_hook_payload.h>
#include <entropic/core/sandbox.h>
#include <entropic/mcp/utf8_sanitize.h>
#include <entropic/types/logging.h>
#include <entropic/types/tool_result.h>
 
#include <nlohmann/json.hpp>
 
#include <algorithm>
#include <array>
#include <chrono>
#include <sstream>
 
static auto logger = entropic::log::get("core.engine");
 
namespace entropic {
 
// ── Hook dispatch helpers ────────────────────────────────
 
static void fire_hook_info(const HookInterface& hooks,
                           entropic_hook_point_t point,
                           const char* json) {
    if (hooks.fire_info != nullptr) {
        hooks.fire_info(hooks.registry, point, json);
    }
}
 
static void fire_loop_start_hook(const HookInterface& hooks,
                                 const LoopContext& ctx) {
    std::string json = "{\"message_count\":"
        + std::to_string(ctx.messages.size())
        + ",\"delegation_depth\":"
        + std::to_string(ctx.delegation_depth) + "}";
    fire_hook_info(hooks, ENTROPIC_HOOK_ON_LOOP_START, json.c_str());
}
 
static void fire_loop_end_hook(const HookInterface& hooks,
                               const LoopContext& ctx) {
    std::string json = "{\"final_state\":\""
        + std::string(agent_state_name(ctx.state))
        + "\",\"iterations\":"
        + std::to_string(ctx.metrics.iterations) + "}";
    fire_hook_info(hooks, ENTROPIC_HOOK_ON_LOOP_END, json.c_str());
}
 
static void fire_loop_iteration_hook(const HookInterface& hooks,
                                     const LoopContext& ctx) {
    std::string json = "{\"iteration\":"
        + std::to_string(ctx.metrics.iterations)
        + ",\"state\":\"" + agent_state_name(ctx.state)
        + "\",\"consecutive_errors\":"
        + std::to_string(ctx.consecutive_errors) + "}";
    fire_hook_info(hooks, ENTROPIC_HOOK_ON_LOOP_ITERATION, json.c_str());
}
 
static void fire_context_assemble_hook(const HookInterface& hooks,
                                       const LoopContext& ctx) {
    std::string json = "{\"message_count\":"
        + std::to_string(ctx.messages.size()) + "}";
    fire_hook_info(hooks, ENTROPIC_HOOK_ON_CONTEXT_ASSEMBLE,
                   json.c_str());
}
 
// Forward declaration
static void remove_anchor_messages(LoopContext& ctx,
                                    const std::string& key);
 
static double now_seconds() {
    auto now = std::chrono::steady_clock::now();
    auto dur = now.time_since_epoch();
    auto ms = std::chrono::duration_cast<
        std::chrono::milliseconds>(dur);
    return static_cast<double>(ms.count()) / 1000.0;
}
 
AgentEngine::AgentEngine(
    const InferenceInterface& inference,
    const LoopConfig& loop_config,
    const CompactionConfig& compaction_config)
    : inference_(inference),
      loop_config_(loop_config),
      token_counter_(loop_config.context_length),
      compaction_manager_(compaction_config, token_counter_),
      context_manager_(
          compaction_manager_, callbacks_,
          ContextManagerHooks{
              [this](LoopContext& ctx) { reinject_context_anchors(ctx); }
          }),
      response_generator_(
          inference, loop_config, callbacks_,
          GenerationEvents{&interrupt_flag_, &pause_flag_}) {
    register_directive_handlers();
}
 
void AgentEngine::set_callbacks(const EngineCallbacks& callbacks) {
    callbacks_ = callbacks;
}
 
void AgentEngine::set_tool_executor(
    const ToolExecutionInterface& tool_exec) {
    tool_exec_ = tool_exec;
}
 
void AgentEngine::set_tier_resolution(
    const TierResolutionInterface& tier_res) {
    tier_res_ = tier_res;
}
 
void AgentEngine::set_storage(const StorageInterface& storage) {
    storage_ = storage;
    compaction_manager_.set_storage(&storage_);
}
 
void AgentEngine::set_hooks(const HookInterface& hooks) {
    hooks_ = hooks;
    response_generator_.set_hooks(hooks);
    context_manager_.set_hooks(hooks);
    directive_processor_.set_hooks(hooks);
}
 
void AgentEngine::set_stream_observer(
    TokenCallback observer, void* user_data) {
    response_generator_.set_stream_observer(observer, user_data);
}
 
void AgentEngine::set_delegation_callbacks(
    ent_decision_t (*on_start)(const ent_delegation_request_t*, void*),
    ent_decision_t (*on_complete)(const ent_delegation_result_t*, void*),
    void* user_data) {
    std::lock_guard<std::mutex> lock(delegation_cb_mutex_);
    delegation_cb_.start = on_start;
    delegation_cb_.complete = on_complete;
    delegation_cb_.user_data = user_data;
}
 
AgentEngine::DelegationCallbacks
AgentEngine::delegation_callbacks_snapshot() const {
    std::lock_guard<std::mutex> lock(delegation_cb_mutex_);
    return delegation_cb_;
}
 
void AgentEngine::set_validation_provider(
    char* (*provider)(void*), void* user_data) {
    validation_provider_ = provider;
    validation_provider_data_ = user_data;
}
 
const TierResolutionInterface& AgentEngine::tier_resolution() const {
    return tier_res_;
}
 
void AgentEngine::apply_identity_overrides(LoopContext& ctx) {
    if (ctx.locked_tier.empty() || tier_res_.get_tier_param == nullptr) {
        return;
    }
    auto mi = tier_res_.get_tier_param(
        ctx.locked_tier, "max_iterations", tier_res_.user_data);
    if (!mi.empty()) {
        ctx.effective_max_iterations = std::atoi(mi.c_str());
        logger->info("[override] tier={} max_iterations={}",
                     ctx.locked_tier, ctx.effective_max_iterations);
    }
    auto mt = tier_res_.get_tier_param(
        ctx.locked_tier, "max_tool_calls_per_turn", tier_res_.user_data);
    if (!mt.empty()) {
        ctx.effective_max_tool_calls_per_turn = std::atoi(mt.c_str());
        logger->info("[override] tier={} max_tool_calls_per_turn={}",
                     ctx.locked_tier, ctx.effective_max_tool_calls_per_turn);
    }
}
 
int AgentEngine::resolve_max_iterations(const LoopContext& ctx) const {
    return ctx.effective_max_iterations >= 0
        ? ctx.effective_max_iterations
        : loop_config_.max_iterations;
}
 
int AgentEngine::resolve_max_tool_calls(const LoopContext& ctx) const {
    return ctx.effective_max_tool_calls_per_turn >= 0
        ? ctx.effective_max_tool_calls_per_turn
        : loop_config_.max_tool_calls_per_turn;
}
 
void AgentEngine::run_loop(LoopContext& ctx, bool inherit_interrupt) {
    // gh#81 (v2.4.3): child delegation loops inherit the parent's
    // interrupt state — clearing it here would swallow a parent
    // interrupt raised just before the child was dispatched. Only a
    // fresh top-level turn resets.
    if (!inherit_interrupt) {
        reset_interrupt();
        pause_flag_.store(false);
    }
    apply_identity_overrides(ctx);
    reinject_context_anchors(ctx);
    if (ctx.metrics.start_time == 0.0) {
        ctx.metrics.start_time = now_seconds();
    }
    set_state(ctx, AgentState::PLANNING);
    loop(ctx);
    ctx.metrics.end_time = now_seconds();
    // Per-tier accumulator (P2-15 follow-up, 2.0.6-rc16.2)
    auto& tm = per_tier_metrics_[
        ctx.locked_tier.empty() ? "lead" : ctx.locked_tier];
    tm.iterations  += ctx.metrics.iterations;
    tm.tool_calls  += ctx.metrics.tool_calls;
    tm.tokens_used += ctx.metrics.tokens_used;
    tm.errors      += ctx.metrics.errors;
    tm.end_time    += (ctx.metrics.end_time - ctx.metrics.start_time);
}
 
std::vector<Message> AgentEngine::run(std::vector<Message> messages,
                                      const std::string& tier_override) {
    // gh#35: update activity timestamp at run() entry so any host
    // polling `seconds_since_last_activity` for an idle-exit policy
    // sees a fresh value as soon as work begins.
    last_activity_epoch_s_.store(
        std::chrono::duration_cast<std::chrono::seconds>(
            std::chrono::system_clock::now().time_since_epoch()).count());
 
    LoopContext ctx;
    ctx.messages = std::move(messages);
    ctx.locked_tier = tier_override;  // gh#99: "" routes; non-empty locks
    ctx.metrics.start_time = now_seconds();
 
    init_session_conversation(ctx);
 
    reset_interrupt();
    pause_flag_.store(false);
 
    reinject_context_anchors(ctx);
    set_state(ctx, AgentState::PLANNING);
 
    loop(ctx);
 
    ctx.metrics.end_time = now_seconds();
    accumulate_run_metrics(ctx);
    logger->info("Loop complete: {} iterations, {}ms",
                 ctx.metrics.iterations, ctx.metrics.duration_ms());
    return ctx.messages;
}
 
void AgentEngine::init_session_conversation(LoopContext& ctx) {
    // gh#48 (v2.1.12): create the root conversation row when storage
    // is wired so `ctx.conversation_id` carries a valid FK into
    // `conversations(id)`. Every downstream delegation copies
    // `parent_ctx.conversation_id` into `child_ctx.parent_conversation_id`
    // (`delegation.cpp:387`); without this, the empty string propagates
    // and every `INSERT INTO delegations` violates the FK silently,
    // making `entropic.followup` return empty across an entire session.
    if (storage_.create_conversation == nullptr) { return; }
    std::string conv_id;
    if (storage_.create_conversation("session", conv_id, storage_.user_data)
        && !conv_id.empty()) {
        ctx.conversation_id = std::move(conv_id);
    } else {
        logger->warn("Storage create_conversation failed at run() init; "
                     "delegations will not persist this session (gh#48)");
    }
}
 
void AgentEngine::accumulate_run_metrics(LoopContext& ctx) {
    last_metrics_ = ctx.metrics;  // P2-15: snapshot for entropic_status
    // Per-tier accumulator (P2-15 follow-up, 2.0.6-rc16.2)
    auto& tm = per_tier_metrics_[
        ctx.locked_tier.empty() ? "lead" : ctx.locked_tier];
    tm.iterations  += ctx.metrics.iterations;
    tm.tool_calls  += ctx.metrics.tool_calls;
    tm.tokens_used += ctx.metrics.tokens_used;
    tm.errors      += ctx.metrics.errors;
    tm.end_time    += (ctx.metrics.end_time - ctx.metrics.start_time);
}
 
void AgentEngine::loop(LoopContext& ctx) {
    fire_loop_start_hook(hooks_, ctx);  // ON_LOOP_START (v1.9.1)
 
    while (!should_stop(ctx)) {
        ctx.metrics.iterations++;
 
        if (interrupt_flag_.load()) {
            set_state(ctx, AgentState::INTERRUPTED);
            break;
        }
 
        execute_iteration(ctx);
 
        if (ctx.state == AgentState::ERROR) {
            break;
        }
    }
 
    if (ctx.metrics.iterations >= resolve_max_iterations(ctx)
        && !is_terminal_state(ctx)) {
        // P3-18 follow-up (2.0.6-rc16.2): force synthetic completion
        // so the facade returns a proper result when the cap is hit.
        // E7 (2.0.6-rc18): mark ctx.metadata with the terminal reason
        // so delegate result and parent-tier relay can surface that
        // the child did not complete naturally.
        logger->warn("Loop ended due to max iterations ({}/{}) — "
                     "forcing synthetic entropic.complete",
                     ctx.metrics.iterations, resolve_max_iterations(ctx));
        Message forced;
        forced.role = "assistant";
        forced.content = "[iteration cap reached after "
            + std::to_string(ctx.metrics.iterations)
            + " iterations — returning current state]";
        ctx.messages.push_back(std::move(forced));
        ctx.metadata["terminal_reason"] = "budget_exhausted";
        set_state(ctx, AgentState::COMPLETE);
    }
 
    fire_loop_end_hook(hooks_, ctx);  // ON_LOOP_END (v1.9.1)
}
 
void AgentEngine::execute_iteration(LoopContext& ctx) {
    logger->info("[LOOP] iter {}/{} state={} msgs={}",
                 ctx.metrics.iterations,
                 resolve_max_iterations(ctx),
                 agent_state_name(ctx.state),
                 ctx.messages.size());
 
    fire_loop_iteration_hook(hooks_, ctx);  // ON_LOOP_ITERATION (v1.9.1)
 
    context_manager_.refresh_context_limit(ctx, 0);
    context_manager_.prune_old_tool_results(ctx);
    context_manager_.check_compaction(ctx);
 
    fire_context_assemble_hook(hooks_, ctx);  // ON_CONTEXT_ASSEMBLE (v1.9.1)
 
    set_state(ctx, AgentState::EXECUTING);
 
    // Hook: PRE_GENERATE — can cancel (v1.9.1)
    if (fire_pre_hook(ENTROPIC_HOOK_PRE_GENERATE, ctx.metrics.iterations)) {
        set_state(ctx, AgentState::COMPLETE);
        return;
    }
 
    auto result = response_generator_.generate_response(ctx);
    dispatch_post_generate(ctx, result);
    process_generation_result(ctx, result);
}
 
void AgentEngine::process_generation_result(LoopContext& ctx,
                                            GenerateResult& result) {
    auto [cleaned, tool_calls] = parse_tool_calls(result.content);
    logger->info("[ITER] finish={}, {} tool call(s), {} chars",
                 result.finish_reason, tool_calls.size(),
                 cleaned.size());
    Message assistant_msg{"assistant", cleaned};
    ctx.messages.push_back(std::move(assistant_msg));
 
    bool made_tool_call =
        !tool_calls.empty() && tool_exec_.process_tool_calls != nullptr;
    // gh#84 (v2.5.1): the budget resets on genuine progress, not on a
    // merely-parsed call — process_tool_results reports whether any
    // tool actually executed (ok / ok_empty).
    bool made_progress = false;
    if (made_tool_call) {
        made_progress = process_tool_results(ctx, tool_calls);
        // gh#123: reset retry counter so a genuine tool call clears prior
        // consecutive-empty-turn debt.
        if (made_progress) {
            ctx.metadata["zero_tool_call_retries"] = "0";
        }
    } else {
        evaluate_no_tool_decision(ctx, cleaned, result.finish_reason);
    }
 
    // gh#80 (v2.5.0): charge the thinking budget before dispatch so a
    // budget-triggered terminal is honored by dispatch_pending_or_halt.
    charge_thinking_budget(ctx, result.content.size(), made_progress);
 
    dispatch_pending_or_halt(ctx);
}
 
void AgentEngine::charge_thinking_budget(
    LoopContext& ctx, size_t content_len, bool made_tool_call) {
    if (loop_config_.budget_mode == BudgetMode::off) { return; }
 
    // A tool call is productive action — reset the window and the
    // nudge latch so the model earns a fresh thinking allowance.
    if (made_tool_call) {
        ctx.budget_tokens_since_tool = 0;
        ctx.budget_window_start_s = 0.0;
        ctx.budget_completion_nudged = false;
        return;
    }
 
    int units = budget_units_consumed(ctx, content_len);
    if (units < loop_config_.budget_limit) { return; }
 
    if (!ctx.budget_completion_nudged) {
        nudge_budget_completion(ctx);
    } else {
        hard_cut_budget(ctx);
    }
}
 
int AgentEngine::budget_units_consumed(LoopContext& ctx, size_t content_len) {
    if (loop_config_.budget_mode == BudgetMode::tokens) {
        // Estimate generated tokens from content length — the
        // function-pointer inference ABI doesn't thread an exact count
        // back. ~4 chars/token; content includes <think> blocks, which
        // is exactly the deliberation we want to charge.
        constexpr size_t kCharsPerToken = 4;
        ctx.budget_tokens_since_tool +=
            static_cast<int>(content_len / kCharsPerToken);
        return ctx.budget_tokens_since_tool;
    }
    // wall_clock
    if (ctx.budget_window_start_s == 0.0) {
        ctx.budget_window_start_s = now_seconds();
    }
    return static_cast<int>(now_seconds() - ctx.budget_window_start_s);
}
 
void AgentEngine::nudge_budget_completion(LoopContext& ctx) {
    ctx.budget_completion_nudged = true;
    ctx.budget_tokens_since_tool = 0;
    ctx.budget_window_start_s =
        (loop_config_.budget_mode == BudgetMode::wall_clock)
            ? now_seconds() : 0.0;
    logger->warn("[BUDGET] thinking budget reached ({} {}); nudging completion",
                 loop_config_.budget_limit,
                 loop_config_.budget_mode == BudgetMode::tokens
                     ? "tokens" : "seconds");
    Message nudge{"user",
        "[engine] thinking budget reached — emit entropic.complete now "
        "with your best current answer. Further deliberation without a "
        "tool call will be cut off."};
    ctx.messages.push_back(std::move(nudge));
}
 
void AgentEngine::hard_cut_budget(LoopContext& ctx) {
    logger->warn("[BUDGET] thinking budget exhausted after nudge — "
                 "hard-cutting turn");
    Message cut{"assistant",
        "[thinking budget exhausted — the turn was hard-cut after the "
        "completion nudge went unheeded; no tool call was emitted]"};
    ctx.messages.push_back(std::move(cut));
    ctx.metadata["terminal_reason"] = "budget_exhausted_thinking";
    set_state(ctx, AgentState::COMPLETE);
}
 
void AgentEngine::dispatch_pending_or_halt(LoopContext& ctx) {
    if (interrupt_flag_.load() && !is_terminal_state(ctx)) {
        logger->info("[ITER] interrupt observed during tool processing — "
                     "halting before pending dispatch");
        set_state(ctx, AgentState::INTERRUPTED);
        return;
    }
 
    if (is_terminal_state(ctx)) {
        if (ctx.pending_delegation.has_value()
         || ctx.pending_pipeline.has_value()) {
            logger->info("[ITER] terminal state reached during batch "
                         "tool processing — dropping pending {}",
                         ctx.pending_delegation.has_value()
                             ? "delegation" : "pipeline");
        }
        return;
    }
 
    if (ctx.pending_delegation.has_value()) {
        ctx.metrics.iterations--;
        execute_pending_delegation(ctx);
    } else if (ctx.pending_pipeline.has_value()) {
        ctx.metrics.iterations--;
        execute_pending_pipeline(ctx);
    }
}
 
void AgentEngine::evaluate_no_tool_decision(
    LoopContext& ctx,
    const std::string& content,
    const std::string& finish_reason) {
    if (handle_terminal_finish_reasons(ctx, finish_reason)) { return; }
    if (try_auto_chain(ctx, finish_reason, content)) {
        logger->info("[DECISION] auto-chain triggered");
        return;
    }
    if (record_explicit_completion_failure(ctx, finish_reason)) { return; }
    if (response_generator_.is_response_complete(content, "[]")) {
        logger->info("[DECISION] response complete");
        set_state(ctx, AgentState::COMPLETE);
    }
}
 
bool AgentEngine::handle_terminal_finish_reasons(
    LoopContext& ctx, const std::string& finish_reason) {
    if (finish_reason == "interrupted") {
        logger->info("[DECISION] interrupted");
        set_state(ctx, AgentState::INTERRUPTED);
        return true;
    }
    if (finish_reason == "length") {
        logger->info("[DECISION] length, continuing");
        return true;
    }
    return false;
}
 
bool AgentEngine::record_explicit_completion_failure(
    LoopContext& ctx, const std::string& finish_reason) {
    if (!tier_requires_explicit_completion(ctx.locked_tier)) {
        return false;
    }
    auto& retries = ctx.metadata["zero_tool_call_retries"];
    int n = retries.empty() ? 0 : std::atoi(retries.c_str());
    // gh#123: default 3; per-tier override via max_consecutive_empty_turns
    int ceiling = 3;
    if (tier_res_.get_tier_param != nullptr) {
        auto cv = tier_res_.get_tier_param(
            ctx.locked_tier, "max_consecutive_empty_turns",
            tier_res_.user_data);
        if (!cv.empty()) { ceiling = std::atoi(cv.c_str()); }
    }
    if (n >= ceiling) {
        // Allowance exhausted — this is a genuine failure.
        ctx.metadata["failure_reason"] =
            "zero_tool_calls_with_explicit_completion";
        ctx.metadata["failure_tier"] = ctx.locked_tier;
        logger->error("[DECISION] empty-turn allowance exhausted "
                      "(tier={}, n={}/{}), failing turn",
                      ctx.locked_tier, n, ceiling);
        set_state(ctx, AgentState::ERROR);
        return true;
    }
    // Reasoning turn — nudge toward action, not a failure yet.
    logger->info("[DECISION] tier '{}' empty turn {}/{} "
                 "(finish_reason={}), nudging toward action",
                 ctx.locked_tier, n + 1, ceiling, finish_reason);
    std::string tools_hint =
        "(entropic.complete, entropic.delegate, or entropic.inspect)";
    if (tier_res_.get_tier_param != nullptr) {
        auto allowed = tier_res_.get_tier_param(
            ctx.locked_tier, "allowed_tools", tier_res_.user_data);
        if (!allowed.empty()) { tools_hint = "(" + allowed + ")"; }
    }
    Message correction;
    correction.role = "user";
    correction.content =
        "[SYSTEM] Your previous response contained no tool call. "
        "You must end every turn with exactly one tool call "
        + tools_hint + ". Retry.";
    ctx.messages.push_back(std::move(correction));
    retries = std::to_string(n + 1);
    set_state(ctx, AgentState::EXECUTING);
    return true;
}
 
bool AgentEngine::tier_requires_explicit_completion(
    const std::string& tier) const {
    if (tier_res_.get_tier_param == nullptr) { return false; }
    auto val = tier_res_.get_tier_param(
        tier, "explicit_completion", tier_res_.user_data);
    return val == "true" || val == "1";
}
 
bool AgentEngine::is_delegation_cycle(
    const LoopContext& ctx, const std::string& target) const {
    if (target == ctx.locked_tier) { return true; }
    for (const auto& anc : ctx.delegation_ancestor_tiers) {
        if (anc == target) { return true; }
    }
    return false;
}
 
bool AgentEngine::is_delegation_repeat_blocked(
    const LoopContext& ctx, const std::string& target) const {
    return target == ctx.last_failed_delegation_target
        && ctx.consecutive_failed_delegations
               >= loop_config_.max_consecutive_failed_delegations;
}
 
bool AgentEngine::fold_complete_into_assistant(
    LoopContext& ctx, const Message& tool_result_msg) const {
    auto tn_it = tool_result_msg.metadata.find("tool_name");
    bool is_complete = tn_it != tool_result_msg.metadata.end()
        && tn_it->second == "entropic.complete";
    if (!is_complete || ctx.messages.empty()) { return false; }
    auto& last = ctx.messages.back();
    auto sum_it = ctx.metadata.find("explicit_completion_summary");
    bool foldable = last.role == "assistant" && last.content.empty()
        && sum_it != ctx.metadata.end();
    if (!foldable) { return false; }
    last.content = sum_it->second;
    return true;
}
 
int64_t AgentEngine::seconds_since_last_activity() const {
    auto last = last_activity_epoch_s_.load();
    if (last == 0) { return 0; }
    auto now = std::chrono::duration_cast<std::chrono::seconds>(
        std::chrono::system_clock::now().time_since_epoch()).count();
    return now > last ? (now - last) : 0;
}
 
bool AgentEngine::should_stop(const LoopContext& ctx) const {
    bool at_limit = ctx.metrics.iterations >= resolve_max_iterations(ctx)
                 || ctx.consecutive_duplicate_attempts >= 3;
    return is_terminal_state(ctx) || at_limit;
}
 
bool AgentEngine::is_terminal_state(const LoopContext& ctx) {
    return ctx.state == AgentState::COMPLETE
        || ctx.state == AgentState::ERROR
        || ctx.state == AgentState::INTERRUPTED;
}
 
void AgentEngine::set_state(LoopContext& ctx, AgentState state) {
    auto prev = ctx.state;
    ctx.state = state;
    logger->info("State: {}", agent_state_name(state));
    if (callbacks_.on_state_change != nullptr) {
        callbacks_.on_state_change(
            static_cast<int>(state), callbacks_.user_data);
    }
    // Persistent slot (gh#40 fallout, v2.1.10): the streaming entry
    // points overwrite callbacks_ via set_callbacks(), so the legacy
    // on_state_change is silent for streaming runs. The persistent
    // slot is unaffected by that shuffle.
    if (state_observer_ != nullptr) {
        state_observer_(static_cast<int>(state), state_observer_data_);
    }
 
    // Hook: ON_STATE_CHANGE (v1.9.1)
    {
        std::string json = "{\"previous\":\""
            + std::string(agent_state_name(prev))
            + "\",\"current\":\""
            + std::string(agent_state_name(state)) + "\"}";
        fire_hook_info(hooks_, ENTROPIC_HOOK_ON_STATE_CHANGE, json.c_str());
    }
 
    // Hook: ON_ERROR when entering ERROR state (v1.9.1)
    if (state == AgentState::ERROR) {
        std::string json = "{\"error_code\":\"STATE_ERROR\""
            ",\"iteration\":"
            + std::to_string(ctx.metrics.iterations)
            + ",\"consecutive\":" + std::to_string(ctx.consecutive_errors)
            + "}";
        fire_hook_info(hooks_, ENTROPIC_HOOK_ON_ERROR, json.c_str());
    }
}
 
void AgentEngine::interrupt() {
    if (!interrupt_flag_.exchange(true)) {
        logger->info("Engine interrupted");
        // P1-10: propagate to external MCP transports so in-flight
        // tool calls abort alongside the generation loop.
        if (external_interrupt_cb_ != nullptr) {
            external_interrupt_cb_(external_interrupt_data_);
        }
    }
    pause_flag_.store(false);
}
 
void AgentEngine::set_external_interrupt(void (*cb)(void*),
                                         void* user_data) {
    external_interrupt_cb_ = cb;
    external_interrupt_data_ = user_data;
}
 
void AgentEngine::reset_interrupt() {
    interrupt_flag_.store(false);
}
 
void AgentEngine::pause() {
    logger->info("Engine paused");
    pause_flag_.store(true);
}
 
void AgentEngine::cancel_pause() {
    logger->info("Pause cancelled, interrupting");
    pause_flag_.store(false);
    interrupt_flag_.store(true);
}
 
std::pair<int, int> AgentEngine::context_usage(
    const std::vector<Message>& messages) const {
    int used = token_counter_.count_messages(messages);
    return {used, token_counter_.max_tokens};
}
 
void AgentEngine::reinject_context_anchors(LoopContext& ctx) {
    for (const auto& [key, content] : context_anchors_) {
        ContextAnchorDirective d(key, content);
        DirectiveResult r;
        dir_anchor(ctx, d, r);
    }
}
 
// ── Directive handler registration ───────────────────────
 
void AgentEngine::register_directive_handlers() {
    auto reg = [this](entropic_directive_type_t t, auto fn) {
        directive_processor_.register_handler(t,
            [this, fn](LoopContext& c, const Directive& d,
                       DirectiveResult& r) {
                (this->*fn)(c, d, r);
            });
    };
    reg(ENTROPIC_DIRECTIVE_STOP_PROCESSING, &AgentEngine::dir_stop);
    reg(ENTROPIC_DIRECTIVE_TIER_CHANGE,     &AgentEngine::dir_tier_change);
    reg(ENTROPIC_DIRECTIVE_DELEGATE,        &AgentEngine::dir_delegate);
    reg(ENTROPIC_DIRECTIVE_PIPELINE,        &AgentEngine::dir_pipeline);
    reg(ENTROPIC_DIRECTIVE_COMPLETE,        &AgentEngine::dir_complete);
    reg(ENTROPIC_DIRECTIVE_CLEAR_SELF_TODOS,&AgentEngine::dir_clear_todos);
    reg(ENTROPIC_DIRECTIVE_INJECT_CONTEXT,  &AgentEngine::dir_inject);
    reg(ENTROPIC_DIRECTIVE_PRUNE_MESSAGES,  &AgentEngine::dir_prune);
    reg(ENTROPIC_DIRECTIVE_CONTEXT_ANCHOR,  &AgentEngine::dir_anchor);
    reg(ENTROPIC_DIRECTIVE_PHASE_CHANGE,    &AgentEngine::dir_phase);
    reg(ENTROPIC_DIRECTIVE_NOTIFY_PRESENTER,&AgentEngine::dir_notify);
}
 
// ── Directive handlers ───────────────────────────────────
 
void AgentEngine::dir_stop(
    LoopContext&, const Directive&, DirectiveResult& r) {
    logger->info("[DIRECTIVE] stop_processing");
    r.stop_processing = true;
}
 
void AgentEngine::dir_tier_change(
    LoopContext& ctx, const Directive& d, DirectiveResult& r) {
    const auto& tc = static_cast<const TierChangeDirective&>(d);
    ctx.locked_tier = tc.tier;
    r.tier_changed = true;
    logger->info("[DIRECTIVE] tier_change: {}", tc.tier);
}
 
void AgentEngine::dir_delegate(
    LoopContext& ctx, const Directive& d, DirectiveResult& r) {
    const auto& dl = static_cast<const DelegateDirective&>(d);
    ctx.pending_delegation = PendingDelegation{
        dl.target, dl.task, dl.max_turns,
        dl.resume_from_delegation_id};
    r.stop_processing = true;
    if (dl.resume_from_delegation_id.empty()) {
        logger->info("[DIRECTIVE] delegate: target={} task='{}'",
                     dl.target, dl.task);
    } else {
        // gh#32 (v2.1.6): target will be resolved from storage later.
        logger->info("[DIRECTIVE] resume_delegation: id={} task='{}'",
                     dl.resume_from_delegation_id, dl.task);
    }
}
 
void AgentEngine::dir_pipeline(
    LoopContext& ctx, const Directive& d, DirectiveResult& r) {
    const auto& pl = static_cast<const PipelineDirective&>(d);
    ctx.pending_pipeline = PendingPipeline{pl.stages, pl.task};
    r.stop_processing = true;
    logger->info("[DIRECTIVE] pipeline: {} stages", pl.stages.size());
}
 
void AgentEngine::dir_complete(
    LoopContext& ctx, const Directive& d, DirectiveResult& r) {
    const auto& cd = static_cast<const CompleteDirective&>(d);
 
    // P1-5 follow-up (2.0.6-rc16.2): signal validating phase so async
    // subscribers can progress queued/running/running:<tier> → validating.
    auto prior_state = ctx.state;
    set_state(ctx, AgentState::VERIFYING);
 
    // Fire ON_COMPLETE pre-hook — application can validate/reject
    if (fire_complete_hook(cd.summary, ctx)) {
        logger->info("[DIRECTIVE] complete REJECTED by hook → revising");
        // Revision path: inform subscribers the validator is rewriting.
        ctx.metadata["validator_phase"] = "revising";
        set_state(ctx, prior_state);
        r.stop_processing = false;  // don't stop — model should retry
        return;
    }
 
    ctx.metadata["explicit_completion_summary"] = cd.summary;
    // Issue #10 (v2.1.4): persist coverage_gap signal in metadata so
    // delegation.cpp::build_child_result can hoist it onto the
    // DelegationResult that flows back to the parent. The metadata
    // path is the only channel that survives between the child loop
    // (which sees the directive) and the parent's
    // finalize_delegation_result (which reads the result).
    if (cd.coverage_gap) {
        ctx.metadata["coverage_gap"] = "true";
        ctx.metadata["gap_description"] = cd.gap_description;
        nlohmann::json files_arr = cd.suggested_files;
        ctx.metadata["suggested_files_json"] = files_arr.dump();
    }
    set_state(ctx, AgentState::COMPLETE);
    r.stop_processing = true;
    logger->info("[DIRECTIVE] complete coverage_gap={}",
                 cd.coverage_gap);
}
 
void AgentEngine::dir_clear_todos(
    LoopContext&, const Directive&, DirectiveResult&) {
    logger->debug("[DIRECTIVE] clear_self_todos (no-op)");
}
 
void AgentEngine::dir_inject(
    LoopContext&, const Directive& d, DirectiveResult& r) {
    const auto& ic = static_cast<const InjectContextDirective&>(d);
    if (!ic.content.empty()) {
        Message msg;
        msg.role = ic.role;
        msg.content = ic.content;
        r.injected_messages.push_back(std::move(msg));
        logger->info("[DIRECTIVE] inject_context");
    }
}
 
void AgentEngine::dir_prune(
    LoopContext& ctx, const Directive& d, DirectiveResult&) {
    const auto& pm = static_cast<const PruneMessagesDirective&>(d);
    auto [pruned, freed] = context_manager_.prune_tool_results(
        ctx, pm.keep_recent);
    logger->info("[DIRECTIVE] prune: {} results, {} chars", pruned, freed);
}
 
void AgentEngine::dir_anchor(
    LoopContext& ctx, const Directive& d, DirectiveResult&) {
    const auto& ca = static_cast<const ContextAnchorDirective&>(d);
    if (ca.content.empty()) {
        context_anchors_.erase(ca.key);
        remove_anchor_messages(ctx, ca.key);
        logger->info("Removed anchor: {}", ca.key);
        return;
    }
    context_anchors_[ca.key] = ca.content;
    remove_anchor_messages(ctx, ca.key);
    Message anchor;
    anchor.role = "user";
    anchor.content = ca.content;
    anchor.metadata["is_context_anchor"] = "true";
    anchor.metadata["anchor_key"] = ca.key;
    ctx.messages.push_back(std::move(anchor));
    logger->info("Updated anchor: {}", ca.key);
}
 
void AgentEngine::dir_phase(
    LoopContext& ctx, const Directive& d, DirectiveResult&) {
    const auto& pc = static_cast<const PhaseChangeDirective&>(d);
    ctx.active_phase = pc.phase;
    logger->info("[DIRECTIVE] phase_change: {}", pc.phase);
}
 
void AgentEngine::dir_notify(
    LoopContext&, const Directive& d, DirectiveResult&) {
    const auto& np = static_cast<const NotifyPresenterDirective&>(d);
    if (callbacks_.on_presenter_notify != nullptr) {
        callbacks_.on_presenter_notify(
            np.key.c_str(), np.data_json.c_str(),
            callbacks_.user_data);
    }
}
 
// ── Tool call parsing (v1.8.5) ───────────────────────────
 
static ToolCall build_tool_call_from_json(
    const nlohmann::json& obj, const std::string& tc_str) {
    ToolCall tc;
    tc.name = obj.value("name", "");
    tc.id = "tc-" + std::to_string(
        std::hash<std::string>{}(tc.name + tc_str) & 0xFFFF);
    if (obj.contains("arguments") && obj["arguments"].is_object()) {
        tc.arguments_json = obj["arguments"].dump();
        for (auto& [k, v] : obj["arguments"].items()) {
            tc.arguments[k] = v.is_string()
                ? v.get<std::string>() : v.dump();
        }
    }
    return tc;
}
 
static std::vector<ToolCall> decode_tool_calls_json(
    const std::string& tc_str) {
    std::vector<ToolCall> calls;
    if (tc_str == "[]" || tc_str.empty()) { return calls; }
    auto arr = nlohmann::json::parse(tc_str, nullptr, false);
    if (!arr.is_array()) { return calls; }
    for (const auto& obj : arr) {
        calls.push_back(build_tool_call_from_json(obj, tc_str));
    }
    return calls;
}
 
std::pair<std::string, std::vector<ToolCall>>
AgentEngine::parse_tool_calls(const std::string& raw_content) {
    if (inference_.parse_tool_calls == nullptr) {
        return {raw_content, {}};
    }
 
    char* cleaned = nullptr;
    char* tc_json = nullptr;
    int rc = inference_.parse_tool_calls(
        raw_content.c_str(), &cleaned, &tc_json,
        inference_.adapter_data);
 
    // gh#111 (v2.9.8): the tool-call parse callback is a SEPARATE inbound
    // boundary from response_generator's content sanitize. The backend derives
    // both `*cleaned` and `*tool_calls_json` from its own parse of the RAW
    // generation (common_chat / adapter parse_response), so a split multi-byte
    // UTF-8 codepoint — routine under MTP speculative decode — arrives here as
    // invalid bytes EVEN THOUGH result.content was already sanitized upstream
    // (response_generator.cpp:470). Both outputs cross into engine-owned state
    // at this one function:
    //   cleaned_str -> assistant Message.content -> (delegation) extract_summary
    //                  fallback -> DelegationResult.summary
    //                  -> fire_delegate_complete_hook j.dump()  [the gh#111 throw]
    //   tc_str      -> decode_tool_calls_json -> build_tool_call_from_json
    //                  obj["arguments"].dump() + CompleteTool result.dump()
    // v2.9.7 patched only the plugin-revised (out!=null) hook branches, which
    // never run on the headless path — so the raw summary still reached the
    // dump. Sanitize BOTH channels at this single boundary (the tool-call-channel
    // sibling of the content sanitize) so no downstream nlohmann::json::dump()
    // can throw type_error.316. (gh#3 recurrence.)
    std::string cleaned_str =
        mcp::sanitize_utf8(cleaned ? cleaned : raw_content);
    std::string tc_str = mcp::sanitize_utf8(tc_json ? tc_json : "[]");
 
    if (inference_.free_fn != nullptr) {
        if (cleaned != nullptr) { inference_.free_fn(cleaned); }
        if (tc_json != nullptr) { inference_.free_fn(tc_json); }
    }
 
    if (rc != 0) { return {cleaned_str, {}}; }
    auto calls = decode_tool_calls_json(tc_str);
    if (!calls.empty()) {
        logger->info("Parsed tool calls from model output");
    }
    return {cleaned_str, std::move(calls)};
}
 
void AgentEngine::defang_meta_action_envelope(Message& msg) const {
    auto tn = msg.metadata.find("tool_name");
    bool is_meta = tn != msg.metadata.end()
        && tn->second.rfind("entropic.", 0) == 0;
    if (!is_meta) { return; }
    auto j = nlohmann::json::parse(msg.content, nullptr, false);
    bool is_envelope = j.is_object() && j.contains("action")
        && j["action"].is_string();
    if (!is_envelope) { return; }
    msg.content = "(engine: " + j["action"].get<std::string>()
        + " directive accepted)";
}
 
bool AgentEngine::process_tool_results(
    LoopContext& ctx,
    const std::vector<ToolCall>& tool_calls) {
    set_state(ctx, AgentState::WAITING_TOOL);
 
    auto results = tool_exec_.process_tool_calls(
        ctx, tool_calls, tool_exec_.user_data);
 
    logger->info("[TOOLS] {} call(s) -> {} result message(s)",
                 tool_calls.size(), results.size());
 
    // gh#84 (v2.5.1): "progress" = at least one tool genuinely
    // executed (result_kind ok / ok_empty), not merely parsed. The
    // thinking budget resets only on progress so a duplicate/rejected
    // -spam spiral (rejected_duplicate, rejected_schema, anti-spiral)
    // can no longer keep its budget perpetually fresh.
    bool made_progress = false;
    for (auto& msg : results) {
        auto it = msg.metadata.find("result_kind");
        if (it != msg.metadata.end()
            && (it->second == "ok" || it->second == "ok_empty")) {
            made_progress = true;
        }
        if (fold_complete_into_assistant(ctx, msg)) {
            continue;  // gh#68: folded; skip pushing JSON user message
        }
        defang_meta_action_envelope(msg);  // gh#88: strip call-shaped envelope
        ctx.messages.push_back(std::move(msg));
    }
 
    ctx.has_pending_tool_results = true;
    // Don't overwrite terminal states set by directive handlers
    if (!is_terminal_state(ctx)) {
        set_state(ctx, AgentState::EXECUTING);
    }
    return made_progress;
}
 
// ── Anchor helper ────────────────────────────────────────
 
static void remove_anchor_messages(LoopContext& ctx,
                                    const std::string& key) {
    auto& msgs = ctx.messages;
    msgs.erase(
        std::remove_if(msgs.begin(), msgs.end(),
            [&key](const Message& m) {
                auto it = m.metadata.find("anchor_key");
                return it != m.metadata.end() && it->second == key;
            }),
        msgs.end());
}
 
// ── Hook helpers (v1.9.1) ────────────────────────────────
 
bool AgentEngine::fire_pre_hook(
    entropic_hook_point_t point, int iteration) {
    if (hooks_.fire_pre == nullptr) {
        return false;
    }
    std::string json = "{\"iteration\":"
        + std::to_string(iteration) + "}";
    char* modified = nullptr;
    int rc = hooks_.fire_pre(hooks_.registry,
        point, json.c_str(), &modified);
    free(modified);
    return rc != 0;
}
 
static const std::array<const char*, 256>& json_escape_table() {
    static const auto tbl = []() {
        std::array<const char*, 256> t{};
        t[static_cast<unsigned char>('"')]  = "\\\"";
        t[static_cast<unsigned char>('\\')] = "\\\\";
        t[static_cast<unsigned char>('\n')] = "\\n";
        t[static_cast<unsigned char>('\r')] = "\\r";
        t[static_cast<unsigned char>('\t')] = "\\t";
        return t;
    }();
    return tbl;
}
 
static std::string json_escape_engine(const std::string& s) {
    const auto& tbl = json_escape_table();
    std::string out;
    out.reserve(s.size() + 16);
    for (char c : s) {
        const char* esc = tbl[static_cast<unsigned char>(c)];
        if (esc) { out += esc; }
        else     { out += c; }
    }
    return out;
}
 
static std::string build_tool_manifest(
    const std::vector<Message>& messages) {
    std::string manifest;
    for (const auto& msg : messages) {
        auto it = msg.metadata.find("tool_name");
        if (it == msg.metadata.end() || it->second.empty()) {
            continue;
        }
        // Issue #5 (v2.1.3): when prune has stubbed this message, the
        // original (pre-stub) content size is preserved in
        // metadata["original_content"]. Report the real size so the
        // validator sees accurate evidence sizes instead of the stub
        // length (which is always ~50 chars regardless of original).
        auto orig = msg.metadata.find("original_content");
        size_t real_size = (orig != msg.metadata.end())
                         ? orig->second.size()
                         : msg.content.size();
        manifest += "- " + it->second
            + " \xe2\x86\x92 " + std::to_string(real_size)
            + " chars\n";
    }
    return manifest;
}
 
static std::string format_tool_evidence_entry(const Message& msg,
                                              size_t chars_per_result) {
    auto orig = msg.metadata.find("original_content");
    const std::string& src = (orig != msg.metadata.end())
                           ? orig->second
                           : msg.content;
    auto iter = msg.metadata.find("added_at_iteration");
    std::string out = "## ";
    out += msg.metadata.at("tool_name");
    if (iter != msg.metadata.end()) {
        out += " [iter " + iter->second + "]";
    }
    out += "\n";
    if (src.size() <= chars_per_result) {
        out += src;
    } else {
        out += src.substr(0, chars_per_result);
        out += "\n[... truncated, "
             + std::to_string(src.size() - chars_per_result)
             + " more chars]";
    }
    out += "\n\n";
    return out;
}
 
static std::string build_tool_evidence(
    const std::vector<Message>& messages,
    size_t max_results,
    size_t chars_per_result) {
    std::vector<const Message*> tool_msgs;
    for (const auto& msg : messages) {
        auto it = msg.metadata.find("tool_name");
        if (it == msg.metadata.end() || it->second.empty()) {
            continue;
        }
        tool_msgs.push_back(&msg);
    }
    if (tool_msgs.empty()) { return {}; }
 
    size_t elided = (tool_msgs.size() > max_results)
                  ? (tool_msgs.size() - max_results) : 0;
    size_t start = elided;
    std::string out;
    if (elided > 0) {
        out += "(" + std::to_string(elided)
             + " earlier tool results elided for length)\n";
    }
    for (size_t i = start; i < tool_msgs.size(); ++i) {
        out += format_tool_evidence_entry(*tool_msgs[i], chars_per_result);
    }
    return out;
}
 
static std::string enrich_manifest_with_history(
    const std::string& base,
    const ToolExecutionInterface& tool_exec) {
    if (tool_exec.history_json == nullptr) { return base; }
    char* js = tool_exec.history_json(20, tool_exec.user_data);
    if (js == nullptr) { return base; }
    std::string out = base + "prior-iteration history: " + js + "\n";
    if (tool_exec.free_fn != nullptr) { tool_exec.free_fn(js); }
    return out;
}
 
static std::string extract_system_prompt(
    const std::vector<Message>& messages) {
    for (const auto& msg : messages) {
        if (msg.role == "system") { return msg.content; }
    }
    return {};
}
 
void AgentEngine::fire_post_generate_hook(
    GenerateResult& result,
    const std::string& tier,
    const std::vector<Message>& messages) {
    if (hooks_.fire_post == nullptr) {
        return;
    }
    auto manifest = build_tool_manifest(messages);
    manifest = enrich_manifest_with_history(manifest, tool_exec_);
    auto sys = extract_system_prompt(messages);
    // Issue #5 (v2.1.3): include un-pruned tool-result evidence so the
    // constitutional validator can verify file:line citations against
    // actual content rather than the stubs that prune leaves behind.
    // Bounded at 20 most-recent results × 800 chars each (~16KB max
    // evidence), well within any sane critique-prompt budget. The
    // field is OPTIONAL on the hook contract — pre-2.1.3 consumers
    // ignore it; v2.1.3 validator augments its critique prompt.
    auto evidence = build_tool_evidence(messages, 20, 800);
    std::string json =
        "{\"finish_reason\":\"" + result.finish_reason
        + "\",\"content\":\""    + json_escape_engine(result.content)
        + "\",\"tier\":\""       + tier
        + "\",\"tool_context\":\"" + json_escape_engine(manifest)
        + "\",\"tool_evidence\":\"" + json_escape_engine(evidence)
        + "\",\"system_prompt\":\"" + json_escape_engine(sys) + "\"}";
    char* out = nullptr;
    hooks_.fire_post(hooks_.registry,
        ENTROPIC_HOOK_POST_GENERATE, json.c_str(), &out);
    if (out != nullptr) {
        // gh#3 recurrence (v2.9.6): a hook's revised content is an
        // inbound boundary crossing a plugin .so, same class as the
        // MCP tool-result boundary — sanitize before it re-enters the
        // engine so downstream json::dump() (delegate-complete hook,
        // facade serialization, storage) cannot throw type_error 316.
        result.content = mcp::sanitize_utf8(out);
        logger->info("POST_GENERATE hook revised content");
        free(out);
    }
}
 
void AgentEngine::dispatch_post_generate(
    LoopContext& ctx, GenerateResult& result) {
    // The per-turn reminders built from pending_validation_feedback
    // and pending_anti_spiral_warning were just consumed by
    // generate_response — clear both so neither leaks into a later
    // iteration. (#42, #45 — both one-shot.)
    ctx.pending_validation_feedback.clear();
    ctx.pending_anti_spiral_warning.clear();
    fire_post_generate_hook(result, ctx.locked_tier, ctx.messages);
    // After POST_GENERATE the validator may have rejected — stash
    // its reason for the NEXT iteration's system prompt.
    capture_validation_feedback(ctx);
}
 
void AgentEngine::capture_validation_feedback(LoopContext& ctx) {
    if (validation_provider_ == nullptr) { return; }
    char* v = validation_provider_(validation_provider_data_);
    if (v == nullptr) { return; }
    std::string raw(v);
    free(v);
    try {
        auto j = nlohmann::json::parse(raw);
        auto verdict = j.value("verdict", "");
        if (verdict.rfind("rejected", 0) != 0) { return; }
        std::string joined;
        if (j.contains("violations") && j["violations"].is_array()) {
            for (const auto& vio : j["violations"]) {
                if (!joined.empty()) { joined += "; "; }
                joined += vio.is_string()
                    ? vio.get<std::string>()
                    : vio.dump();
            }
        }
        if (joined.empty()) { joined = verdict; }
        ctx.pending_validation_feedback = joined;
    } catch (const nlohmann::json::exception&) {
        // Malformed provider output is non-fatal; just skip.
    }
}
 
static std::string build_tool_results_json(
    const std::vector<Message>& messages) {
    std::string arr = "[";
    bool first = true;
    for (const auto& msg : messages) {
        auto it = msg.metadata.find("tool_name");
        if (it == msg.metadata.end() || it->second.empty()) {
            continue;
        }
        if (!first) { arr += ","; }
        arr += "{\"name\":\"" + json_escape_engine(it->second)
            + "\",\"content\":\"" + json_escape_engine(msg.content)
            + "\"}";
        first = false;
    }
    arr += "]";
    return arr;
}
 
bool AgentEngine::fire_complete_hook(
    const std::string& summary,
    const LoopContext& ctx) {
    if (hooks_.fire_pre == nullptr) { return false; }
 
    auto tool_results = build_tool_results_json(ctx.messages);
    // E3 (2.0.6-rc17): splice validator verdict/violations so
    // ON_COMPLETE consumers can distinguish clean pass from
    // reverted-for-length / max-revisions-exhausted.
    std::string validation_block = ",\"validation\":null";
    if (validation_provider_ != nullptr) {
        char* v = validation_provider_(validation_provider_data_);
        if (v != nullptr) {
            validation_block = ",\"validation\":" + std::string(v);
            free(v);
        }
    }
    std::string json =
        "{\"summary\":\"" + json_escape_engine(summary)
        + "\",\"tier\":\"" + ctx.locked_tier
        + "\",\"tool_results\":" + tool_results
        + ",\"iteration\":" + std::to_string(ctx.metrics.iterations)
        + validation_block
        + "}";
    char* modified = nullptr;
    int rc = hooks_.fire_pre(hooks_.registry,
        ENTROPIC_HOOK_ON_COMPLETE, json.c_str(), &modified);
    if (modified != nullptr) {
        // Hook provided rejection feedback — inject as user message.
        // Same inbound-boundary gap as fire_post_generate_hook above:
        // sanitize the hook's returned bytes before they enter a
        // Message that later flows to json::dump() call sites.
        Message feedback;
        feedback.role = "user";
        feedback.content =
            std::string("[CITATION VALIDATION] ") + mcp::sanitize_utf8(modified);
        const_cast<LoopContext&>(ctx).messages.push_back(
            std::move(feedback));
        free(modified);
    }
    return rc != 0;
}
 
bool AgentEngine::fire_delegate_pre_hook(
    const PendingDelegation& pending, int depth) {
    if (hooks_.fire_pre == nullptr) {
        return false;
    }
    std::string json = "{\"target_tier\":\""
        + pending.target + "\",\"task\":\""
        + pending.task + "\",\"depth\":"
        + std::to_string(depth) + "}";
    char* modified = nullptr;
    int rc = hooks_.fire_pre(hooks_.registry,
        ENTROPIC_HOOK_ON_DELEGATE, json.c_str(), &modified);
    free(modified);
    return rc != 0;
}
 
// ── detail::build_delegate_complete_json (gh#113, v2.9.9) ──────────────────
// Extracted from fire_delegate_complete_hook so it can be driven directly in
// unit tests with a bad-UTF8 summary (simulating gh#112 storage-load path).
 
std::string entropic::detail::build_delegate_complete_json(
    const std::string& target,
    bool success,
    const std::string& summary) {
    nlohmann::json j;
    j["target_tier"] = target;
    j["success"] = success;
    j["result_kind"] = result_kind_to_string(success
        ? ToolResultKind::ok
        : ToolResultKind::delegation_failed);
    j["summary"] = mcp::sanitize_utf8(summary);
    return j.dump();
}
 
void AgentEngine::fire_delegate_complete_hook(
    const std::string& target, bool success,
    const std::string& summary) {
    if (hooks_.fire_post == nullptr) {
        return;
    }
    std::string json = detail::build_delegate_complete_json(
        target, success, summary);
    char* out = nullptr;
    hooks_.fire_post(hooks_.registry,
        ENTROPIC_HOOK_ON_DELEGATE_COMPLETE, json.c_str(), &out);
    free(out);
}
 
// ── Delegation execution (v1.8.6) ────────────────────────
 
static void run_child_loop_trampoline(LoopContext& ctx, void* user_data) {
    auto* engine = static_cast<AgentEngine*>(user_data);
    // gh#81 (v2.4.3): inherit the parent's interrupt — a child loop
    // must not clear a parent interrupt raised at/just-before dispatch.
    engine->run_loop(ctx, /*inherit_interrupt=*/true);
}
 
static void push_delegation_rejected(LoopContext& ctx) {
    Message reject;
    reject.role = "user";
    reject.content = "[DELEGATION REJECTED] Maximum delegation "
                     "depth (" + std::to_string(
                         AgentEngine::MAX_DELEGATION_DEPTH) +
                     ") reached.";
    ctx.messages.push_back(std::move(reject));
}
 
static void push_delegation_cycle_rejected(
    LoopContext& ctx, const std::string& target) {
    std::string chain;
    for (const auto& anc : ctx.delegation_ancestor_tiers) {
        chain += anc + " -> ";
    }
    chain += ctx.locked_tier + " -> " + target;
 
    Message reject;
    reject.role = "user";
    reject.content = "[DELEGATION REJECTED] Circular delegation "
                     "detected: tier '" + target +
                     "' already in the active delegation chain "
                     "(" + chain + "). Choose a different target.";
    ctx.metadata["failure_reason"] = "delegation_cycle";
    ctx.metadata["failure_target"] = target;
    ctx.messages.push_back(std::move(reject));
}
 
static void push_delegation_result(LoopContext& ctx,
    const std::string& target, const DelegationResult& result) {
    std::string tag = result.success ? "COMPLETE" : "FAILED";
    Message msg;
    msg.role = "user";
    msg.content = "[DELEGATION " + tag + ": " + target + "] " + result.summary;
    ctx.messages.push_back(std::move(msg));
}
 
static void push_delegation_repeat_blocked(
    LoopContext& ctx, const std::string& target, int n) {
    Message reject;
    reject.role = "user";
    reject.content = "[DELEGATION REJECTED] '" + target
        + "' has just failed " + std::to_string(n)
        + " times in a row. Stop retrying this target. Either "
          "respond to the user with what you have, or delegate to "
          "a different tier.";
    ctx.metadata["failure_reason"] = "delegation_repeat_blocked";
    ctx.metadata["failure_target"] = target;
    ctx.messages.push_back(std::move(reject));
}
 
bool AgentEngine::reject_delegation_if_guarded(
    LoopContext& ctx, const PendingDelegation& pending) {
    bool rejected = true;
    if (ctx.delegation_depth >= MAX_DELEGATION_DEPTH) {
        logger->warn("Delegation rejected: depth {} >= max {}",
                     ctx.delegation_depth, MAX_DELEGATION_DEPTH);
        push_delegation_rejected(ctx);
    } else if (is_delegation_cycle(ctx, pending.target)) {
        // P1-9: reject A→B→A and longer cycles before running a child.
        logger->warn("Delegation rejected: cycle on target tier '{}'",
                     pending.target);
        push_delegation_cycle_rejected(ctx, pending.target);
    } else if (is_delegation_repeat_blocked(ctx, pending.target)) {
        // gh#64: refuse re-delegation to a target that has just failed
        // N times in a row. Pre-fix, a lead retrying a Q4 specialist
        // that couldn't emit a tool call would burn 30+ identical
        // delegations before its own iteration cap stopped it.
        logger->warn("Delegation rejected: '{}' failed {}x in a row "
                     "(>= max_consecutive_failed_delegations={})",
                     pending.target,
                     ctx.consecutive_failed_delegations,
                     loop_config_.max_consecutive_failed_delegations);
        push_delegation_repeat_blocked(
            ctx, pending.target, ctx.consecutive_failed_delegations);
    } else {
        rejected = false;
    }
    return rejected;
}
 
void AgentEngine::execute_pending_delegation(LoopContext& ctx) {
    auto pending = std::move(*ctx.pending_delegation);
    ctx.pending_delegation.reset();
 
    if (reject_delegation_if_guarded(ctx, pending)) { return; }
 
    set_state(ctx, AgentState::DELEGATING);
 
    // gh#32 (v2.1.6): resume_delegation tool emits a directive with
    // resume_from_delegation_id set; the target tier is unknown to the
    // tool and must be resolved from storage. Failure to load (unknown
    // id, no storage) surfaces a typed error to the lead.
    //
    // The pre-hook gate is interleaved with resume so both share a
    // single early-exit (knots returns gate).
    std::vector<Message> resume_history;
    bool blocked = false;
    if (!pending.resume_from_delegation_id.empty()
        && !resolve_resume_delegation(ctx, pending, resume_history)) {
        blocked = true;
    } else if (fire_delegate_pre_hook(pending, ctx.delegation_depth)) {
        logger->info("ON_DELEGATE hook cancelled delegation");
        blocked = true;
    }
    if (blocked) {
        set_state(ctx, AgentState::EXECUTING);
        return;
    }
 
    fire_delegation_start(ctx, pending.target, pending.task);
    auto result = run_pending_delegation(
        ctx, pending, std::move(resume_history));
    push_delegation_result(ctx, pending.target, result);
 
    // gh#64: track consecutive failures against the same target.
    if (result.success) {
        ctx.last_failed_delegation_target.clear();
        ctx.consecutive_failed_delegations = 0;
    } else if (pending.target == ctx.last_failed_delegation_target) {
        ++ctx.consecutive_failed_delegations;
    } else {
        ctx.last_failed_delegation_target = pending.target;
        ctx.consecutive_failed_delegations = 1;
    }
 
    fire_delegation_complete(ctx, pending.target, result);
    fire_delegate_complete_hook(pending.target, result.success,
                                result.summary);
 
    finalize_delegation_result(ctx, result);
}
 
void AgentEngine::relay_partial_result(
    LoopContext& ctx, const std::string& summary) {
    GenerateResult relay_result;
    relay_result.content = summary;
    relay_result.finish_reason = "stop";
    relay_result.tool_calls_json = "[]";
    fire_post_generate_hook(
        relay_result, ctx.locked_tier, ctx.messages);
    ctx.metadata["explicit_completion_summary"] = relay_result.content;
    set_state(ctx, AgentState::COMPLETE);
}
 
static std::string build_coverage_gap_message(
    const std::string& tier, const DelegationResult& result) {
    std::string body =
        "[COVERAGE GAP from " + tier + "]\n"
        "Summary so far: " + result.summary + "\n"
        "What's missing: " + result.gap_description;
    if (!result.suggested_files.empty()) {
        body += "\nSuggested files to inspect:";
        for (const auto& f : result.suggested_files) {
            body += "\n  - " + f;
        }
    }
    return body;
}
 
static void fold_delegation_summary(
    LoopContext& ctx, const std::string& summary) {
    for (auto rit = ctx.messages.rbegin();
         rit != ctx.messages.rend(); ++rit) {
        if (rit->role == "assistant" && rit->content.empty()) {
            rit->content = summary;
            break;
        }
    }
}
 
void AgentEngine::finalize_delegation_result(
    LoopContext& ctx, const DelegationResult& result) {
    // delegation.cpp sets success=false when terminal_reason is non-empty,
    // so the two relay branches are disjoint — check them independently.
    const bool in_relay_tier =
        relay_single_delegate_tiers_.count(ctx.locked_tier) > 0;
    if (in_relay_tier && result.coverage_gap) {
        Message gap;
        gap.role = "user";
        gap.content = build_coverage_gap_message(
            result.target_tier, result);
        ctx.messages.push_back(std::move(gap));
        ctx.metadata["relay_status"] = "coverage_gap_suppressed";
        logger->info(
            "[COVERAGE GAP] suppressing auto-relay for tier={} "
            "({} suggested files)",
            result.target_tier, result.suggested_files.size());
        set_state(ctx, AgentState::EXECUTING);
        return;
    }
    if (result.success && in_relay_tier) {
        relay_partial_result(ctx, result.summary);
        log_relay_status(ctx);
        return;
    }
    if (!result.terminal_reason.empty() && in_relay_tier) {
        relay_partial_result(ctx,
            "[partial — budget_exhausted] " + result.summary);
        log_relay_status(ctx, result.terminal_reason);
        return;
    }
    bool needs_explicit = tier_requires_explicit_completion(
        ctx.locked_tier);
    if (result.success && !needs_explicit) {
        fold_delegation_summary(ctx, result.summary);  // gh#119
    }
    set_state(ctx, (result.success && !needs_explicit)
        ? AgentState::COMPLETE : AgentState::EXECUTING);
}
 
void AgentEngine::log_relay_status(LoopContext& ctx,
                                   const std::string& terminal_reason) {
    std::string verdict;
    if (validation_provider_ != nullptr) {
        char* v = validation_provider_(validation_provider_data_);
        if (v != nullptr) {
            std::string jv(v);
            free(v);
            auto pos = jv.find("\"verdict\":\"");
            if (pos != std::string::npos) {
                pos += 11;
                auto end = jv.find('"', pos);
                if (end != std::string::npos) {
                    verdict = jv.substr(pos, end - pos);
                }
            }
        }
    }
    if (!terminal_reason.empty()) {
        ctx.metadata["relay_status"] = "budget_exhausted_relayed";
        logger->warn(
            "Relay: single-delegate result used "
            "(partial — terminal_reason={}, verdict={})",
            terminal_reason, verdict.empty() ? "none" : verdict);
        return;
    }
    if (verdict == "skipped" || verdict.empty()) {
        ctx.metadata["relay_status"] = "validation_skipped";
        logger->info(
            "Relay: single-delegate result used "
            "(lead validation skipped per config)");
    } else {
        ctx.metadata["relay_status"] = "validated";
        logger->info(
            "Relay: single-delegate result used "
            "(passed lead validation)");
    }
}
 
void AgentEngine::execute_pending_pipeline(LoopContext& ctx) {
    auto pending = std::move(*ctx.pending_pipeline);
    ctx.pending_pipeline.reset();
 
    if (ctx.delegation_depth >= MAX_DELEGATION_DEPTH) {
        logger->warn("Pipeline rejected: depth {} >= max {}",
                     ctx.delegation_depth, MAX_DELEGATION_DEPTH);
        Message reject;
        reject.role = "user";
        reject.content = "[PIPELINE REJECTED] Maximum delegation "
                         "depth reached.";
        ctx.messages.push_back(std::move(reject));
        return;
    }
 
    set_state(ctx, AgentState::DELEGATING);
 
    // gh#33 (v2.1.6): engine-scoped sandbox; non-owning pointer.
    auto repo_dir = get_repo_dir();
    DelegationManager mgr(run_child_loop_trampoline, this,
                          tier_res_, repo_dir,
                          ensure_sandbox_manager());
    if (storage_.create_delegation != nullptr) {
        mgr.set_storage(&storage_);
    }
    // gh#29 (v2.1.5): snapshot under the mutex (see execute_pending_
    // delegation comment); avoids a torn read against a concurrent
    // set_delegation_callbacks call.
    auto cb_snap = delegation_callbacks_snapshot();
    mgr.set_delegation_callbacks(
        cb_snap.start, cb_snap.complete, cb_snap.user_data);
    std::vector<DelegationResult> stage_log;
    auto result = mgr.execute_pipeline(
        ctx, pending.stages, pending.task, stage_log);
 
    std::string tag = result.success ? "COMPLETE" : "FAILED";
    std::string content = "[PIPELINE " + tag + "]";
    for (size_t i = 0; i < stage_log.size(); ++i) {
        content += "\nStage " + std::to_string(i + 1)
                   + " (" + stage_log[i].target_tier + "): "
                   + stage_log[i].summary;
    }
    content += "\nFinal: " + result.summary;
    Message result_msg;
    result_msg.role = "user";
    result_msg.content = std::move(content);
    ctx.messages.push_back(std::move(result_msg));
 
    set_state(ctx, AgentState::EXECUTING);
}
 
void AgentEngine::fire_delegation_start(
    const LoopContext& /*ctx*/,
    const std::string& tier,
    const std::string& task) {
    if (callbacks_.on_delegation_start != nullptr) {
        callbacks_.on_delegation_start(
            "", tier.c_str(), task.c_str(),
            callbacks_.user_data);
    }
}
 
void AgentEngine::fire_delegation_complete(
    const LoopContext& /*ctx*/,
    const std::string& tier,
    const DelegationResult& result) {
    if (callbacks_.on_delegation_complete != nullptr) {
        callbacks_.on_delegation_complete(
            "", tier.c_str(), result.summary.c_str(),
            result.success ? 1 : 0,
            callbacks_.user_data);
    }
}
 
// ── Auto-chain (v1.8.6) ─────────────────────────────────
 
bool AgentEngine::should_auto_chain(
    const LoopContext& ctx,
    const std::string& finish_reason,
    const std::string& content) {
    if (ctx.locked_tier.empty() || tier_res_.get_tier_param == nullptr) {
        return false;
    }
 
    std::string auto_chain = tier_res_.get_tier_param(
        ctx.locked_tier, "auto_chain", tier_res_.user_data);
    if (auto_chain.empty()) {
        return false;
    }
 
    bool triggered = (finish_reason == "length") ||
        (finish_reason == "stop" &&
         response_generator_.is_response_complete(content, "[]"));
    return triggered;
}
 
bool AgentEngine::try_auto_chain(
    LoopContext& ctx,
    const std::string& finish_reason,
    const std::string& content) {
    if (!should_auto_chain(ctx, finish_reason, content)) {
        return false;
    }
 
    if (ctx.delegation_depth > 0) {
        logger->info("[AUTO-CHAIN] child depth={}, completing",
                     ctx.delegation_depth);
        set_state(ctx, AgentState::COMPLETE);
        return true;
    }
 
    // Root: tier change to auto_chain target
    std::string target = tier_res_.get_tier_param(
        ctx.locked_tier, "auto_chain", tier_res_.user_data);
 
    if (!target.empty()) {
        logger->info("[AUTO-CHAIN] root, tier change to '{}'", target);
        TierChangeDirective tc(target, "auto_chain");
        DirectiveResult r;
        dir_tier_change(ctx, tc, r);
    }
    return !target.empty();
}
 
// ── Project dir (v2.1.5, gh#29) ─────────────────────────
 
std::filesystem::path AgentEngine::get_repo_dir() {
    if (repo_dir_checked_) {
        return cached_repo_dir_.value_or(std::filesystem::path{});
    }
    repo_dir_checked_ = true;
    std::filesystem::path resolved;
    if (!project_dir_override_.empty()) {
        resolved = project_dir_override_;
        logger->info("Project dir for sandbox snapshots: {} (configured)",
                     resolved.string());
    } else {
        resolved = std::filesystem::current_path();
        logger->info("Project dir for sandbox snapshots: {} (cwd fallback)",
                     resolved.string());
    }
    cached_repo_dir_ = resolved;
    return resolved;
}
 
void AgentEngine::set_project_dir(const std::filesystem::path& project_dir) {
    project_dir_override_ = project_dir;
    cached_repo_dir_.reset();
    repo_dir_checked_ = false;
}
 
static void push_resume_failure(
        LoopContext& ctx,
        const std::string& reason,
        const std::string& delegation_id) {
    Message m;
    m.role = "user";
    m.content = "[DELEGATION FAILED: resume_delegation] "
                + reason + " (delegation_id=" + delegation_id + ")";
    ctx.messages.push_back(std::move(m));
}
 
bool AgentEngine::fetch_resume_payload(
        LoopContext& ctx,
        const std::string& id,
        nlohmann::json& parsed) {
    std::optional<std::string> error;
    std::string raw;
    if (storage_.load_delegation_with_messages == nullptr) {
        error = "storage unavailable";
    } else if (!storage_.load_delegation_with_messages(
                   id.c_str(), raw, storage_.user_data)) {
        error = "unknown delegation_id";
    } else {
        parsed = nlohmann::json::parse(raw, nullptr, false);
        if (parsed.is_discarded() || !parsed.is_object()) {
            error = "malformed storage payload";
        }
    }
    if (error.has_value()) {
        logger->error("resume_delegation '{}': {}", id, *error);
        push_resume_failure(ctx, *error, id);
        return false;
    }
    return true;
}
 
bool AgentEngine::resolve_resume_delegation(
        LoopContext& ctx,
        PendingDelegation& pending,
        std::vector<Message>& out_history) {
    const auto& id = pending.resume_from_delegation_id;
    nlohmann::json j;
    if (!fetch_resume_payload(ctx, id, j)) {
        return false;
    }
    auto target = j.value("target_tier", std::string{});
    if (target.empty()) {
        push_resume_failure(ctx, "target_tier missing in storage", id);
        return false;
    }
    pending.target = target;
    if (j.contains("messages") && j["messages"].is_array()) {
        for (const auto& mj : j["messages"]) {
            Message m;
            m.role = mj.value("role", "");
            m.content = mj.value("content", "");
            if (!m.role.empty()) {
                out_history.push_back(std::move(m));
            }
        }
    }
    logger->info("resume_delegation '{}': loaded {} messages, target='{}'",
                 id, out_history.size(), target);
    return true;
}
 
DelegationResult AgentEngine::run_pending_delegation(
        LoopContext& ctx,
        const PendingDelegation& pending,
        std::vector<Message> resume_history) {
    std::optional<int> max_turns;
    if (pending.max_turns > 0) { max_turns = pending.max_turns; }
    DelegationManager mgr(run_child_loop_trampoline, this,
                          tier_res_, get_repo_dir(),
                          ensure_sandbox_manager());
    if (storage_.create_delegation != nullptr) {
        mgr.set_storage(&storage_);
    }
    auto cb_snap = delegation_callbacks_snapshot();
    mgr.set_delegation_callbacks(
        cb_snap.start, cb_snap.complete, cb_snap.user_data);
    if (resume_history.empty()) {
        return mgr.execute_delegation(
            ctx, pending.target, pending.task, max_turns);
    }
    return mgr.execute_resume_delegation(
        ctx, pending.target, pending.task,
        std::move(resume_history), max_turns);
}
 
SandboxManager* AgentEngine::ensure_sandbox_manager() {
    if (sandbox_mgr_) {
        return &*sandbox_mgr_;
    }
    auto repo_dir = get_repo_dir();
    if (repo_dir.empty()) {
        return nullptr;
    }
    sandbox_mgr_.emplace(repo_dir);
    return &*sandbox_mgr_;
}
 
// ── Conversation state (v2.0.2) ─────────────────────────────
 
void AgentEngine::set_system_prompt(const std::string& prompt) {
    system_prompt_ = prompt;
}
 
void AgentEngine::set_session_logger(SessionLogger* log) {
    session_logger_ = log;
}
 
std::vector<Message> AgentEngine::run_turn(const std::string& input) {
    // gh#40 (v2.1.10): the drain loop turns mid-generation queued user
    // messages into subsequent turns at this single top-level COMPLETE
    // boundary. running_flag_ lets the facade reject
    // entropic_queue_user_message with INVALID_STATE when idle.
    running_flag_.store(true);
    if (conversation_.empty() && !system_prompt_.empty()) {
        Message sys;
        sys.role = "system";
        sys.content = system_prompt_;
        conversation_.push_back(std::move(sys));
    }
    auto result = run_drain_loop(input, /*tier_override=*/"");
    running_flag_.store(false);
    return result;
}
 
std::vector<Message> AgentEngine::run_turn_as(const std::string& tier,
                                              const std::string& input) {
    running_flag_.store(true);
    seed_system_prompt_for_tier(tier);
    auto result = run_drain_loop(input, tier);
    running_flag_.store(false);
    return result;
}
 
void AgentEngine::seed_system_prompt_for_tier(const std::string& tier) {
    if (!conversation_.empty()) { return; }
    auto it = tier_info_.find(tier);
    const std::string& sp =
        (it != tier_info_.end() && !it->second.system_prompt.empty())
            ? it->second.system_prompt
            : system_prompt_;
    if (sp.empty()) { return; }
    Message sys;
    sys.role = "system";
    sys.content = sp;
    conversation_.push_back(std::move(sys));
}
 
std::vector<Message> AgentEngine::run_drain_loop(
    std::string pending, const std::string& tier_override) {
    std::vector<Message> result;
    while (true) {
        Message usr;
        usr.role = "user";
        usr.content = pending;
        conversation_.push_back(std::move(usr));
 
        size_t sent_len = conversation_.size();
        result = run(conversation_, tier_override);  // copy — run() may mutate
        for (size_t i = sent_len; i < result.size(); ++i) {
            conversation_.push_back(result[i]);
        }
        auto next = pop_queued_user_message();
        if (!next.has_value()) { break; }
        fire_queue_consumed(*next, user_message_queue_depth());
        pending = std::move(*next);
    }
    return result;
}
 
void AgentEngine::seed_system_prompt(
    const std::vector<Message>& new_messages) {
    bool caller_has_system = false;
    for (const auto& m : new_messages) {
        if (m.role == "system") { caller_has_system = true; break; }
    }
    if (conversation_.empty() && !system_prompt_.empty()
            && !caller_has_system) {
        Message sys;
        sys.role = "system";
        sys.content = system_prompt_;
        conversation_.push_back(std::move(sys));
    }
}
 
bool AgentEngine::prepare_next_turn(std::vector<Message>& pending) {
    auto next = pop_queued_user_message();
    if (!next.has_value()) { return false; }
    fire_queue_consumed(*next, user_message_queue_depth());
    Message usr;
    usr.role = "user";
    usr.content = std::move(*next);
    pending.clear();
    pending.push_back(std::move(usr));
    return true;
}
 
std::vector<Message> AgentEngine::run_turn(std::vector<Message> new_messages) {
    // gh#40 (v2.1.10): mirror the single-string overload's drain
    // loop. Queued messages enqueued via entropic_queue_user_message
    // become subsequent plain-text user turns at this top-level
    // boundary (no content_parts — the queue ABI is text-only).
    running_flag_.store(true);
    seed_system_prompt(new_messages);
    std::vector<Message> pending = std::move(new_messages);
    std::vector<Message> result;
    while (true) {
        for (auto& m : pending) {
            conversation_.push_back(std::move(m));
        }
        size_t sent_len = conversation_.size();
        result = run(conversation_);
        for (size_t i = sent_len; i < result.size(); ++i) {
            conversation_.push_back(result[i]);
        }
        if (!prepare_next_turn(pending)) { break; }
    }
    running_flag_.store(false);
    return result;
}
 
int AgentEngine::run_streaming(
    const std::string& input,
    TokenCallback on_token,
    void* user_data,
    int* cancel_flag)
{
    if (session_logger_) {
        session_logger_->log_user_input(input);
    }
 
    StreamThinkFilter filter(on_token, user_data);
    if (session_logger_ && session_logger_->is_open()) {
        filter.set_raw_callback(
            SessionLogger::raw_token_callback,
            session_logger_);
    }
 
    struct Ctx {
        StreamThinkFilter* filter;
        int* cancel;
        AgentEngine* engine;
    };
    Ctx sctx{&filter, cancel_flag, this};
 
    EngineCallbacks cbs{};
    cbs.on_stream_chunk = [](const char* t, size_t l, void* ud) {
        auto* c = static_cast<Ctx*>(ud);
        if (c->cancel && *c->cancel) {
            c->engine->interrupt();
            return;
        }
        c->filter->on_token(t, l);
    };
    cbs.user_data = &sctx;
    set_callbacks(cbs);
 
    auto result = run_turn(input);
    filter.flush();
 
    if (session_logger_) {
        session_logger_->end_turn();
    }
    if (cancel_flag && *cancel_flag) { return 1; }
    return 0;
}
 
static std::string concat_user_echo(
    const std::vector<Message>& messages) {
    std::string echo;
    for (const auto& m : messages) {
        if (m.role != "user" || m.content.empty()) { continue; }
        if (!echo.empty()) { echo += '\n'; }
        echo += m.content;
    }
    return echo;
}
 
int AgentEngine::run_streaming(
    std::vector<Message> new_messages,
    TokenCallback on_token,
    void* user_data,
    int* cancel_flag)
{
    if (session_logger_) {
        session_logger_->log_user_input(concat_user_echo(new_messages));
    }
 
    StreamThinkFilter filter(on_token, user_data);
    if (session_logger_ && session_logger_->is_open()) {
        filter.set_raw_callback(
            SessionLogger::raw_token_callback,
            session_logger_);
    }
 
    struct Ctx {
        StreamThinkFilter* filter;
        int* cancel;
        AgentEngine* engine;
    };
    Ctx sctx{&filter, cancel_flag, this};
 
    EngineCallbacks cbs{};
    cbs.on_stream_chunk = [](const char* t, size_t l, void* ud) {
        auto* c = static_cast<Ctx*>(ud);
        if (c->cancel && *c->cancel) {
            c->engine->interrupt();
            return;
        }
        c->filter->on_token(t, l);
    };
    cbs.user_data = &sctx;
    set_callbacks(cbs);
 
    auto result = run_turn(std::move(new_messages));
    filter.flush();
 
    if (session_logger_) {
        session_logger_->end_turn();
    }
    if (cancel_flag && *cancel_flag) { return 1; }
    return 0;
}
 
void AgentEngine::clear_conversation() {
    conversation_.clear();
    logger->info("conversation cleared");
}
 
size_t AgentEngine::message_count() const {
    return conversation_.size();
}
 
const std::vector<Message>& AgentEngine::get_messages() const {
    return conversation_;
}
 
// ── Mid-generation user-message queue (gh#40, v2.1.10) ─────────
 
bool AgentEngine::queue_user_message(const std::string& message) {
    std::lock_guard lock(queue_mutex_);
    int cap = loop_config_.message_queue_capacity;
    if (cap < 0) { cap = 0; }
    if (user_message_queue_.size()
            >= static_cast<size_t>(cap)) {
        return false;
    }
    user_message_queue_.push_back(message);
    logger->info("queued mid-gen user message: depth={}",
                 user_message_queue_.size());
    return true;
}
 
size_t AgentEngine::user_message_queue_depth() const {
    std::lock_guard lock(queue_mutex_);
    return user_message_queue_.size();
}
 
void AgentEngine::clear_user_message_queue() {
    std::lock_guard lock(queue_mutex_);
    size_t dropped = user_message_queue_.size();
    user_message_queue_.clear();
    if (dropped > 0) {
        logger->info("cleared mid-gen queue: dropped={}", dropped);
    }
}
 
void AgentEngine::set_message_queue_capacity(int cap) {
    std::lock_guard lock(queue_mutex_);
    loop_config_.message_queue_capacity = cap < 0 ? 0 : cap;
}
 
std::optional<std::string>
AgentEngine::pop_queued_user_message() {
    std::lock_guard lock(queue_mutex_);
    if (user_message_queue_.empty()) {
        return std::nullopt;
    }
    std::string front = std::move(user_message_queue_.front());
    user_message_queue_.pop_front();
    return front;
}
 
void AgentEngine::fire_queue_consumed(const std::string& consumed,
                                      size_t remaining) {
    if (queue_observer_ != nullptr) {
        queue_observer_(
            consumed.c_str(), remaining, queue_observer_data_);
    }
}
 
void AgentEngine::set_queue_observer(
    void (*observer)(const char*, size_t, void*),
    void* user_data) {
    queue_observer_ = observer;
    queue_observer_data_ = user_data;
}
 
void AgentEngine::set_state_observer(
    void (*observer)(int, void*),
    void* user_data) {
    state_observer_ = observer;
    state_observer_data_ = user_data;
    response_generator_.set_state_observer(observer, user_data);
}
 
// ── Directive hooks (v2.0.2) ────────────────────────────────
 
ToolExecutorHooks AgentEngine::build_directive_hooks() {
    ToolExecutorHooks hooks;
    hooks.process_directives = [](
        LoopContext& ctx,
        const std::vector<const Directive*>& dirs,
        void* ud) -> DirectiveResult {
        return static_cast<AgentEngine*>(ud)
            ->directive_processor().process(ctx, dirs);
    };
    hooks.user_data = this;
    return hooks;
}
 
// ── Tier resolution (v2.0.2) ────────────────────────────────
 
void AgentEngine::set_tier_info(
    const std::string& name,
    const ChildContextInfo& info)
{
    tier_info_[name] = info;
}
 
bool AgentEngine::has_tier(const std::string& name) const {
    return tier_info_.count(name) > 0;
}
 
std::vector<std::string> AgentEngine::get_tier_allowed_tools(
    const std::string& name) const {
    auto it = tier_info_.find(name);
    if (it == tier_info_.end()) { return {}; }
    return it->second.allowed_tools;
}
 
const std::string& AgentEngine::tier_system_prompt(
    const std::string& name) const {
    static const std::string kEmpty;
    auto it = tier_info_.find(name);
    return it == tier_info_.end() ? kEmpty : it->second.system_prompt;
}
 
void AgentEngine::set_relay_single_delegate(const std::string& name) {
    relay_single_delegate_tiers_.insert(name);
}
 
void AgentEngine::set_handoff_rules(
    const std::unordered_map<std::string,
        std::vector<std::string>>& rules)
{
    handoff_rules_ = rules;
    wire_internal_tier_resolution();
}
 
ChildContextInfo AgentEngine::tri_resolve_tier(
    const std::string& name, void* ud) {
    auto* self = static_cast<AgentEngine*>(ud);
    auto it = self->tier_info_.find(name);
    ChildContextInfo info;
    if (it == self->tier_info_.end()) {
        info.valid = false;
    } else {
        info = it->second;
    }
    return info;
}
 
bool AgentEngine::tri_tier_exists(const std::string& name, void* ud) {
    auto* self = static_cast<AgentEngine*>(ud);
    return self->tier_info_.count(name) > 0;
}
 
std::vector<std::string> AgentEngine::tri_get_handoff_targets(
    const std::string& name, void* ud) {
    auto* self = static_cast<AgentEngine*>(ud);
    auto it = self->handoff_rules_.find(name);
    std::vector<std::string> result;
    if (it != self->handoff_rules_.end()) { result = it->second; }
    return result;
}
 
static std::string join_csv(const std::vector<std::string>& v) {
    std::string out;
    for (const auto& s : v) {
        if (!out.empty()) { out += ','; }
        out += s;
    }
    return out;
}
 
std::string AgentEngine::tri_get_tier_param(const std::string& name,
    const std::string& param, void* ud) {
    auto* self = static_cast<AgentEngine*>(ud);
    auto it = self->tier_info_.find(name);
    if (it == self->tier_info_.end()) { return ""; }
    const auto& info = it->second;
    std::string result;
    if (param == "explicit_completion") {
        result = info.explicit_completion ? "true" : "false";
    }
    if (param == "max_iterations" && info.max_iterations_override >= 0) {
        result = std::to_string(info.max_iterations_override);
    }
    if (param == "max_tool_calls_per_turn"
        && info.max_tool_calls_per_turn_override >= 0) {
        result = std::to_string(info.max_tool_calls_per_turn_override);
    }
    if (param == "max_consecutive_empty_turns"
        && info.max_consecutive_empty_turns_override >= 0) {
        result = std::to_string(info.max_consecutive_empty_turns_override);
    }
    if (param == "allowed_tools" && !info.allowed_tools.empty()) {
        result = join_csv(info.allowed_tools);
    }
    return result;
}
 
void AgentEngine::wire_internal_tier_resolution() {
    TierResolutionInterface tri;
    tri.resolve_tier = &AgentEngine::tri_resolve_tier;
    tri.tier_exists = &AgentEngine::tri_tier_exists;
    tri.get_handoff_targets = &AgentEngine::tri_get_handoff_targets;
    tri.get_tier_param = &AgentEngine::tri_get_tier_param;
    tri.user_data = this;
    set_tier_resolution(tri);
}
 
} // namespace entropic