switchyard_libsy/algorithms/util/

tool_signals.rs

// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

//! Tool-result context signals extracted from the conversation history.
//!
//! The extractor walks normalized messages, finds tool calls and results,
//! pattern-matches their text against a curated error table, and aggregates
//! conversation-history metrics used by [`crate::StageRouter`] and the
//! advisor gate's request-side guards.
//!
//! All logic is pure and deterministic — no I/O, no shared state.

#![allow(dead_code)]

use async_trait::async_trait;
use serde::Deserialize;
use serde_json::Value;
use switchyard_protocol::{ContentBlock, Request, Role};

use crate::{LibsyError, Result};

use crate::core::processor::{Event, Processor};
use crate::core::state::State;

// ─── severity constants ───────────────────────────────────────────────────────

const SOFT: f32 = 0.3;
const HARD: f32 = 0.7;
const CRITICAL: f32 = 1.0;

// ─── pattern table ────────────────────────────────────────────────────────────

/// (name, severity, lower-cased substrings — any hit fires the pattern)
static ERROR_PATTERNS: &[(&str, f32, &[&str])] = &[
    (
        "oom",
        CRITICAL,
        &["out of memory", "memoryerror", "cannot allocate memory"],
    ),
    (
        "connection_refused",
        CRITICAL,
        &[
            "connection refused",
            "connectionrefusederror",
            "econnrefused",
        ],
    ),
    ("traceback", HARD, &["traceback (most recent call last)"]),
    (
        "import_error",
        HARD,
        &["modulenotfounderror:", "importerror:", "no module named "],
    ),
    (
        "cmd_not_found",
        HARD,
        &["command not found", "not found\n", "/usr/bin/env: "],
    ),
    ("assertion", HARD, &["assertionerror"]),
    ("value_error", HARD, &["valueerror:"]),
    ("syntax_error", HARD, &["syntaxerror:"]),
    (
        "timeout",
        HARD,
        &[
            "timed out",
            "timeouterror",
            "timeout expired",
            "deadline exceeded",
        ],
    ),
    (
        "no_such_file",
        HARD,
        &[
            "filenotfounderror:",
            "no such file or directory",
            // Claude Code Read-tool miss. Anchored as "file does not exist" (not a
            // bare "does not exist", which fires on `ls` output and prose) — trace-
            // mined across 1006 local trajectories at 22 true / 2 false positives.
            "file does not exist",
        ],
    ),
    // SOFT: plain non-zero exit without a recognisable exception traceback.
    (
        "exit_nonzero",
        SOFT,
        &[
            "exit code 1",
            "exit code 2",
            "exit status 1",
            "returned non-zero",
            "exited with code",
        ],
    ),
];

static EDIT_TOOL_NAMES: &[&str] = &[
    "edit",
    "multiedit",
    "notebookedit",
    "str_replace",
    "str_replace_based_edit_tool",
    "apply_patch", // codex's edit tool
    "text_editor",
    "patch", // hermes's str_replace-style edit tool
];

static WRITE_TOOL_NAMES: &[&str] = &["write", "create_file", "new_file", "write_file"];

// Bash subcommand patterns. Lowercased; callers must lowercase the command
// before matching. Bucketed into write_count / edit_count alongside the
// dedicated `Write` / `Edit` tools.
static BASH_WRITE_PATTERNS: &[&str] = &[
    "cat >",
    "cat >>",
    "echo >",
    "echo >>",
    "tee ",
    "printf >",
    "printf >>",
    "> /",
    ">> /",
    "<< 'eof'",
    "<<eof",
    "<<'eof'",
    "<< eof",
];

/// Python file-write expressions, which only indicate a write when an
/// interpreter is running them rather than a search looking for them.
static PYTHON_WRITE_PATTERNS: &[&str] = &["write_text(", "writelines(", ".write("];

static BASH_EDIT_PATTERNS: &[&str] = &[
    "sed -i",
    "sed --in-place",
    "awk -i inplace",
    "awk 'inplace=1'",
    "patch ",
    "patch -p",
    "perl -i",
    "perl -p -i",
    "perl -pi",
];

// Read-like Bash inspections. Match only when none of the write/edit patterns
// fire (redirection / in-place edit trumps the read intent of the command).
static BASH_READ_PATTERNS: &[&str] = &[
    "cat /", "cat ./", "cat ../", "grep ", "ls ", "ls -", "find ", "head ", "tail ", "wc ",
    "diff ", "which ", "ps ", "df ", "du ", "stat ", "file ", "less ", "more ",
];

static READ_TOOL_NAMES: &[&str] = &["read", "view", "read_file", "search_files"];

// Planning / scratchpad tool calls — investigative (non-producing) activity.
// `update_plan` is codex's equivalent of `todowrite`.
static PLAN_TOOL_NAMES: &[&str] = &["todowrite", "todo_write", "todo", "update_plan"];

// Tool names that route through Bash-command pattern matching. `bash` is
// claude-code's name; `shell_command` is codex's; `shell` / `local_shell_call`
// are seen on some OpenAI-derived harnesses; `terminal` is hermes's (it carries
// a `command` arg like the others, so its intent comes from the pattern match).
static BASH_TOOL_NAMES: &[&str] = &[
    "bash",
    "shell_command",
    "shell",
    "local_shell_call",
    "terminal",
    "exec_command", // codex
];

// Prefer false negatives: tests_passed routes the picker to EFFICIENT, so a false
// positive would drop tier on an unfinished task.
static TEST_PASS_PHRASES: &[&str] = &[
    " passed",
    "passed in",
    "tests passed",
    "all tests passed",
    "test ok",
    "test result: ok",
    "passed.\n",
    "tests pass",
    "\nok ", // go test; newline-anchored to avoid "...lookup..." mid-text
    "✓ ",
];

// Literal failure phrases that cannot appear inside a clean run. Substring
// matched as-is. Patterns that pair with a count (e.g. "failed", "errors")
// are handled separately by `has_nonzero_failure_count` so "0 failed" /
// "0 errors" do not trigger a false negative.
static TEST_FAILURE_LITERAL: &[&str] = &["✗ ", "fatal:", "assertionerror", "error:"];

// Count-prefixed failure keywords. Trip only when a nonzero integer precedes
// the keyword (modulo whitespace), so cargo's "0 failed" and go's
// "0 errors" summaries on a clean run are not misread as failures.
static NUMERIC_FAILURE_KEYWORDS: &[&str] = &["failed", "failure", "failures", "errors", "error"];

/// Default sliding-window size for `recent_*` counts and windowed severity.
///
/// A short horizon captures "what is the agent doing right now" while keeping
/// signals sticky — an error or stall persists a few recovery turns instead of
/// flickering off the moment one clean result lands. Override per request by
/// passing a window to [`ToolSignals::from_request`].
pub const DEFAULT_RECENT_WINDOW: usize = 3;

