Skip to content

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(plan-execute): support custom tool semantics (#935)

ryan-lempkae0050c0e57bb
diff --git a/crates/libsy/src/algorithms/plan_execute.rs b/crates/libsy/src/algorithms/plan_execute.rs
index 422003e0b..2bbbc286f 100644
--- a/crates/libsy/src/algorithms/plan_execute.rs
+++ b/crates/libsy/src/algorithms/plan_execute.rs
@@ -10,7 +10,7 @@ use parking_lot::Mutex;
use switchyard_protocol::{Category, ContentBlock, Request};
use super::util::prompts::{append_note, drop_exact_replay, prepend_system_prompt};
-use super::util::tool_signals::ToolSignals;
+use super::util::tool_signals::{ToolSemantics, ToolSignals};
use crate::core::algorithm::{Algorithm, Driver, RoutingIdentity};
use crate::{LibsyError, Result, RoutingOutcome};
@@ -23,6 +23,8 @@ const MAX_EXECUTING_SESSIONS: usize = 4_096;
/// Configuration for [`PlanExecute`].
#[derive(Clone, Debug)]
pub struct PlanExecuteConfig {
+ /// Additional tool names whose mutations trigger handoff.
+ pub tool_semantics: ToolSemantics,
/// System instruction added until the first edit or write tool call.
pub planning_prompt: String,
/// Optional instruction appended to the handoff request.
@@ -34,6 +36,7 @@ pub struct PlanExecuteConfig {
impl Default for PlanExecuteConfig {
fn default() -> Self {
Self {
+ tool_semantics: ToolSemantics::default(),
planning_prompt: DEFAULT_PLANNING_PROMPT.trim().to_string(),
handoff_prompt: None,
planner_reasoning_as_text: false,
@@ -58,7 +61,7 @@ pub struct PlanExecute {
impl PlanExecute {
/// Creates a plan/execute router.
///
- /// Returns an error when either configured prompt is blank.
+ /// Returns an error when a prompt is blank or tool semantics are invalid.
pub fn new(config: PlanExecuteConfig) -> Result<Self> {
if config.planning_prompt.trim().is_empty() {
return Err(LibsyError::AlgorithmError {
@@ -74,6 +77,7 @@ impl PlanExecute {
message: "handoff_prompt must not be empty".to_string(),
});
}
+ config.tool_semantics.validate()?;
Ok(Self {
config,
executing_sessions: Mutex::new(HashSet::new()),
@@ -81,7 +85,8 @@ impl PlanExecute {
}
fn phase(&self, request: &Request) -> Result<Phase> {
- let signals = ToolSignals::from_request(request, None);
+ let signals =
+ ToolSignals::from_request_with_semantics(request, None, &self.config.tool_semantics);
let mutation_seen = signals.edit_count > 0 || signals.write_count > 0;
let Some(identity) = RoutingIdentity::from_request(request) else {
return Ok(if mutation_seen {
diff --git a/crates/libsy/src/algorithms/util/tool_signals.rs b/crates/libsy/src/algorithms/util/tool_signals.rs
index 11ac3ac65..e5b0fc038 100644
--- a/crates/libsy/src/algorithms/util/tool_signals.rs
+++ b/crates/libsy/src/algorithms/util/tool_signals.rs
@@ -257,7 +257,7 @@ 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.
+/// Exact tool-name semantics added to the built-in vocabulary.
///
/// Matching is ASCII case-insensitive. An MCP or Codex namespaced tool also
/// matches by its bare tool name. These lists are additive: built-in tool names
diff --git a/crates/switchyard-runner/src/algorithm.rs b/crates/switchyard-runner/src/algorithm.rs
index a7e40e751..1c0f1dff9 100644
--- a/crates/switchyard-runner/src/algorithm.rs
+++ b/crates/switchyard-runner/src/algorithm.rs
@@ -360,6 +360,9 @@ pub enum AlgorithmSpec {
capable_target: String,
/// Target used from the first edit or write onward.
efficient_target: String,
+ /// Additional tool names whose mutations trigger handoff.
+ #[serde(default)]
+ tool_semantics: ToolSemantics,
/// Replaces the built-in planning instruction.
#[serde(default)]
planning_prompt: Option<String>,
@@ -1271,12 +1274,14 @@ fn build_algorithm(
attach_subagent_router(route_name, parent, subagents.as_ref(), targets)
}
AlgorithmSpec::PlanExecute {
+ tool_semantics,
planning_prompt,
handoff_prompt,
planner_reasoning_as_text,
..
} => {
let mut config = PlanExecuteConfig::default();
+ config.tool_semantics.clone_from(tool_semantics);
if let Some(prompt) = planning_prompt {
config.planning_prompt = prompt.clone();
}
diff --git a/crates/switchyard-runner/src/config.rs b/crates/switchyard-runner/src/config.rs
index 2c85a97ca..f3bfcdf37 100644
--- a/crates/switchyard-runner/src/config.rs
+++ b/crates/switchyard-runner/src/config.rs
@@ -1035,6 +1035,35 @@ target = "strong"
);
}
+ #[tokio::test]
+ async fn plan_execute_applies_custom_tool_semantics() -> RunnerResult<()> {
+ use switchyard_protocol::{ContentBlock, Message, Request, Role, ToolCall};
+
+ let configured = format!(
+ "{VALID_CONFIG}\n[routes.plan_execute.tool_semantics]\nmutate = [\"persist_source_file\"]"
+ );
+ let mut request = Request::default();
+ request.llm_request.messages.push(Message {
+ role: Role::Assistant,
+ content: vec![ContentBlock::ToolCall(ToolCall {
+ id: "write-1".to_string(),
+ name: "mcp__files__Persist_Source_File".to_string(),
+ arguments: json!({"path": "task.py", "content": "print('hello')"}),
+ })],
+ });
+
+ for (config, expected) in [
+ (VALID_CONFIG, "strong/model"),
+ (configured.as_str(), "weak/model"),
+ ] {
+ let runner = Runner::from_toml(config)?;
+ let route = runner.route("switchyard/plan-execute").unwrap();
+ let outcome = route.decide(request.clone()).await?;
+ assert_eq!(outcome.selected_model_ids[0], expected);
+ }
+ Ok(())
+ }
+
fn error_message(toml: &str) -> String {
match runner_from_toml(toml) {
Ok(_) => "configuration unexpectedly succeeded".to_string(),