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

docs(plan-execute): document custom tool handoff (#923)

ryan-lempka6d3dafbd1a1f
diff --git a/docs/reference/toml_schema.md b/docs/reference/toml_schema.md
index ce95015ee..91f1f90f2 100644
--- a/docs/reference/toml_schema.md
+++ b/docs/reference/toml_schema.md
@@ -223,12 +223,13 @@ Splits traffic across targets. See
### `plan_execute`
Plans on a capable target, then switches to an efficient target after the first
-file mutation. See [Plan/Execute Routing](../routing_algorithms/plan_execute_routing.md).
+recognized edit or write tool call. See [Plan/Execute Routing](../routing_algorithms/plan_execute_routing.md).
| Key | Required | Default | Meaning |
|---|:---:|---|---|
| `capable_target` | Yes | - | Target used for read-only inspection and planning. |
| `efficient_target` | Yes | - | Target used after the first edit or write. |
+| `tool_semantics.mutate` | No | `[]` | Additional tool names that trigger handoff. See the [example](../routing_algorithms/plan_execute_routing.md#optional-settings). |
| `planning_prompt` | No | packaged prompt | Replaces the planning instruction. |
| `handoff_prompt` | No | unset | Adds an instruction to the handoff request. |
| `planner_reasoning_as_text` | No | `false` | Converts visible planner reasoning summaries to assistant text at handoff. |
diff --git a/docs/routing_algorithms/plan_execute_routing.md b/docs/routing_algorithms/plan_execute_routing.md
index a94bb46c4..6c7dcd918 100644
--- a/docs/routing_algorithms/plan_execute_routing.md
+++ b/docs/routing_algorithms/plan_execute_routing.md
@@ -1,8 +1,8 @@
# Plan/Execute Routing
Plan/execute routing uses a capable model to inspect and plan a coding task,
-then switches to an efficient model after the first file mutation. It does not
-make a classifier call.
+then switches to an efficient model after the first recognized edit or write
+tool call. It does not make a classifier call.
```toml
schema_version = 1
@@ -71,8 +71,19 @@ edit missing from the request history.
| Key | Behavior |
|---|---|
+| `tool_semantics.mutate` | Lists custom tools that trigger handoff. |
| `planning_prompt` | Replaces the built-in planning instruction. |
| `handoff_prompt` | Adds an instruction to the handoff request. |
| `planner_reasoning_as_text` | Converts visible planner reasoning summaries to assistant text at handoff. |
+To make a custom tool trigger handoff:
+
+```toml
+[routes.plan_execute.tool_semantics]
+mutate = ["persist_source_file"]
+```
+
+This uses the same [tool matching rules](stage_router_routing.md#optional-custom-tool-semantics)
+as Stage. The other custom tool categories do not trigger handoff.
+
Use a stable session ID with handoff processing or history compaction.