/// Exact tool-name semantics added to the stage router's built-in vocabulary.
///
/// Matching is ASCII case-insensitive. These lists are additive: built-in tool
/// names cannot be reclassified.
#[derive(Clone, Debug, Default, Deserialize, PartialEq, Eq)]
#[serde(default, deny_unknown_fields)]
pub struct ToolSemantics {
    /// Read-only lookup or inspection tools.
    pub observe: Vec<String>,
    /// Tools that change task or external state.
    pub mutate: Vec<String>,
    /// Explicit planning or task-decomposition tools.
    pub plan: Vec<String>,
    /// Tools that demonstrate new forward activity without favoring either tier.
    pub new: Vec<String>,
}

impl ToolSemantics {
    /// Rejects ambiguous mappings and attempts to reclassify built-in tools.
    pub fn validate(&self) -> Result<()> {
        let mut seen: Vec<(String, &'static str)> = Vec::new();
        for (category, names) in [
            ("observe", &self.observe),
            ("mutate", &self.mutate),
            ("plan", &self.plan),
            ("new", &self.new),
        ] {
            for name in names {
                if name.trim().is_empty() {
                    return Err(tool_semantics_error(format!(
                        "tool_semantics.{category} contains an empty tool name"
                    )));
                }
                let normalized = name.to_ascii_lowercase();
                if is_builtin_tool_name(&name.to_lowercase()) {
                    return Err(tool_semantics_error(format!(
                        "tool {name:?} already has built-in semantics and cannot be reclassified"
                    )));
                }
                if let Some((_, previous)) = seen.iter().find(|(seen, _)| seen == &normalized) {
                    return Err(tool_semantics_error(format!(
                        "tool {name:?} appears in both tool_semantics.{previous} and tool_semantics.{category}"
                    )));
                }
                seen.push((normalized, category));
            }
        }
        Ok(())
    }

    fn classify(&self, name: &str) -> Option<ToolSemantic> {
        if contains_name(&self.observe, name) {
            Some(ToolSemantic::Observe)
        } else if contains_name(&self.mutate, name) {
            // The stage scorer treats writes and edits identically. Custom
            // mutations use the write counter to preserve the public signal shape.
            Some(ToolSemantic::Mutate(MutationKind::Write))
        } else if contains_name(&self.plan, name) {
            Some(ToolSemantic::Plan)
        } else if contains_name(&self.new, name) {
            Some(ToolSemantic::New)
        } else {
            None
        }
    }
}

fn contains_name(names: &[String], candidate: &str) -> bool {
    names
        .iter()
        .any(|name| name.eq_ignore_ascii_case(candidate))
}

fn tool_semantics_error(message: String) -> LibsyError {
    LibsyError::AlgorithmError { message }
}

// ─── output type ─────────────────────────────────────────────────────────────

/// Tool-execution signals extracted from a normalized [`Request`].
///
/// A request-side processor stores these signals in [`State`](crate::State) for
/// [`crate::StageRouter`] and its classifier to consume. The advisor gate's
/// request-side guards read the conversation-shape counts directly via
/// [`ToolSignals::from_request`].
#[derive(Clone, Debug, Default)]
pub struct ToolSignals {
    /// Max severity across the recent window (last `recent_window` tool results):
    /// `0.0` clean · `0.3` soft (exit_nonzero) · `0.7` hard · `1.0` critical.
    /// Windowed so an error persists through the recovery turns instead of clearing
    /// the instant the next result is clean.
    pub severity: f32,
    /// Consecutive clean tool results back from the most recent. `0` if the last failed.
    pub no_error_streak: u32,
    /// Total edit-style tool calls in the request.
    pub edit_count: u32,
    /// Total write-style tool calls in the request.
    pub write_count: u32,
    /// Read-type calls (Read tool + read-like Bash). Used by the build-pit gate.
    pub read_count: u32,
    /// TodoWrite / planning tool calls. Investigative (non-producing) activity —
    /// recent todowrites distinguish `exploring` from `spinning` in the scorer.
    pub todowrite_count: u32,
    /// Edit-type calls within the configured recent window (default: [`DEFAULT_RECENT_WINDOW`]).
    pub recent_edit_count: u32,
    /// Write-type calls within the configured recent window (default: [`DEFAULT_RECENT_WINDOW`]).
    pub recent_write_count: u32,
    /// Read-type calls within the configured recent window (default: [`DEFAULT_RECENT_WINDOW`]).
    pub recent_read_count: u32,
    /// TodoWrite calls within the configured recent window (default: [`DEFAULT_RECENT_WINDOW`]).
    pub recent_todowrite_count: u32,
    /// Configured `new` tool calls across the full request history.
    pub new_count: u32,
    /// Configured `new` tool calls within the recent window.
    pub recent_new_count: u32,
    /// Consecutive trailing tool calls in the `Unknown` category (no Write/Edit/Read/
    /// Plan match). Surfaced in the classifier state summary; not scored directly.
    pub pure_bash_streak: u32,
    /// At least one of the last three tool results matched a test-pass pattern.
    pub tests_passed: bool,
    /// Total `ToolResult` blocks, counted per block (a message batching N
    /// results contributes N) and including empty-content results.
    pub tool_result_count: u32,
    /// Messages with `Role::Assistant`, unlike [`ToolSignals::turn_depth`],
    /// which counts every message regardless of role.
    pub assistant_turn_count: u32,
    /// Message-count proxy for turn depth. Wire-format dependent (Anthropic batches
    /// tool results into fewer messages than OpenAI-chat), so gates keyed on it are
    /// approximate across request origins.
    pub turn_depth: u32,
    /// The request carries a context-compaction summary (the agent's context was
    /// summarised after overflowing). Compaction resets the router's accumulated
    /// signals, so a task that was on the strong tier de-escalates back to weak — the
    /// picker uses this to force + hold the strong tier. Self-latching: the summary
    /// stays in the context prefix on every subsequent turn.
    pub compacted: bool,
}

impl ToolSignals {
    /// Extracts tool and activity signals from `request`.
    ///
    /// `window_size` limits recent counters to the newest tool results. `None`
    /// uses [`DEFAULT_RECENT_WINDOW`].
    pub fn from_request(request: &Request, window_size: Option<usize>) -> Self {
        Self::from_request_with_semantics(request, window_size, &ToolSemantics::default())
    }

