Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.
Rust
feat(stage-router): support custom tool semantics (#606)
Sean Lopp8ea0963f92ac
diff --git a/crates/libsy/src/algorithms/stage.rs b/crates/libsy/src/algorithms/stage.rsindex 3fd4acc1e..2f9adf945 100644--- a/crates/libsy/src/algorithms/stage.rs+++ b/crates/libsy/src/algorithms/stage.rs@@ -24,7 +24,7 @@ use super::util::stage::{DecisionSource, HandoffNoteConfig, PickerMode, StageClassifier, StageTargets, Tier,fall_open_tier, record_decision_source, record_routing_decision,};-use super::util::tool_signals::{DEFAULT_RECENT_WINDOW, ToolSignalProcessor};+use super::util::tool_signals::{DEFAULT_RECENT_WINDOW, ToolSemantics, ToolSignalProcessor};use crate::core::algorithm::{Algorithm, Driver};use crate::core::classifier::{Classification, Classifier, Score};use crate::core::state::State;@@ -113,6 +113,8 @@ pub struct StageRouterConfig {/// Trailing tool results the signals are computed over. `None` uses/// [`DEFAULT_RECENT_WINDOW`].pub recent_window: Option<usize>,+ /// Exact tool-name semantics added to the built-in coding vocabulary.+ pub tool_semantics: ToolSemantics,/// Note handed to the model on a signal-driven escalation, and on a/// hand-back to the efficient tier when a de-escalation note is configured.pub handoff_notes: Option<HandoffNoteConfig>,@@ -133,6 +135,7 @@ impl StageRouterConfig {mode,confidence_threshold,recent_window: None,+ tool_semantics: ToolSemantics::default(),handoff_notes: None,tier_prompts: TargetPrompts::default(),llm_fallback: None,@@ -190,6 +193,7 @@ pub(crate) fn build_stage_route(),});}+ config.tool_semantics.validate()?;// The tiers are a fixed pair; their targets are whatever the deployment calls// them, and the classifier scores onto those names.let targets = StageTargets::new(capable.clone(), efficient.clone());@@ -205,6 +209,7 @@ pub(crate) fn build_stage_route(}let signals = ToolSignalProcessor {recent_window: config.recent_window.unwrap_or(DEFAULT_RECENT_WINDOW),+ tool_semantics: config.tool_semantics,};let target_set = vec![capable.clone(), efficient.clone()];let mut router = FallThrough::<State>::new_with_state(target_set)diff --git a/crates/libsy/src/algorithms/util/stage.rs b/crates/libsy/src/algorithms/util/stage.rsindex d5da79596..f9e3ef806 100644--- a/crates/libsy/src/algorithms/util/stage.rs+++ b/crates/libsy/src/algorithms/util/stage.rs@@ -257,9 +257,9 @@ impl ScoreResult {pub struct CodingAgentDimensions {/// Windowed max error severity in `[0, 1]`.pub severity: f64,- /// `1.0` when a deep turn has no reads, plans, writes, or edits (pure churn).+ /// `1.0` when a deep turn has no recognized observation, mutation, plan, or new activity.pub spinning: f64,- /// `1.0` when a deep turn reads/plans but does not write or edit.+ /// `1.0` when a deep turn observes/plans but does not mutate or show new activity.pub exploring: f64,/// Fraction of recent tool ops that produced code (writes + edits).pub production_intensity: f64,@@ -302,10 +302,11 @@ pub fn dimensions_from_signal(signal: &ToolSignals) -> CodingAgentDimensions {let deep_enough = signal.turn_depth >= STALL_MIN_TURN_DEPTH;let no_production = signal.recent_write_count == 0 && signal.recent_edit_count == 0;let investigating = signal.recent_read_count >= 1 || signal.recent_todowrite_count >= 1;+ let new_activity = signal.recent_new_count >= 1;// spinning vs exploring partition the "not producing" case by investigative// activity, so at most one fires — no double-counting on the production axis.- let spinning = deep_enough && no_production && !investigating;- let exploring = deep_enough && no_production && investigating;+ let spinning = deep_enough && no_production && !investigating && !new_activity;+ let exploring = deep_enough && no_production && investigating && !new_activity;CodingAgentDimensions {severity: f64::from(signal.severity),@@ -746,6 +747,57 @@ mod tests {}}+ #[test]+ fn new_activity_suppresses_stall_dimensions_without_biasing_the_score() {+ let signal = ToolSignals {+ turn_depth: STALL_MIN_TURN_DEPTH,+ recent_new_count: 1,+ ..Default::default()+ };++ let dimensions = dimensions_from_signal(&signal);++ assert_eq!(dimensions.spinning, 0.0);+ assert_eq!(dimensions.exploring, 0.0);+ assert_eq!(score_signal(&signal).score, 0.0);+ }++ #[test]+ fn old_new_activity_does_not_suppress_a_current_stall() {+ let signal = ToolSignals {+ turn_depth: STALL_MIN_TURN_DEPTH,+ new_count: 1,+ recent_new_count: 0,+ ..Default::default()+ };++ let dimensions = dimensions_from_signal(&signal);++ assert_eq!(dimensions.spinning, 1.0);+ assert_eq!(dimensions.exploring, 0.0);+ assert!(score_signal(&signal).score > 0.0);+ }++ #[test]+ fn new_activity_does_not_dilute_existing_production() {+ let baseline = ToolSignals {+ turn_depth: STALL_MIN_TURN_DEPTH,+ recent_write_count: 1,+ ..Default::default()+ };+ let with_new = ToolSignals {+ recent_new_count: 2,+ new_count: 2,+ ..baseline.clone()+ };++ assert_eq!(+ dimensions_from_signal(&with_new).production_intensity,+ dimensions_from_signal(&baseline).production_intensity+ );+ assert_eq!(score_signal(&with_new), score_signal(&baseline));+ }+// ─── StageClassifier ─────────────────────────────────────────────────/// Tiers named the way a deployment would name them.diff --git a/crates/libsy/src/algorithms/util/tool_signals.rs b/crates/libsy/src/algorithms/util/tool_signals.rsindex 3427357be..43e1bd814 100644--- a/crates/libsy/src/algorithms/util/tool_signals.rs+++ b/crates/libsy/src/algorithms/util/tool_signals.rs@@ -13,10 +13,11 @@#![allow(dead_code)]use async_trait::async_trait;+use serde::Deserialize;use serde_json::Value;use switchyard_protocol::{ContentBlock, Request, Role};-use crate::Result;+use crate::{LibsyError, Result};use crate::core::processor::{Event, Processor};use crate::core::state::State;@@ -203,6 +204,83 @@ static NUMERIC_FAILURE_KEYWORDS: &[&str] = &["failed", "failure", "failures", "e/// 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`].@@ -237,7 +315,11 @@ pub struct ToolSignals {pub recent_read_count: u32,/// TodoWrite calls within the configured recent window (default: [`DEFAULT_RECENT_WINDOW`]).pub recent_todowrite_count: u32,- /// Consecutive trailing tool calls in the `Other` category (no Write/Edit/Read/+ /// 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.@@ -261,12 +343,25 @@ pub struct ToolSignals {}impl ToolSignals {- /// Extracts tool and progress signals from `request`.+ /// 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 {- extract_tool_signals_with_window(request, window_size.unwrap_or(DEFAULT_RECENT_WINDOW))+ 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,+ )}}@@ -278,12 +373,19 @@ struct ObservedToolCall {}#[derive(Debug, Clone, Copy, PartialEq, Eq)]-enum ToolCategory {+enum MutationKind {Write,Edit,- Read,+}++/// Domain-neutral meaning assigned to an observed tool call.+#[derive(Debug, Clone, Copy, PartialEq, Eq)]+enum ToolSemantic {+ Mutate(MutationKind),+ Observe,Plan,- Other,+ New,+ Unknown,}/// Request-side processor that extracts tool-result signals from each request@@ -293,12 +395,15 @@ 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(),}}}@@ -307,45 +412,66 @@ impl Default for ToolSignalProcessor {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(req, Some(self.recent_window));+ 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>) -> ToolCategory {+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 ToolCategory::Write;+ return ToolSemantic::Mutate(MutationKind::Write);}if EDIT_TOOL_NAMES.contains(&lower.as_str()) {- return ToolCategory::Edit;+ return ToolSemantic::Mutate(MutationKind::Edit);}if READ_TOOL_NAMES.contains(&lower.as_str()) {- return ToolCategory::Read;+ return ToolSemantic::Observe;}if PLAN_TOOL_NAMES.contains(&lower.as_str()) {- return ToolCategory::Plan;+ 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 ToolCategory::Write;+ return ToolSemantic::Mutate(MutationKind::Write);}if cmd.contains("python") && PYTHON_WRITE_PATTERNS.iter().any(|p| cmd.contains(p)) {- return ToolCategory::Write;+ return ToolSemantic::Mutate(MutationKind::Write);}if BASH_EDIT_PATTERNS.iter().any(|p| cmd.contains(p)) {- return ToolCategory::Edit;+ return ToolSemantic::Mutate(MutationKind::Edit);}if BASH_READ_PATTERNS.iter().any(|p| cmd.contains(p)) {- return ToolCategory::Read;+ return ToolSemantic::Observe;}}- ToolCategory::Other+ 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 ───────────────────────────────────────────────────@@ -355,6 +481,18 @@ fn classify_tool_call(name: &str, command: Option<&str>) -> ToolCategory {/// 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.@@ -401,7 +539,13 @@ fn extract_tool_signals_with_window(request: &Request, recent_window: usize) ->}}- let mut signal = build_signal(tool_texts, tool_calls, messages.len() as u32, recent_window);+ 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);@@ -456,6 +600,7 @@ fn build_signal(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@@ -474,7 +619,7 @@ fn build_signal(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 `Other`-category calls back+ // 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;@@ -485,43 +630,51 @@ fn build_signal(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(&tc.name, tc.command.as_deref());+ let cat = classify_tool_call_with_semantics(&tc.name, tc.command.as_deref(), semantics);if streak_open {- if matches!(cat, ToolCategory::Other) {+ if matches!(cat, ToolSemantic::Unknown) {pure_bash_streak += 1;} else {streak_open = false;}}match cat {- ToolCategory::Write => {+ ToolSemantic::Mutate(MutationKind::Write) => {write_count += 1;if i >= recent_start {recent_write_count += 1;}}- ToolCategory::Edit => {+ ToolSemantic::Mutate(MutationKind::Edit) => {edit_count += 1;if i >= recent_start {recent_edit_count += 1;}}- ToolCategory::Read => {+ ToolSemantic::Observe => {read_count += 1;if i >= recent_start {recent_read_count += 1;}}- ToolCategory::Plan => {+ ToolSemantic::Plan => {todowrite_count += 1;if i >= recent_start {recent_todowrite_count += 1;}}- ToolCategory::Other => {}+ ToolSemantic::New => {+ new_count += 1;+ if i >= recent_start {+ recent_new_count += 1;+ }+ }+ ToolSemantic::Unknown => {}}}@@ -538,6 +691,8 @@ fn build_signal(recent_write_count,recent_read_count,recent_todowrite_count,+ new_count,+ recent_new_count,pure_bash_streak,tests_passed,turn_depth,@@ -654,6 +809,7 @@ fn has_nonzero_failure_count(lower: &str) -> bool {#[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};@@ -1099,13 +1255,13 @@ mod tests {#[test]fn todowrite_classifies_as_plan() {- assert_eq!(classify_tool_call("TodoWrite", None), ToolCategory::Plan);- assert_eq!(classify_tool_call("todo_write", None), ToolCategory::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), ToolCategory::Plan);+ assert_eq!(classify_tool_call("update_plan", None), ToolSemantic::Plan);}#[test]@@ -1113,46 +1269,55 @@ mod tests {// shell_command + heredoc -> Write.assert_eq!(classify_tool_call("shell_command", Some("cat > /app/foo.py <<'eof'\nx=1\neof")),- ToolCategory::Write,+ ToolSemantic::Mutate(MutationKind::Write),);// shell_command + read-like inspection -> Read.assert_eq!(classify_tool_call("shell_command", Some("ls /app")),- ToolCategory::Read,+ ToolSemantic::Observe,);- // shell_command without matching patterns -> Other.+ // shell_command without matching patterns -> Unknown.assert_eq!(classify_tool_call("shell_command", Some("./run_tests.sh")),- ToolCategory::Other,+ ToolSemantic::Unknown,);}#[test]fn read_tool_classifies_as_read() {- assert_eq!(classify_tool_call("Read", None), ToolCategory::Read);- assert_eq!(classify_tool_call("View", None), ToolCategory::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), ToolCategory::Write);- assert_eq!(classify_tool_call("patch", None), ToolCategory::Edit);- assert_eq!(classify_tool_call("read_file", None), ToolCategory::Read);- assert_eq!(classify_tool_call("search_files", None), ToolCategory::Read);+ 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")),- ToolCategory::Edit,+ ToolSemantic::Mutate(MutationKind::Edit),);assert_eq!(classify_tool_call("terminal", Some("grep foo /app")),- ToolCategory::Read,+ ToolSemantic::Observe,);assert_eq!(classify_tool_call("terminal", Some("./run_tests.sh")),- ToolCategory::Other,+ ToolSemantic::Unknown,);}@@ -1167,7 +1332,7 @@ mod tests {for cmd in cases {assert_eq!(classify_tool_call("Bash", Some(cmd)),- ToolCategory::Read,+ ToolSemantic::Observe,"expected Read for {cmd}");}@@ -1179,7 +1344,7 @@ mod tests {// write redirection must win.assert_eq!(classify_tool_call("Bash", Some("cat /etc/hosts > /tmp/out")),- ToolCategory::Write,+ ToolSemantic::Mutate(MutationKind::Write),);}@@ -1231,4 +1396,216 @@ mod tests {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")+ );+ }}diff --git a/crates/libsy/src/lib.rs b/crates/libsy/src/lib.rsindex ad70b8da2..7999f2428 100644--- a/crates/libsy/src/lib.rs+++ b/crates/libsy/src/lib.rs@@ -33,7 +33,7 @@ pub use algorithms::util::classifier_contract::{pub use algorithms::util::escalation::EscalationJudgeConfig;pub use algorithms::util::prompts::{SystemPromptProcessor, TargetPrompts, append_note};pub use algorithms::util::subagent::{SubagentGate, SubagentOverride};-pub use algorithms::util::tool_signals::{DEFAULT_RECENT_WINDOW, ToolSignals};+pub use algorithms::util::tool_signals::{DEFAULT_RECENT_WINDOW, ToolSemantics, ToolSignals};// Stage-router scoring and tier selection — the shared signal-driven routing// core (scorer, picker, and the `StageClassifier`).diff --git a/crates/switchyard-py/src/libsy_bindings.rs b/crates/switchyard-py/src/libsy_bindings.rsindex 79adca287..cc7801a42 100644--- a/crates/switchyard-py/src/libsy_bindings.rs+++ b/crates/switchyard-py/src/libsy_bindings.rs@@ -16,7 +16,7 @@ use switchyard_libsy::{CustomClassifierConfig, CustomClassifierPolicy, EscalationJudgeConfig, HandoffNoteConfig,LibsyError as RustLibsyError, LlmClassifierConfig, LlmFallback, LlmTaskClassifier, Noop,PickerMode, Random, RoutingOutcome, StageRouter, StageRouterConfig, Step as RustStep,- StepStream, TaskClassifierConfig,+ StepStream, TaskClassifierConfig, ToolSemantics,};use switchyard_protocol::{LlmClientError, LlmResponse, LlmResponseStream, LlmResponseStreamEvent, Metadata, ModelId,@@ -815,6 +815,7 @@ fn build_llm_classifier(config: LlmClassifierConfig) -> PyResult<PyAlgorithm> {only_on_wrong_signal_escalation=true,capable_system_prompt=None,efficient_system_prompt=None,+ tool_semantics=None,classifier=None))]#[allow(clippy::too_many_arguments)]@@ -830,6 +831,7 @@ fn stage_router_algorithm(only_on_wrong_signal_escalation: bool,capable_system_prompt: Option<String>,efficient_system_prompt: Option<String>,+ tool_semantics: Option<HashMap<String, Vec<String>>>,classifier: Option<Py<PyLlmFallback>>,) -> PyResult<PyAlgorithm> {let mode = match picker {@@ -864,6 +866,19 @@ fn stage_router_algorithm(if let Some(prompt) = efficient_system_prompt {config.tier_prompts = config.tier_prompts.with(efficient.clone(), prompt);}+ if let Some(mut semantics) = tool_semantics {+ config.tool_semantics = ToolSemantics {+ observe: semantics.remove("observe").unwrap_or_default(),+ mutate: semantics.remove("mutate").unwrap_or_default(),+ plan: semantics.remove("plan").unwrap_or_default(),+ new: semantics.remove("new").unwrap_or_default(),+ };+ if let Some(category) = semantics.keys().next() {+ return Err(PyValueError::new_err(format!(+ "unknown tool_semantics category {category:?}; expected observe, mutate, plan, or new"+ )));+ }+ }config.llm_fallback = classifier.map(|classifier| classifier.bind(py).try_borrow()?.clone_core(py)).transpose()?;diff --git a/crates/switchyard-runner/src/algorithm.rs b/crates/switchyard-runner/src/algorithm.rsindex e5db6d477..21a8fa9a0 100644--- a/crates/switchyard-runner/src/algorithm.rs+++ b/crates/switchyard-runner/src/algorithm.rs@@ -15,6 +15,7 @@ use libsy::{CustomClassifierPolicy, EscalationJudgeConfig, GateTrigger, HandoffNoteConfig,LlmClassifierConfig, LlmFallback, LlmTaskClassifier, Noop, Passthrough, PickerMode, Random,StageRouter, StageRouterConfig, SubagentRouter, SubagentRouterConfig, TaskClassifierConfig,+ ToolSemantics,};use serde::Deserialize;use switchyard_protocol::ModelId;@@ -401,6 +402,9 @@ pub struct StageTierConfig {/// How many trailing tool results the signals are scored over.#[serde(default)]pub recent_turn_window: Option<usize>,+ /// Exact tool-name semantics added to the built-in stage vocabulary.+ #[serde(default)]+ pub tool_semantics: ToolSemantics,/// Notes handed to a tier when the router switches to it.#[serde(default)]pub handoff_notes: Option<HandoffNoteConfig>,@@ -1004,6 +1008,7 @@ fn build_algorithm(efficient_target,confidence_threshold,recent_turn_window,+ tool_semantics,handoff_notes,} = tiers;if matches!(picker, PickerMode::CapableFirst) {@@ -1015,6 +1020,7 @@ fn build_algorithm(let efficient = resolve_target_model_id(route_name, efficient_target, targets)?;let mut config = StageRouterConfig::new(*picker, *confidence_threshold);config.recent_window = *recent_turn_window;+ config.tool_semantics = tool_semantics.clone();config.handoff_notes = handoff_notes.clone();// The judge is called through its own target, so it is not a routing// destination and stays out of the tier pair.@@ -1064,6 +1070,7 @@ fn build_algorithm(let mut stage_config =StageRouterConfig::new(PickerMode::EfficientFirst, stage.confidence_threshold);stage_config.recent_window = stage.recent_turn_window;+ stage_config.tool_semantics = stage.tool_semantics.clone();stage_config.handoff_notes = stage.handoff_notes.clone();let config = CompositeRouterConfig {judge_target,diff --git a/crates/switchyard-runner/src/config.rs b/crates/switchyard-runner/src/config.rsindex 5317df264..a2ef9aea7 100644--- a/crates/switchyard-runner/src/config.rs+++ b/crates/switchyard-runner/src/config.rs@@ -747,6 +747,12 @@ efficient_target = "weak"picker = "efficient_first"confidence_threshold = 1.0+[routes.stage.tool_semantics]+observe = ["lookup_customer"]+mutate = ["send_payment"]+plan = ["create_workflow"]+new = ["send_message"]+[routes.stage.classifier]target = "stage_judge"base_threshold = 0.5@@ -774,6 +780,9 @@ classify_trigger = "user_turn"capable_target = "strong"efficient_target = "weak"confidence_threshold = 0.5++[routes.composed.stage.tool_semantics]+new = ["send_message"]"#)}@@ -808,6 +817,33 @@ confidence_threshold = 0.5Ok(())}+ #[test]+ fn stage_rejects_ambiguous_or_non_additive_tool_semantics() {+ for (configured, expected) in [+ (+ stage_config().replace(+ "mutate = [\"send_payment\"]",+ "mutate = [\"LOOKUP_CUSTOMER\"]",+ ),+ "appears in both tool_semantics.observe and tool_semantics.mutate",+ ),+ (+ stage_config().replace("new = [\"send_message\"]", "new = [\"Read\"]"),+ "already has built-in semantics and cannot be reclassified",+ ),+ (+ stage_config().replace("observe = [\"lookup_customer\"]", "observe = [\" \"]"),+ "contains an empty tool name",+ ),+ ] {+ let message = error_message(&configured);+ assert!(+ message.contains(expected),+ "expected {expected:?} in error, got: {message}"+ );+ }+ }+#[test]fn passthrough_and_stage_accept_subagent_routing() -> RunnerResult<()> {let stage = stage_config();diff --git a/crates/switchyard-server/README.md b/crates/switchyard-server/README.mdindex b14b7fa37..b4631b26f 100644--- a/crates/switchyard-server/README.md+++ b/crates/switchyard-server/README.md@@ -52,6 +52,11 @@ capable_target = "model_a"efficient_target = "model_b"picker = "efficient_first"confidence_threshold = 0.5++[routes.stage.tool_semantics]+observe = ["lookup_customer"]+mutate = ["update_inventory"]+new = ["send_message"]``````bash@@ -121,11 +126,14 @@ fallback produced while the judge was unreachable. `message_hash_fallback` keyscontent rather than a session id, so unrelated callers sending identical text share oneassignment.-A `stage_router` route scores tool-result and agent-progress signals from recent turns to pick a-tier per turn, without an extra classifier call on every turn. `capable_target`,+A `stage_router` route scores tool-result and activity signals from recent turns to pick a+tier per turn, without an extra classifier call on every turn. Domain-specific exact tool names+can extend its built-in coding vocabulary through `tool_semantics.observe`,+`tool_semantics.mutate`, `tool_semantics.plan`, and neutral `tool_semantics.new`. `capable_target`,`efficient_target`, `picker` (`efficient_first` or `capable_first`), and `confidence_threshold`-are required. Optional handoff notes, per-tier system prompts, and a capability-judge fallback are-documented in [Stage-Router Routing](../../docs/routing_algorithms/stage_router_routing.md).+are required. All configured semantic names use exact ASCII case-insensitive matching. Optional+handoff notes, per-tier system prompts, and a capability-judge fallback are documented in+[Stage-Router Routing](../../docs/routing_algorithms/stage_router_routing.md).## Endpointsdiff --git a/crates/switchyard-server/tests/server.rs b/crates/switchyard-server/tests/server.rsindex 0f6567092..60b73840c 100644--- a/crates/switchyard-server/tests/server.rs+++ b/crates/switchyard-server/tests/server.rs@@ -1425,6 +1425,162 @@ base_threshold = 0.5Ok(())}+// A configured mutation must select the efficient tier through the HTTP configuration path.+#[tokio::test]+async fn stage_router_uses_configured_tool_semantics() -> TestResult {+ let upstream = MockUpstream::start().await?;+ let state = load_test_config(&format!(+ r#"+schema_version = 1++[llm_clients.upstream]+format = "openai_chat"+base_url = "{base_url}"++[targets.strong]+id = "model/strong"+llm_client = "upstream"++[targets.weak]+id = "model/weak"+llm_client = "upstream"++[routes.stage]+id = "switchyard/stage"+type = "stage_router"+capable_target = "strong"+efficient_target = "weak"+picker = "capable_first"+confidence_threshold = 0.3++[routes.stage.tool_semantics]+mutate = ["send_payment_request"]+"#,+ base_url = upstream.base_url+ ))?;+ let app = build_switchyard_router(state);++ let response = send(+ &app,+ "POST",+ "/v1/chat/completions",+ Some(json!({+ "model": "switchyard/stage",+ "messages": [+ {"role": "user", "content": "pay the balance"},+ {"role": "assistant", "tool_calls": [{+ "id": "call_1",+ "type": "function",+ "function": {+ "name": "send_payment_request",+ "arguments": "{}"+ }+ }]},+ {"role": "tool", "tool_call_id": "call_1", "content": "payment sent"}+ ]+ })),+ )+ .await?;++ assert_eq!(response.status, StatusCode::OK);+ assert_eq!(+ response+ .headers+ .get("x-model-router-selected-model")+ .and_then(|value| value.to_str().ok()),+ Some("model/weak")+ );+ Ok(())+}++// Composite TOML must pass custom stage semantics through to the nested stage router.+#[tokio::test]+async fn composite_router_uses_configured_tool_semantics() -> TestResult {+ let upstream = MockUpstream::start().await?;+ let state = load_test_config(&format!(+ r#"+schema_version = 1++[llm_clients.upstream]+format = "openai_chat"+base_url = "{base_url}"++[targets.classifier]+id = "model/classifier"+llm_client = "upstream"++[targets.strong]+id = "model/strong"+llm_client = "upstream"++[targets.weak]+id = "model/weak"+llm_client = "upstream"++[routes.composite]+id = "switchyard/composite"+type = "composite"++[routes.composite.classifier]+target = "classifier"+base_threshold = 0.5+classify_trigger = "user_turn"++[routes.composite.stage]+capable_target = "strong"+efficient_target = "weak"+confidence_threshold = 0.3++[routes.composite.stage.tool_semantics]+new = ["send_message_to_user"]+"#,+ base_url = upstream.base_url+ ))?;+ let app = build_switchyard_router(state);++ let response = send(+ &app,+ "POST",+ "/v1/chat/completions",+ Some(json!({+ "model": "switchyard/composite",+ "messages": [+ {"role": "user", "content": "help the customer"},+ {"role": "assistant", "content": "working"},+ {"role": "user", "content": "continue"},+ {"role": "assistant", "content": "working"},+ {"role": "user", "content": "continue"},+ {"role": "assistant", "content": "working"},+ {"role": "assistant", "tool_calls": [{+ "id": "call_1",+ "type": "function",+ "function": {+ "name": "send_message_to_user",+ "arguments": "{}"+ }+ }]},+ {"role": "tool", "tool_call_id": "call_1", "content": "message sent"}+ ]+ })),+ )+ .await?;++ assert_eq!(response.status, StatusCode::OK);+ assert_eq!(+ response+ .headers+ .get("x-model-router-selected-model")+ .and_then(|value| value.to_str().ok()),+ Some("model/weak")+ );+ assert_eq!(+ upstream.models().await,+ ["model/weak"],+ "configured new activity must suppress the deep-turn stall without consulting the judge"+ );+ Ok(())+}+#[tokio::test]async fn custom_classifier_routes_four_targets_and_falls_back_on_an_invalid_verdict() -> TestResult{diff --git a/docs/getting_started.md b/docs/getting_started.mdindex 7c1cb362b..5f61e8034 100644--- a/docs/getting_started.md+++ b/docs/getting_started.md@@ -136,7 +136,7 @@ settings. The Rust server also supports:| Auto | You want a recommended default instead of picking a strategy yourself. | `auto` || [Random](routing_algorithms/random_routing.md) | You need a weighted split for A/B tests or baselines. | `random` || [LLM classifier](routing_algorithms/llm_classifier_routing.md) | Request content should decide whether to use the weak or strong target. | `llm_classifier` |-| [Stage router](routing_algorithms/stage_router_routing.md) | Tool-result and progress signals should select an efficient or capable target. | `stage_router` |+| [Stage router](routing_algorithms/stage_router_routing.md) | Built-in or configured tool-activity signals should select an efficient or capable target. | `stage_router` |A single TOML file can declare multiple routes. The table key, such as`routes.smart`, is a local configuration name; each route's `id` is exposed as adiff --git a/docs/reference/toml_schema.md b/docs/reference/toml_schema.mdindex a819a6178..3df685872 100644--- a/docs/reference/toml_schema.md+++ b/docs/reference/toml_schema.md@@ -248,6 +248,10 @@ optional `handoff_notes` and `classifier` tables and for tuning.| `picker` | Yes | — | `efficient_first`, or `capable_first` (experimental, unbenchmarked). Tier used when the signals are not confident. || `confidence_threshold` | Yes | — | Corroboration a decisive pick needs. In `[0, 1]`. || `recent_turn_window` | No | `3` | Trailing tool results the signals are computed over. |+| `tool_semantics.observe` | No | `[]` | Exact ASCII case-insensitive domain tool names that count as read-only investigation. |+| `tool_semantics.mutate` | No | `[]` | Exact ASCII case-insensitive domain tool names that count as state-changing production. |+| `tool_semantics.plan` | No | `[]` | Exact ASCII case-insensitive domain tool names that count as planning or task decomposition. |+| `tool_semantics.new` | No | `[]` | Exact ASCII case-insensitive domain tool names that demonstrate forward activity without favoring either tier. || `classifier.classify_trigger` | No | `every_request` | When the judge runs. See the `llm_classifier` route. `new_session` has no effect here. || `classifier.response_format_type` | No | `json_schema` | Structured-output mode for the optional classifier judge. Use `json_object` when the classifier provider does not support JSON Schema; Switchyard adds the schema to the prompt and validates the verdict locally. || `subagents` | No | unset | Nested `passthrough` or custom `llm_classifier` policy used only for delegated sub-agent work. See [Sub-Agent-Aware Routing](../routing_algorithms/subagent_routing.md). |@@ -283,6 +287,10 @@ configuration. Today a classifier sets the tier a stage router falls open to whe| `stage.efficient_target` | Yes | — | Efficient tier. || `stage.confidence_threshold` | Yes | — | Corroboration a decisive signal needs. In `[0, 1]`. || `stage.recent_turn_window` | No | `3` | Trailing tool results the signals are computed over. |+| `stage.tool_semantics.observe` | No | `[]` | Additional exact ASCII case-insensitive tool names that count as observation. |+| `stage.tool_semantics.mutate` | No | `[]` | Additional exact ASCII case-insensitive tool names that count as mutation. |+| `stage.tool_semantics.plan` | No | `[]` | Additional exact ASCII case-insensitive tool names that count as planning. |+| `stage.tool_semantics.new` | No | `[]` | Additional exact ASCII case-insensitive tool names that count as neutral forward activity. || `subagents` | No | unset | Nested policy used only for delegated sub-agent work. |The tier is retained per session. A deployment that sends no session ID needsdiff --git a/docs/routing_algorithms/composite_routing.md b/docs/routing_algorithms/composite_routing.mdindex f11226935..aaa6c3e9b 100644--- a/docs/routing_algorithms/composite_routing.md+++ b/docs/routing_algorithms/composite_routing.md@@ -33,6 +33,12 @@ classify_trigger = "user_turn"capable_target = "strong"efficient_target = "weak"confidence_threshold = 0.5++[routes.switchyard.stage.tool_semantics]+observe = ["lookup_customer"]+mutate = ["update_inventory"]+plan = ["create_research_plan"]+new = ["send_message"]````[routes.switchyard.classifier]` takes the `stage_router` classifier fields.@@ -41,6 +47,8 @@ whenever the user speaks, `new_session` picks once and holds it.`[routes.switchyard.stage]` takes the `stage_router` fields except `picker`, whosejob the classifier does per turn. Leave `classifier` out as well: that judge runsahead of the fall-open tier, so it answers most of the turns this one decided.+Custom `tool_semantics` remain stage-local and have the same additive behavior as+on a standalone stage route.## Sessionsdiff --git a/docs/routing_algorithms/overview.md b/docs/routing_algorithms/overview.mdindex 6350bc24e..074b3c151 100644--- a/docs/routing_algorithms/overview.md+++ b/docs/routing_algorithms/overview.md@@ -15,7 +15,7 @@ configuration and tuning. For the vocabulary these pages use, see| [Sub-Agent-Aware Routing](subagent_routing.md) | Delegated sub-agents should use a separate routing policy from the parent agent. | `passthrough` or `stage_router` with `subagents` || [Random Routing](random_routing.md) | You need a fixed traffic split for A/B tests, baselines, or cost experiments. | `random` || [LLM Classifier Routing](llm_classifier_routing.md) | Request content should decide whether a turn needs the weak or strong tier. | `llm_classifier` |-| [Stage-Router Routing](stage_router_routing.md) | Tool-result and agent-progress signals should route most turns without an extra classifier call. | `stage_router` |+| [Stage-Router Routing](stage_router_routing.md) | Built-in or configured tool-activity signals should route most turns without an extra classifier call. | `stage_router` || Auto Routing | You want a recommended default instead of picking a strategy yourself. For a deeper dive on the current default, see [Stage-Router Routing](stage_router_routing.md); for full control, pick one of the strategies above instead. | `auto` || [Composite Routing](composite_routing.md) | Routing algorithms are composed, one setting the configuration of another before handing off. Today an LLM classifier sets a stage router's default tier. | `composite` || [Escalation-Router Routing](escalation_router_routing.md) | Start every task on the weak tier and escalate to strong when an LLM judge detects trouble. | `llm_classifier` with `escalation` |diff --git a/docs/routing_algorithms/stage_router_routing.md b/docs/routing_algorithms/stage_router_routing.mdindex 95c484721..6e7ff9ac1 100644--- a/docs/routing_algorithms/stage_router_routing.md+++ b/docs/routing_algorithms/stage_router_routing.md@@ -15,10 +15,9 @@ remaining targets in configured order for that request. See## How it works-A coding agent's run moves through stages: early on it explores the codebase and-recovers from errors, and later it settles into more mechanical implementation.-Those stages call for different amounts of model capability, which is what the-router keys on.+A tool-using agent's run moves through stages that call for different amounts of+model capability. The built-in vocabulary is calibrated for coding agents: it+recognizes file observation, mutation, planning, shell activity, and test results.For each LLM call, stage-router estimates which stage the agent is in from the**tool-result history** on the conversation, scoring two axes:@@ -210,6 +209,35 @@ switchyard-server --config routes.toml --port 4000This is the recommended default: routing on tool signals alone, no classifier.+### Optional: custom tool semantics++Extend the built-in coding vocabulary when an agent uses domain-specific tool+names. Mappings are route-scoped, additive, and matched by exact name without+regard to ASCII case:++```toml+[routes.stage.tool_semantics]+observe = ["KB_search", "get_customer_by_phone"]+mutate = ["send_payment_request", "update_inventory"]+plan = ["create_research_plan"]+new = ["start_conversation", "send_message_to_user"]+```++The categories affect existing stage signals:++- `observe` counts as investigation, like the built-in read and search tools.+- `mutate` counts as production, like the built-in write and edit tools.+- `plan` counts as investigation, like the built-in planning tools.+- `new` records forward activity that suppresses false `spinning` and+ `exploring` signals, but does not otherwise favor either tier.+- `unknown` remains the fallback for tools that match neither the built-in+ vocabulary nor configured semantics.++Configuration cannot reclassify a built-in tool. Empty names, duplicate names+across categories, and unknown category keys are rejected when the route is+loaded. Argument-aware wrapper tools, inferred semantics, and learned routing+rules are outside this exact-name configuration.+### Optional: handoff notesAdd a `[routes.stage.handoff_notes]` section to pass a contextual note to thediff --git a/docs/routing_algorithms/subagent_routing.md b/docs/routing_algorithms/subagent_routing.mdindex 2533e80ea..ab201f2a0 100644--- a/docs/routing_algorithms/subagent_routing.md+++ b/docs/routing_algorithms/subagent_routing.md@@ -98,6 +98,9 @@ tool_calling = truereasoning = true```+The parent stage route may also declare `[routes.agent.tool_semantics]` to map+domain-specific tools; delegated sub-agent policy configuration is unaffected.+Clients must still request the route ID (`agent` above). An explicit model namethat is not registered as a route is rejected before sub-agent classification.`message_hash_fallback` is not supported for sub-agent routing because affinitydiff --git a/switchyard_rust/libsy.py b/switchyard_rust/libsy.pyindex 9756b1c6b..5acbac3d4 100644--- a/switchyard_rust/libsy.py+++ b/switchyard_rust/libsy.py@@ -261,6 +261,7 @@ if TYPE_CHECKING:only_on_wrong_signal_escalation: bool = True,capable_system_prompt: str | None = None,efficient_system_prompt: str | None = None,+ tool_semantics: dict[str, Sequence[str]] | None = None,classifier: LlmFallback | None = None,) -> Algorithm: ...diff --git a/tests/test_libsy_minimal_bindings.py b/tests/test_libsy_minimal_bindings.pyindex b693d4d87..4d1fb78e6 100644--- a/tests/test_libsy_minimal_bindings.py+++ b/tests/test_libsy_minimal_bindings.py@@ -436,3 +436,69 @@ async def test_context_window_failure_falls_back_to_the_next_model() -> None:assert selected_model == "fast"assert response["model"] == "strong"+++async def test_stage_router_applies_additive_tool_semantics() -> None:+ """Verify that configured mutation semantics reach stage-router scoring."""++ algorithm = algorithms.stage_router(+ "strong",+ "fast",+ picker="capable_first",+ confidence_threshold=0.3,+ tool_semantics={+ "observe": ["KB_search"],+ "mutate": ["send_payment_request"],+ "plan": ["create_research_plan"],+ "new": ["send_message_to_user"],+ },+ )++ selected_model, _ = await run_algorithm(+ algorithm,+ {"strong": EchoClient("strong"), "fast": EchoClient("fast")},+ request={+ "model": "auto",+ "messages": [+ {+ "role": "user",+ "content": [{"type": "text", "text": "pay the balance"}],+ },+ {+ "role": "assistant",+ "content": [+ {+ "type": "tool_call",+ "id": "call_1",+ "name": "send_payment_request",+ "arguments": {},+ }+ ],+ },+ {+ "role": "user",+ "content": [+ {+ "type": "tool_result",+ "tool_call_id": "call_1",+ "content": [{"type": "text", "text": "payment sent"}],+ "is_error": None,+ }+ ],+ },+ ],+ },+ )++ assert selected_model == "fast"+++def test_stage_router_rejects_unknown_tool_semantics_category() -> None:+ with pytest.raises(ValueError, match="unknown tool_semantics category"):+ algorithms.stage_router(+ "strong",+ "fast",+ picker="efficient_first",+ confidence_threshold=0.5,+ tool_semantics={"complete": ["end_conversation"]},+ )