    /// Extracts signals using the built-in vocabulary plus additive semantics.
    pub fn from_request_with_semantics(
        request: &Request,
        window_size: Option<usize>,
        semantics: &ToolSemantics,
    ) -> Self {
        extract_tool_signals_with_window_and_semantics(
            request,
            window_size.unwrap_or(DEFAULT_RECENT_WINDOW),
            semantics,
        )
    }
}

// `command` is the lowercased Bash command line; None for non-Bash tools.
#[derive(Debug, Clone)]
struct ObservedToolCall {
    name: String,
    command: Option<String>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum MutationKind {
    Write,
    Edit,
}

/// Domain-neutral meaning assigned to an observed tool call.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ToolSemantic {
    Mutate(MutationKind),
    Observe,
    Plan,
    New,
    Unknown,
}

/// Request-side processor that extracts tool-result signals from each request
/// and stores them on the request `State` for downstream routing.
#[derive(Debug, Clone)]
pub struct ToolSignalProcessor {
    /// Number of trailing tool results the `recent_*` counts and windowed
    /// severity are computed over.
    pub recent_window: usize,
    /// Route-scoped additions to the built-in tool vocabulary.
    pub tool_semantics: ToolSemantics,
}

impl Default for ToolSignalProcessor {
    fn default() -> Self {
        Self {
            recent_window: DEFAULT_RECENT_WINDOW,
            tool_semantics: ToolSemantics::default(),
        }
    }
}

#[async_trait]
impl Processor<State> for ToolSignalProcessor {
    async fn process(&self, state: &mut State, event: Event<'_>) -> Result<()> {
        if let Event::Request { request: req, .. } = event {
            let tool_signal = ToolSignals::from_request_with_semantics(
                req,
                Some(self.recent_window),
                &self.tool_semantics,
            );
            state.tool_signals = Some(tool_signal);
        }
        Ok(())
    }
}

fn classify_tool_call(name: &str, command: Option<&str>) -> ToolSemantic {
    classify_tool_call_with_semantics(name, command, &ToolSemantics::default())
}

fn classify_tool_call_with_semantics(
    name: &str,
    command: Option<&str>,
    semantics: &ToolSemantics,
) -> ToolSemantic {
    // Built-in names and Bash command inference take precedence over route-scoped mappings.
    let lower = name.to_lowercase();
    if WRITE_TOOL_NAMES.contains(&lower.as_str()) {
        return ToolSemantic::Mutate(MutationKind::Write);
    }
    if EDIT_TOOL_NAMES.contains(&lower.as_str()) {
        return ToolSemantic::Mutate(MutationKind::Edit);
    }
    if READ_TOOL_NAMES.contains(&lower.as_str()) {
        return ToolSemantic::Observe;
    }
    if PLAN_TOOL_NAMES.contains(&lower.as_str()) {
        return ToolSemantic::Plan;
    }
    if BASH_TOOL_NAMES.contains(&lower.as_str())
        && let Some(cmd) = command
    {
        // Write/edit redirection trumps read-like operands.
        if BASH_WRITE_PATTERNS.iter().any(|p| cmd.contains(p)) {
            return ToolSemantic::Mutate(MutationKind::Write);
        }
        if cmd.contains("python") && PYTHON_WRITE_PATTERNS.iter().any(|p| cmd.contains(p)) {
            return ToolSemantic::Mutate(MutationKind::Write);
        }
        if BASH_EDIT_PATTERNS.iter().any(|p| cmd.contains(p)) {
            return ToolSemantic::Mutate(MutationKind::Edit);
        }
        if BASH_READ_PATTERNS.iter().any(|p| cmd.contains(p)) {
            return ToolSemantic::Observe;
        }
    }
    semantics.classify(name).unwrap_or(ToolSemantic::Unknown)
}

fn is_builtin_tool_name(lower: &str) -> bool {
    WRITE_TOOL_NAMES.contains(&lower)
        || EDIT_TOOL_NAMES.contains(&lower)
        || READ_TOOL_NAMES.contains(&lower)
        || PLAN_TOOL_NAMES.contains(&lower)
        || BASH_TOOL_NAMES.contains(&lower)
}

// ─── extraction entry point ───────────────────────────────────────────────────

/// Extract all tool-execution signals from a normalized [`Request`].
///
/// Returns [`ToolSignals::default()`] when the message history contains no tool
/// activity, so callers can always inspect the signal fields.
fn extract_tool_signals_with_window(request: &Request, recent_window: usize) -> ToolSignals {
    extract_tool_signals_with_window_and_semantics(
        request,
        recent_window,
        &ToolSemantics::default(),
    )
}

fn extract_tool_signals_with_window_and_semantics(
    request: &Request,
    recent_window: usize,
    semantics: &ToolSemantics,
) -> ToolSignals {
    // Read the decoded conversation, not the raw body: every inbound format lands
    // in the same shape here, so the signals do not depend on knowing which one it
    // arrived as.
    let messages = &request.llm_request.messages;
    let mut tool_texts: Vec<String> = Vec::new();
    let mut tool_calls: Vec<ObservedToolCall> = Vec::new();
    let mut compacted = false;
    let mut tool_result_count = 0usize;
    let mut assistant_turn_count = 0usize;

    for message in messages {
        if message.role == Role::Assistant {
            assistant_turn_count += 1;
        }
        for block in &message.content {
            match block {
                ContentBlock::ToolCall(call) => {
                    tool_calls.push(ObservedToolCall {
                        name: call.name.clone(),
                        command: command_of(&call.arguments),
                    });
                }
                ContentBlock::ToolResult(result) => {
                    // Before the empty-text filter: empty results still count.
                    tool_result_count += 1;
                    let text = result
                        .content
                        .iter()
                        .filter_map(text_of)
                        .collect::<Vec<_>>()
                        .join("\n");
                    if !text.is_empty() {
                        tool_texts.push(text);
                    }
                }
                // Compaction is detected anywhere in the conversation: the summary
                // stays in the prefix on every later turn, so this self-latches
                // once it fires.
                ContentBlock::Text { text } => {
                    compacted |= text.to_lowercase().contains(COMPACTION_MARKER);
                }
                _ => {}
            }
        }
    }

    let mut signal = build_signal(
        tool_texts,
        tool_calls,
        messages.len() as u32,
        recent_window,
        semantics,
    );
    signal.compacted = compacted;
    signal.tool_result_count = u32::try_from(tool_result_count).unwrap_or(u32::MAX);
    signal.assistant_turn_count = u32::try_from(assistant_turn_count).unwrap_or(u32::MAX);
    signal
}

/// Distinctive preamble Claude Code injects as a user message when it compacts an
/// overflowed context. Matched case-insensitively; normal task text never contains it.
const COMPACTION_MARKER: &str = "session is being continued";

/// The shell command a tool call carries, when it has one. Harnesses name the
/// field `command`; anything else is a tool whose category comes from its name.
fn command_of(arguments: &Value) -> Option<String> {
    // the Responses wire format sends arguments as a JSON string, not an object
    let decoded = arguments
        .as_str()
        .and_then(|raw| serde_json::from_str::<Value>(raw).ok());
    let object = decoded.as_ref().unwrap_or(arguments);

    ["command", "cmd", "input"]
        .iter()
        .filter_map(|key| object.get(*key))
        .find_map(command_text)
}

/// A command field as lowercase text, from a string or an argv array.
fn command_text(value: &Value) -> Option<String> {
    match value {
        Value::String(text) => Some(text.to_lowercase()),
        Value::Array(parts) => {
            let joined = parts
                .iter()
                .filter_map(Value::as_str)
                .collect::<Vec<_>>()
                .join(" ");
            (!joined.is_empty()).then(|| joined.to_lowercase())
        }
        _ => None,
    }
}

/// Text carried by a content block, ignoring the non-textual kinds.
fn text_of(block: &ContentBlock) -> Option<&str> {
    match block {
        ContentBlock::Text { text } | ContentBlock::Refusal { text } => Some(text.as_str()),
        _ => None,
    }
}

fn build_signal(
    tool_texts: Vec<String>,
    tool_calls: Vec<ObservedToolCall>,
    turn_depth: u32,
    recent_window: usize,
    semantics: &ToolSemantics,
) -> ToolSignals {
    // Windowed severity: take the MAX severity across the last `recent_window` tool
    // results rather than only the last one. An error's severity then persists for
    // the recent window and decays out of it — parallel to the windowed `recent_*`
    // counts — so a fix written a couple of turns after an error still routes on the
    // error signal instead of the router flapping straight back to the weak tier.
    let sev_start = tool_texts.len().saturating_sub(recent_window.max(1));
    let mut severity = 0.0f32;
    for text in &tool_texts[sev_start..] {
        let (sev, _patterns) = classify_text(text);
        if sev > severity {
            severity = sev;
        }
    }

    let no_error_streak = compute_no_error_streak(&tool_texts);

    // Single pass: cumulative + sliding-window counters together. Also tracks
    // the trailing pure-bash streak (consecutive `Unknown` calls back
    // from the end) — the build-pit proxy.
    let recent_start = tool_calls.len().saturating_sub(recent_window);
    let mut write_count = 0u32;
    let mut edit_count = 0u32;
    let mut read_count = 0u32;
    let mut todowrite_count = 0u32;
    let mut recent_write_count = 0u32;
    let mut recent_edit_count = 0u32;
    let mut recent_read_count = 0u32;
    let mut recent_todowrite_count = 0u32;
    let mut new_count = 0u32;
    let mut recent_new_count = 0u32;
    let mut pure_bash_streak = 0u32;
    let mut streak_open = true;
    for (i, tc) in tool_calls.iter().enumerate().rev() {
        let cat = classify_tool_call_with_semantics(&tc.name, tc.command.as_deref(), semantics);
        if streak_open {
            if matches!(cat, ToolSemantic::Unknown) {
                pure_bash_streak += 1;
            } else {
                streak_open = false;
            }
        }
        match cat {
            ToolSemantic::Mutate(MutationKind::Write) => {
                write_count += 1;
                if i >= recent_start {
                    recent_write_count += 1;
                }
            }
            ToolSemantic::Mutate(MutationKind::Edit) => {
                edit_count += 1;
                if i >= recent_start {
                    recent_edit_count += 1;
                }
            }
            ToolSemantic::Observe => {
                read_count += 1;
                if i >= recent_start {
                    recent_read_count += 1;
                }
            }
            ToolSemantic::Plan => {
                todowrite_count += 1;
                if i >= recent_start {
                    recent_todowrite_count += 1;
                }
            }
            ToolSemantic::New => {
                new_count += 1;
                if i >= recent_start {
                    recent_new_count += 1;
                }
            }
            ToolSemantic::Unknown => {}
        }
    }

    let tests_passed = detect_tests_passed(&tool_texts, recent_window);

    ToolSignals {
        severity,
        no_error_streak,
        edit_count,
        write_count,
        read_count,
        todowrite_count,
        recent_edit_count,
        recent_write_count,
        recent_read_count,
        recent_todowrite_count,
        new_count,
        recent_new_count,
        pure_bash_streak,
        tests_passed,
        turn_depth,
        // Set by extract_tool_signals_with_window after the format-specific extract,
        // which scans all message contents for the compaction marker and tallies
        // the raw conversation-shape counts.
        tool_result_count: 0,
        assistant_turn_count: 0,
        compacted: false,
    }
}

// ─── pure helpers ─────────────────────────────────────────────────────────────

/// Normalise a JSON tool-result content value to a plain string.
fn content_to_text(content: Option<&Value>) -> Option<String> {
    match content? {
        Value::String(s) => Some(s.clone()),
        Value::Array(blocks) => {
            let parts: Vec<&str> = blocks
                .iter()
                .filter_map(|b| {
                    b.as_object()
                        .filter(|o| o.get("type").and_then(Value::as_str) == Some("text"))
                        .and_then(|o| o.get("text"))
                        .and_then(Value::as_str)
                })
                .collect();
            if parts.is_empty() {
                None
            } else {
                Some(parts.join("\n"))
            }
        }
        _ => None,
    }
}

/// Match `text` against the error pattern table.
///
/// Returns `(max_severity, matched_pattern_names)`.
pub(crate) fn classify_text(text: &str) -> (f32, Vec<String>) {
    let lower = text.to_lowercase();
    let mut patterns = Vec::new();
    let mut severity: f32 = 0.0;
    for (name, sev, substrings) in ERROR_PATTERNS {
        if substrings.iter().any(|sub| lower.contains(sub)) {
            patterns.push(name.to_string());
            severity = severity.max(*sev);
        }
    }
    (severity, patterns)
}

fn compute_no_error_streak(tool_texts: &[String]) -> u32 {
    let mut streak = 0u32;
    for text in tool_texts.iter().rev() {
        let (sev, _) = classify_text(text);
        if sev > 0.0 {
            break;
        }
        streak += 1;
    }
    streak
}

fn detect_tests_passed(tool_texts: &[String], recent_window: usize) -> bool {
    let start = tool_texts.len().saturating_sub(recent_window.max(1));
    tool_texts[start..].iter().any(|text| {
        let lower = text.to_lowercase();
        TEST_PASS_PHRASES.iter().any(|p| lower.contains(p))
            && !TEST_FAILURE_LITERAL.iter().any(|p| lower.contains(p))
            && !has_nonzero_failure_count(&lower)
    })
}

// True iff `lower` contains a `NUMERIC_FAILURE_KEYWORDS` token preceded
// (modulo whitespace) by a nonzero integer. The "modulo whitespace" lets
// "1 failed", "1\nfailed", and "1  failed" all trip; the nonzero guard
// keeps cargo's "0 failed" / go's "0 errors" / pytest's "0 errors in"
// summaries from being misread as failures on a clean run.
fn has_nonzero_failure_count(lower: &str) -> bool {
    for kw in NUMERIC_FAILURE_KEYWORDS {
        let mut cursor = 0usize;
        while let Some(rel) = lower[cursor..].find(kw) {
            let kw_start = cursor + rel;
            let kw_end = kw_start + kw.len();
            // Word boundary AFTER the keyword — "errors" mid-word (e.g.
            // "errored") shouldn't count as a failure-count site.
            let boundary_after = lower[kw_end..]
                .chars()
                .next()
                .is_none_or(|c| !c.is_ascii_alphanumeric());
            if boundary_after {
                let prefix = &lower[..kw_start];
                let trimmed = prefix.trim_end_matches(|c: char| c.is_whitespace());
                let digits_rev: String = trimmed
                    .chars()
                    .rev()
                    .take_while(|c| c.is_ascii_digit())
                    .collect();
                if !digits_rev.is_empty() && digits_rev.chars().any(|d| d != '0') {
                    return true;
                }
            }
            cursor = kw_start + kw.len();
        }
    }
    false
}

// ─── tests ───────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;
    use crate::algorithms::util::stage::score_signal;
    use serde_json::json;
    use switchyard_protocol::{ContentBlock, LlmRequest, Message, Role, ToolCall, ToolResult};

    fn with_messages(messages: Vec<Message>) -> Request {
        Request {
            llm_request: LlmRequest {
                messages,
                ..LlmRequest::default()
            },
            raw_request: None,
            metadata: None,
        }
    }

    // assistant message with a single named tool call
    fn tc(name: &str) -> Message {
        Message {
            role: Role::Assistant,
            content: vec![ContentBlock::ToolCall(ToolCall {
                id: String::new(),
                name: name.to_string(),
                arguments: json!({}),
            })],
        }
    }

    // assistant Bash message carrying `command`
    fn bash(command: &str) -> Message {
        Message {
            role: Role::Assistant,
            content: vec![ContentBlock::ToolCall(ToolCall {
                id: String::new(),
                name: "Bash".to_string(),
                arguments: json!({"command": command}),
            })],
        }
    }

    // a tool result message (goes in a user-role message, as in Anthropic's normalised form)
    fn tr(text: &str) -> Message {
        Message {
            role: Role::User,
            content: vec![ContentBlock::ToolResult(ToolResult {
                tool_call_id: String::new(),
                content: vec![ContentBlock::Text {
                    text: text.to_string(),
                }],
                is_error: None,
            })],
        }
    }

    #[test]
    fn clean_text_has_zero_severity() {
        let (sev, patterns) = classify_text("everything went fine");
        assert_eq!(sev, 0.0);
        assert!(patterns.is_empty());
    }

    #[test]
    fn traceback_is_hard() {
        let (sev, patterns) = classify_text("Traceback (most recent call last):\n  ValueError");
        assert_eq!(sev, HARD);
        assert!(patterns.contains(&"traceback".to_string()));
    }

    #[test]
    fn oom_is_critical() {
        let (sev, _) = classify_text("Out of memory: kill process 1234");
        assert_eq!(sev, CRITICAL);
    }

    #[test]
    fn severity_is_max_across_patterns() {
        // exit_nonzero (SOFT) + traceback (HARD) → HARD.
        let (sev, _) = classify_text("exit code 1\nTraceback (most recent call last):");
        assert_eq!(sev, HARD);
    }

    #[test]
    fn file_does_not_exist_is_hard() {
        // Claude Code Read-tool miss. Trace-mined addition (22 true / 2 false positives).
        let (sev, patterns) =
            classify_text("Error: File does not exist. Note: current working directory is /app.");
        assert_eq!(sev, HARD);
        assert!(patterns.contains(&"no_such_file".to_string()));
    }

    #[test]
    fn bare_does_not_exist_stays_clean() {
        // Precision guard: only the anchored "file does not exist" fires, so a bare
        // "does not exist" in prose or directory output must not trip a false error.
        let (sev, _) = classify_text("The directory does not exist yet, creating it now.");
        assert_eq!(sev, 0.0);
    }

    #[test]
    fn no_error_streak_all_clean() {
        let texts = vec!["ok".to_string(), "all good".to_string()];
        assert_eq!(compute_no_error_streak(&texts), 2);
    }

    #[test]
    fn no_error_streak_stops_at_error() {
        let texts = vec![
            "Traceback (most recent call last):".to_string(),
            "ok".to_string(),
            "ok".to_string(),
        ];
        assert_eq!(compute_no_error_streak(&texts), 2);
    }

    #[test]
    fn tests_passed_detects_pytest_output() {
        assert!(detect_tests_passed(
            &["====== 5 passed in 0.12s ======".to_string()],
            DEFAULT_RECENT_WINDOW
        ));
    }

    #[test]
    fn tests_passed_ignores_partial_failures() {
        assert!(!detect_tests_passed(
            &["2 failed, 5 passed in 0.56s".to_string()],
            DEFAULT_RECENT_WINDOW
        ));
    }

    #[test]
    fn severity_is_windowed_over_recent_results() {
        // An error two results back, then two clean results.
        let request = with_messages(vec![
            tr("Traceback (most recent call last):\n  ValueError"),
            tr("ok"),
            tr("ok"),
        ]);
        // window covers the error → severity persists (max over the window)
        assert_eq!(extract_tool_signals_with_window(&request, 3).severity, HARD);
        // window of 1 sees only the last (clean) result → severity has decayed out
        assert_eq!(extract_tool_signals_with_window(&request, 1).severity, 0.0);
    }

    #[test]
    fn extract_openai_chat_tool_results() {
        let request = with_messages(vec![
            Message::text(Role::User, "do something"),
            tc("Edit"),
            tr("Traceback (most recent call last):\n  ValueError"),
        ]);
        let sig = ToolSignals::from_request(&request, None);
        assert_eq!(sig.severity, HARD);
        assert_eq!(sig.edit_count, 1);
        assert_eq!(sig.turn_depth, 3);
    }

    #[test]
    fn extract_anthropic_tool_results() {
        let request = with_messages(vec![tr("Traceback (most recent call last):\n  ValueError")]);
        let sig = ToolSignals::from_request(&request, None);
        assert_eq!(sig.severity, HARD);
    }

    #[test]
    fn extract_responses_api_tool_results() {
        let request = with_messages(vec![tc("Write"), tr("file written successfully")]);
        let sig = ToolSignals::from_request(&request, None);
        assert_eq!(sig.severity, 0.0);
        assert_eq!(sig.write_count, 1);
    }

    #[test]
    fn conversation_counts_are_per_block_and_role_aware() {
        // A batched user message (Anthropic shape) contributes one count per
        // ToolResult block, empty-content results included. assistant_turn_count
        // tracks Role::Assistant only, while turn_depth counts every message.
        let result = |content: Vec<ContentBlock>| {
            ContentBlock::ToolResult(ToolResult {
                tool_call_id: String::new(),
                content,
                is_error: None,
            })
        };
        let request = with_messages(vec![
            Message::text(Role::User, "do something"),
            Message::text(Role::Assistant, "working"),
            Message {
                role: Role::User,
                content: vec![
                    result(vec![ContentBlock::Text {
                        text: "ok".to_string(),
                    }]),
                    result(Vec::new()),
                ],
            },
            tc("Bash"),
        ]);
        let sig = ToolSignals::from_request(&request, None);
        assert_eq!(sig.tool_result_count, 2);
        assert_eq!(sig.assistant_turn_count, 2);
        assert_eq!(sig.turn_depth, 4);
    }

    #[test]
    fn recent_window_counts_only_last_default_window_tool_calls() {
        // 5 writes + 1 edit at the end → the default window (3) should see
        // the last 3 calls: 1 edit + 2 writes (not all 6 calls).
        let request = with_messages(vec![
            tc("Write"),
            tr("ok"),
            tc("Write"),
            tr("ok"),
            tc("Write"),
            tr("ok"),
            tc("Write"),
            tr("ok"),
            tc("Write"),
            tr("ok"),
            tc("Edit"),
            tr("ok"),
        ]);
        let sig = ToolSignals::from_request(&request, None);
        assert_eq!(sig.write_count, 5);
        assert_eq!(sig.edit_count, 1);
        assert_eq!(sig.recent_write_count, 2);
        assert_eq!(sig.recent_edit_count, 1);
    }

    #[test]
    fn codex_apply_patch_counts_as_an_edit() {
        let request = with_messages(vec![tc("apply_patch"), tr("Success. Updated the file")]);
        let sig = ToolSignals::from_request(&request, None);
        assert_eq!(sig.edit_count, 1);
        assert_eq!(sig.recent_edit_count, 1);
    }

    fn exec_command(cmd: Value) -> Message {
        Message {
            role: Role::Assistant,
            content: vec![ContentBlock::ToolCall(ToolCall {
                id: String::new(),
                name: "exec_command".to_string(),
                arguments: cmd,
            })],
        }
    }

    #[test]
    fn codex_exec_command_is_classified() {
        // arguments arrive as a JSON string, with the command under `cmd`
        let args = json!(r#"{"cmd":"sed -i s/a/b/ src/lib.rs","workdir":"/x"}"#);
        let request = with_messages(vec![exec_command(args), tr("ok")]);
        assert_eq!(
            ToolSignals::from_request(&request, None).recent_edit_count,
            1
        );
    }

    #[test]
    fn python_write_expressions_need_a_python_command() {
        let write = with_messages(vec![
            exec_command(json!({"cmd": "python3 - <<'PY'\np.write_text(s)\nPY"})),
            tr("ok"),
        ]);
        assert_eq!(
            ToolSignals::from_request(&write, None).recent_write_count,
            1
        );

        let search = with_messages(vec![
            exec_command(json!({"cmd": "grep -R '.write(' src"})),
            tr("ok"),
        ]);
        assert_eq!(
            ToolSignals::from_request(&search, None).recent_write_count,
            0
        );
    }

    #[test]
    fn recent_window_size_is_caller_overridable() {
        // Same six tool calls (1 edit at the end, 5 writes before).
        // With recent_window=3 → recent_writes=2, recent_edits=1.
        // With recent_window=6 → recent_writes=5, recent_edits=1 (all calls).
        let request = with_messages(vec![
            tc("Write"),
            tr("ok"),
            tc("Write"),
            tr("ok"),
            tc("Write"),
            tr("ok"),
            tc("Write"),
            tr("ok"),
            tc("Write"),
            tr("ok"),
            tc("Edit"),
            tr("ok"),
        ]);
        let narrow = extract_tool_signals_with_window(&request, 3);
        assert_eq!(narrow.recent_write_count, 2);
        assert_eq!(narrow.recent_edit_count, 1);

        let wide = extract_tool_signals_with_window(&request, 6);
        assert_eq!(wide.recent_write_count, 5);
        assert_eq!(wide.recent_edit_count, 1);
    }

    #[test]
    fn compaction_marker_sets_compacted() {
        // The compaction summary is a user message carrying Claude Code's preamble.
        let request = with_messages(vec![
            Message::text(
                Role::User,
                "This session is being continued from a previous conversation that ran out of context.",
            ),
            bash("ls"),
        ]);
        assert!(ToolSignals::from_request(&request, None).compacted);
    }

    #[test]
    fn no_compaction_marker_stays_uncompacted() {
        let request = with_messages(vec![
            Message::text(Role::User, "Write a script that parses the log file."),
            bash("ls"),
        ]);
        assert!(!ToolSignals::from_request(&request, None).compacted);
    }

    #[test]
    fn bash_heredoc_counts_as_write() {
        // Claude Code's pattern on TB 2.0 — write a scratch file via heredoc.
        let request = with_messages(vec![bash("cat > /tmp/test.py <<'EOF'\nprint(1)\nEOF")]);
        let sig = ToolSignals::from_request(&request, None);
        assert_eq!(
            sig.write_count, 1,
            "Bash heredoc should bucket into write_count"
        );
        assert_eq!(sig.edit_count, 0);
    }

    #[test]
    fn bash_sed_inplace_counts_as_edit() {
        let request = with_messages(vec![bash("sed -i 's/foo/bar/g' /app/file.py")]);
        let sig = ToolSignals::from_request(&request, None);
        assert_eq!(
            sig.edit_count, 1,
            "Bash sed -i should bucket into edit_count"
        );
        assert_eq!(sig.write_count, 0);
    }

    #[test]
    fn bash_non_mutating_does_not_count() {
        // ls, cat, grep — should not increment either counter.
        let request = with_messages(vec![bash("ls -la /app"), bash("cat /app/main.py")]);
        let sig = ToolSignals::from_request(&request, None);
        assert_eq!(sig.write_count, 0);
        assert_eq!(sig.edit_count, 0);
    }

    #[test]
    fn tests_passed_detects_pytest_with_failure_block() {
        // Mixed pytest run: 2 failed + 5 passed → NOT considered tests_passed.
        assert!(!detect_tests_passed(
            &["2 failed, 5 passed in 0.56s".to_string()],
            DEFAULT_RECENT_WINDOW
        ));
    }

    #[test]
    fn tests_passed_accepts_cargo_clean_summary() {
        // Cargo's clean-run summary contains "0 failed" — must not trip the
        // failure list (regression: previously substring-matched "failed").
        assert!(detect_tests_passed(
            &["running 3 tests\ntest result: ok. 3 passed; 0 failed; 0 ignored".to_string()],
            DEFAULT_RECENT_WINDOW
        ));
    }

    #[test]
    fn tests_passed_rejects_cargo_real_failure() {
        // Cargo's actual-failure summary: nonzero count before "failed".
        assert!(!detect_tests_passed(
            &["running 3 tests\ntest result: FAILED. 2 passed; 1 failed; 0 ignored".to_string()],
            DEFAULT_RECENT_WINDOW
        ));
    }

    #[test]
    fn tests_passed_accepts_go_clean_summary() {
        // Go test's clean-run "0 errors" must not trip (regression).
        assert!(detect_tests_passed(
            &["ok  github.com/foo/bar\t0.012s (5 passed, 0 errors)".to_string()],
            DEFAULT_RECENT_WINDOW
        ));
    }

    #[test]
    fn tests_passed_accepts_pytest_zero_errors() {
        // Pytest long-form: "0 errors in 0.3s" on a clean run.
        assert!(detect_tests_passed(
            &["5 passed, 0 errors in 0.30s".to_string()],
            DEFAULT_RECENT_WINDOW
        ));
    }

    #[test]
    fn tests_passed_detects_diy_checkmark() {
        assert!(detect_tests_passed(
            &["✓ all checks passed".to_string()],
            DEFAULT_RECENT_WINDOW
        ));
    }

    #[test]
    fn anthropic_bash_heredoc_extracts_command() {
        // Anthropic format: tool_use.input is an object, not a JSON string.
        let request = with_messages(vec![bash("cat > /tmp/foo.txt << 'EOF'\nhi\nEOF")]);
        let sig = ToolSignals::from_request(&request, None);
        assert_eq!(
            sig.write_count, 1,
            "Anthropic Bash heredoc must also be detected"
        );
    }

    #[test]
    fn recent_window_falls_back_to_full_history_when_short() {
        let request = with_messages(vec![tc("Write")]);
        let sig = ToolSignals::from_request(&request, None);
        assert_eq!(sig.recent_write_count, 1);
        assert_eq!(sig.recent_edit_count, 0);
    }

    #[test]
    fn clean_tool_result_has_zero_severity_and_non_empty_streak() {
        let request = with_messages(vec![tr("output ok"), tr("another ok")]);
        let sig = ToolSignals::from_request(&request, None);
        assert_eq!(sig.severity, 0.0);
        assert_eq!(sig.no_error_streak, 2);
    }

    // ─── asymmetric-signal extensions ────────────────────────────────────

    #[test]
    fn todowrite_classifies_as_plan() {
        assert_eq!(classify_tool_call("TodoWrite", None), ToolSemantic::Plan);
        assert_eq!(classify_tool_call("todo_write", None), ToolSemantic::Plan);
    }

    #[test]
    fn codex_update_plan_classifies_as_plan() {
        assert_eq!(classify_tool_call("update_plan", None), ToolSemantic::Plan);
    }

    #[test]
    fn codex_shell_command_runs_bash_pattern_match() {
        // shell_command + heredoc -> Write.
        assert_eq!(
            classify_tool_call("shell_command", Some("cat > /app/foo.py <<'eof'\nx=1\neof")),
            ToolSemantic::Mutate(MutationKind::Write),
        );
        // shell_command + read-like inspection -> Read.
        assert_eq!(
            classify_tool_call("shell_command", Some("ls /app")),
            ToolSemantic::Observe,
        );
        // shell_command without matching patterns -> Unknown.
        assert_eq!(
            classify_tool_call("shell_command", Some("./run_tests.sh")),
            ToolSemantic::Unknown,
        );
    }

    #[test]
    fn read_tool_classifies_as_read() {
        assert_eq!(classify_tool_call("Read", None), ToolSemantic::Observe);
        assert_eq!(classify_tool_call("View", None), ToolSemantic::Observe);
    }

    #[test]
    fn hermes_tool_names_classify() {
        // Hermes (NousResearch) file tools route by name.
        assert_eq!(
            classify_tool_call("write_file", None),
            ToolSemantic::Mutate(MutationKind::Write)
        );
        assert_eq!(
            classify_tool_call("patch", None),
            ToolSemantic::Mutate(MutationKind::Edit)
        );
        assert_eq!(classify_tool_call("read_file", None), ToolSemantic::Observe);
        assert_eq!(
            classify_tool_call("search_files", None),
            ToolSemantic::Observe
        );
        // Hermes runs shell through `terminal`, which carries a `command` arg,
        // so its intent comes from the Bash-pattern match like codex's shell_command.
        assert_eq!(
            classify_tool_call("terminal", Some("sed -i 's/a/b/' /app/x.py")),
            ToolSemantic::Mutate(MutationKind::Edit),
        );
        assert_eq!(
            classify_tool_call("terminal", Some("grep foo /app")),
            ToolSemantic::Observe,
        );
        assert_eq!(
            classify_tool_call("terminal", Some("./run_tests.sh")),
            ToolSemantic::Unknown,
        );
    }

    #[test]
    fn bash_read_patterns_classify_as_read() {
        let cases = [
            "cat /etc/passwd",
            "grep foo bar.txt",
            "ls /app",
            "find . -name '*.py'",
        ];
        for cmd in cases {
            assert_eq!(
                classify_tool_call("Bash", Some(cmd)),
                ToolSemantic::Observe,
                "expected Read for {cmd}"
            );
        }
    }

    #[test]
    fn bash_write_precedence_over_read() {
        // `cat /file > out` contains both `cat /` (read) and ` > ` (write);
        // write redirection must win.
        assert_eq!(
            classify_tool_call("Bash", Some("cat /etc/hosts > /tmp/out")),
            ToolSemantic::Mutate(MutationKind::Write),
        );
    }

    #[test]
    fn pure_bash_streak_counts_trailing_other() {
        // 5 trailing non-classified Bash calls → streak == 5.
        let request = with_messages(vec![
            bash("make"),
            tr("ok"),
            bash("./configure"),
            tr("ok"),
            bash("make install"),
            tr("ok"),
            bash("./run.sh"),
            tr("ok"),
            bash("./test"),
            tr("ok"),
        ]);
        let sig = ToolSignals::from_request(&request, None);
        assert_eq!(sig.pure_bash_streak, 5);
        assert_eq!(sig.write_count, 0);
        assert_eq!(sig.read_count, 0);
    }

    #[test]
    fn pure_bash_streak_resets_on_write() {
        let request = with_messages(vec![bash("make"), tr("ok"), tc("Write"), tr("ok")]);
        let sig = ToolSignals::from_request(&request, None);
        assert_eq!(sig.pure_bash_streak, 0);
        assert_eq!(sig.write_count, 1);
    }

    #[test]
    fn recent_window_tracks_todowrite_and_read() {
        // Final 3 tool calls: TodoWrite, Read, TodoWrite.
        let request = with_messages(vec![
            bash("make"),
            tr("ok"),
            tc("TodoWrite"),
            tr("ok"),
            tc("Read"),
            tr("ok"),
            tc("TodoWrite"),
            tr("ok"),
        ]);
        let sig = ToolSignals::from_request(&request, None);
        assert_eq!(sig.todowrite_count, 2);
        assert_eq!(sig.recent_todowrite_count, 2);
        assert_eq!(sig.read_count, 1);
        assert_eq!(sig.recent_read_count, 1);
    }

    #[test]
    fn configured_tool_semantics_extend_the_builtin_vocabulary() {
        let semantics = ToolSemantics {
            observe: vec!["KB_search".to_string()],
            mutate: vec!["send_payment_request".to_string()],
            plan: vec!["create_research_plan".to_string()],
            new: vec!["send_message_to_user".to_string()],
        };
        semantics.validate().expect("valid additive semantics");
        let request = with_messages(vec![
            tc("Read"),
            tc("Write"),
            tc("TodoWrite"),
            tc("kb_SEARCH"),
            tc("send_payment_request"),
            tc("create_research_plan"),
            tc("send_message_to_user"),
            tc("unlisted_tool"),
        ]);

        let signal = ToolSignals::from_request_with_semantics(&request, None, &semantics);

        assert_eq!(signal.read_count, 2);
        assert_eq!(signal.write_count, 2);
        assert_eq!(signal.todowrite_count, 2);
        assert_eq!(signal.new_count, 1);
        assert_eq!(signal.recent_new_count, 1);
        assert_eq!(signal.pure_bash_streak, 1);
    }

    #[test]
    fn configured_tool_semantics_only_fold_ascii_case() {
        let semantics = ToolSemantics {
            observe: vec!["kb_search".to_string()],
            ..Default::default()
        };

        assert_eq!(
            classify_tool_call_with_semantics("KB_SEARCH", None, &semantics),
            ToolSemantic::Observe
        );
        // U+212A lowercases to ASCII `k` under Unicode rules, but custom names
        // intentionally ignore only ASCII case.
        assert_eq!(
            classify_tool_call_with_semantics("KB_SEARCH", None, &semantics),
            ToolSemantic::Unknown
        );
    }

    #[test]
    fn custom_semantics_preserve_builtin_unicode_lowercasing() {
        let semantics = ToolSemantics {
            observe: vec!["lookup_customer".to_string()],
            ..Default::default()
        };

        // This matched the built-in `notebookedit` before custom semantics existed.
        assert_eq!(
            classify_tool_call_with_semantics("notebooKedit", None, &semantics),
            ToolSemantic::Mutate(MutationKind::Edit)
        );
    }

    #[test]
    fn configured_semantics_never_replace_builtin_classifications() {
        let semantics = ToolSemantics {
            observe: vec!["lookup_customer".to_string()],
            mutate: vec!["send_payment".to_string()],
            plan: vec!["create_workflow".to_string()],
            new: vec!["send_message".to_string()],
        };

        for name in WRITE_TOOL_NAMES {
            assert_eq!(
                classify_tool_call_with_semantics(name, None, &semantics),
                ToolSemantic::Mutate(MutationKind::Write),
                "write tool {name:?} changed classification"
            );
        }
        for name in EDIT_TOOL_NAMES {
            assert_eq!(
                classify_tool_call_with_semantics(name, None, &semantics),
                ToolSemantic::Mutate(MutationKind::Edit),
                "edit tool {name:?} changed classification"
            );
        }
        for name in READ_TOOL_NAMES {
            assert_eq!(
                classify_tool_call_with_semantics(name, None, &semantics),
                ToolSemantic::Observe,
                "read tool {name:?} changed classification"
            );
        }
        for name in PLAN_TOOL_NAMES {
            assert_eq!(
                classify_tool_call_with_semantics(name, None, &semantics),
                ToolSemantic::Plan,
                "plan tool {name:?} changed classification"
            );
        }

        for (command, expected) in [
            ("cat /tmp/input", ToolSemantic::Observe),
            (
                "cat /tmp/input > /tmp/output",
                ToolSemantic::Mutate(MutationKind::Write),
            ),
            (
                "sed -i 's/a/b/' /tmp/file",
                ToolSemantic::Mutate(MutationKind::Edit),
            ),
            ("./run_tests.sh", ToolSemantic::Unknown),
        ] {
            assert_eq!(
                classify_tool_call_with_semantics("BASH", Some(command), &semantics),
                expected,
                "bash command {command:?} changed classification"
            );
        }
    }

    #[test]
    fn configured_semantics_score_like_their_builtin_equivalents() {
        let semantics = ToolSemantics {
            observe: vec!["lookup_customer".to_string()],
            mutate: vec!["send_payment".to_string()],
            plan: vec!["create_workflow".to_string()],
            ..Default::default()
        };

        for (builtin, configured) in [
            ("Read", "lookup_customer"),
            ("Write", "send_payment"),
            ("TodoWrite", "create_workflow"),
        ] {
            let messages_before_tool = || {
                vec![
                    Message::text(Role::User, "start"),
                    Message::text(Role::Assistant, "working"),
                    Message::text(Role::User, "continue"),
                    Message::text(Role::Assistant, "working"),
                    Message::text(Role::User, "continue"),
                    Message::text(Role::Assistant, "working"),
                    Message::text(Role::User, "continue"),
                ]
            };
            let mut builtin_messages = messages_before_tool();
            builtin_messages.push(tc(builtin));
            let mut configured_messages = messages_before_tool();
            configured_messages.push(tc(configured));

            let builtin_score = score_signal(&ToolSignals::from_request(
                &with_messages(builtin_messages),
                None,
            ));
            let configured_score = score_signal(&ToolSignals::from_request_with_semantics(
                &with_messages(configured_messages),
                None,
                &semantics,
            ));

            assert_ne!(
                builtin_score.score, 0.0,
                "the {builtin:?} control must exercise a scoring dimension"
            );
            assert_eq!(
                configured_score, builtin_score,
                "configured tool {configured:?} must score exactly like {builtin:?}"
            );
        }
    }

    #[test]
    fn tool_semantics_reject_duplicates_and_builtin_reclassification() {
        let duplicate = ToolSemantics {
            observe: vec!["lookup".to_string()],
            mutate: vec!["LOOKUP".to_string()],
            ..Default::default()
        };
        assert!(
            duplicate
                .validate()
                .expect_err("duplicate should fail")
                .to_string()
                .contains("appears in both")
        );

        let builtin = ToolSemantics {
            new: vec!["write_file".to_string()],
            ..Default::default()
        };
        assert!(
            builtin
                .validate()
                .expect_err("built-in should fail")
                .to_string()
                .contains("built-in semantics")
        );

        let empty = ToolSemantics {
            observe: vec![" \t".to_string()],
            ..Default::default()
        };
        assert!(
            empty
                .validate()
                .expect_err("empty name should fail")
                .to_string()
                .contains("empty tool name")
        );
    }
}