fix(agent): suppress tool protocol when no tools are available

Treat empty effective tool sets as a no-tools turn across prompt assembly, provider request shape, and parser execution.

Preserve reasoning-tag stripping while avoiding execution of tool-like output when no tools are available.

Add focused regressions for native request shape, XML text preservation, prompt scaffolding, and channel protocol prompt behavior.

Author: Audacity88

crates/zeroclaw-channels/src/orchestrator/mod.rs

@@ -93,8 +93,9 @@ use zeroclaw_memory::{self, MEMORY_CONTEXT_CLOSE, MEMORY_CONTEXT_OPEN, Memory};
 use zeroclaw_providers::reliable::{scope_provider_fallback, take_last_provider_fallback};
 use zeroclaw_providers::{self, ChatMessage, Provider};
 use zeroclaw_runtime::agent::loop_::{
-    clear_model_switch_request, get_model_switch_state, is_model_switch_requested,
-    run_tool_call_loop, scope_session_key, scope_thread_id, scrub_credentials,
+    build_tool_instructions_for_names, clear_model_switch_request, get_model_switch_state,
+    is_model_switch_requested, run_tool_call_loop, scope_session_key, scope_thread_id,
+    scrub_credentials,
 };
 use zeroclaw_runtime::approval::ApprovalManager;
 #[cfg(not(feature = "whatsapp-web"))]
@@ -5745,6 +5746,15 @@ pub async fn start_channels(
     if !excluded.is_empty() && config.autonomy.level != AutonomyLevel::Full {
         tool_descs.retain(|(name, _)| !excluded.iter().any(|ex| ex == name));
     }
+    let effective_tool_names: HashSet<&str> = tools_registry
+        .iter()
+        .map(|tool| tool.name())
+        .filter(|name| {
+            config.autonomy.level == AutonomyLevel::Full
+                || !excluded.iter().any(|excluded| excluded.as_str() == *name)
+        })
+        .collect();
+    tool_descs.retain(|(name, _)| effective_tool_names.contains(name));
 
     let bootstrap_max_chars = if config.agent.compact_context {
         Some(6000)
@@ -5766,8 +5776,9 @@ pub async fn start_channels(
         config.agent.max_system_prompt_chars,
     );
     if !native_tools {
-        system_prompt.push_str(&zeroclaw_runtime::agent::loop_::build_tool_instructions(
+        system_prompt.push_str(&build_tool_instructions_for_names(
             tools_registry.as_ref(),
+            &effective_tool_names,
         ));
     }
 
@@ -6244,6 +6255,7 @@ mod tests {
     use tempfile::TempDir;
     use zeroclaw_memory::{Memory, MemoryCategory, SqliteMemory};
     use zeroclaw_providers::{ChatMessage, Provider};
+    use zeroclaw_runtime::agent::loop_::build_tool_instructions;
     use zeroclaw_runtime::observability::NoopObserver;
     use zeroclaw_runtime::tools::{Tool, ToolResult};
 
@@ -10104,7 +10116,8 @@ BTC is currently around $65,000 based on latest tool output."#
             "build_system_prompt should not emit protocol block directly"
         );
 
-        prompt.push_str(&zeroclaw_runtime::agent::loop_::build_tool_instructions(&[]));
+        let tools_registry: Vec<Box<dyn Tool>> = vec![Box::new(MockPriceTool)];
+        prompt.push_str(&build_tool_instructions(&tools_registry));
 
         assert_eq!(
             prompt.matches("## Tool Use Protocol").count(),

crates/zeroclaw-runtime/src/agent/agent.rs

@@ -19,6 +19,7 @@ use std::time::Instant;
 use zeroclaw_config::schema::Config;
 use zeroclaw_memory::{self, Memory, MemoryCategory};
 use zeroclaw_providers::{self, ChatMessage, ChatRequest, ConversationMessage, Provider};
+use zeroclaw_tool_call_parser::strip_think_tags;
 
 // Re-export TurnEvent from zeroclaw-types for backwards compatibility.
 pub use zeroclaw_api::agent::TurnEvent;
@@ -421,6 +422,24 @@ impl Agent {
         self.history.clear();
     }
 
+    fn should_send_tool_specs(&self) -> bool {
+        self.tool_dispatcher.should_send_tool_specs() && !self.tool_specs.is_empty()
+    }
+
+    fn parse_response_for_effective_tools(
+        &self,
+        response: &zeroclaw_providers::ChatResponse,
+    ) -> (String, Vec<ParsedToolCall>) {
+        if self.tool_specs.is_empty() {
+            return (
+                strip_think_tags(&response.text.clone().unwrap_or_default()),
+                Vec::new(),
+            );
+        }
+
+        self.tool_dispatcher.parse_response(response)
+    }
+
     pub fn set_memory_session_id(&mut self, session_id: Option<String>) {
         self.memory_session_id = session_id;
     }
@@ -1168,7 +1187,7 @@ impl Agent {
                 .chat(
                     ChatRequest {
                         messages: &messages,
-                        tools: if self.tool_dispatcher.should_send_tool_specs() {
+                        tools: if self.should_send_tool_specs() {
                             Some(&self.tool_specs)
                         } else {
                             None
@@ -1183,9 +1202,9 @@ impl Agent {
                 Err(err) => return Err(err),
             };
 
-            let (text, calls) = self.tool_dispatcher.parse_response(&response);
+            let (text, calls) = self.parse_response_for_effective_tools(&response);
             if calls.is_empty() {
-                let final_text = if text.is_empty() {
+                let final_text = if text.is_empty() && !self.tool_specs.is_empty() {
                     response.text.unwrap_or_default()
                 } else {
                     text
@@ -1353,7 +1372,7 @@ impl Agent {
             let mut stream = self.provider.stream_chat(
                 zeroclaw_providers::ChatRequest {
                     messages: &messages,
-                    tools: if self.tool_dispatcher.should_send_tool_specs() {
+                    tools: if self.should_send_tool_specs() {
                         Some(&self.tool_specs)
                     } else {
                         None
@@ -1491,7 +1510,7 @@ impl Agent {
                 let chat_fut = self.provider.chat(
                     ChatRequest {
                         messages: &messages,
-                        tools: if self.tool_dispatcher.should_send_tool_specs() {
+                        tools: if self.should_send_tool_specs() {
                             Some(&self.tool_specs)
                         } else {
                             None
@@ -1531,9 +1550,9 @@ impl Agent {
                     .await;
             }
 
-            let (text, mut calls) = self.tool_dispatcher.parse_response(&response);
+            let (text, mut calls) = self.parse_response_for_effective_tools(&response);
             if calls.is_empty() {
-                let final_text = if text.is_empty() {
+                let final_text = if text.is_empty() && !self.tool_specs.is_empty() {
                     response.text.unwrap_or_default()
                 } else {
                     text

crates/zeroclaw-runtime/src/agent/dispatcher.rs

@@ -128,7 +128,11 @@ impl ToolDispatcher for XmlToolDispatcher {
         ConversationMessage::Chat(ChatMessage::user(format!("[Tool results]\n{content}")))
     }
 
-    fn prompt_instructions(&self, _tools: &[Box<dyn Tool>]) -> String {
+    fn prompt_instructions(&self, tools: &[Box<dyn Tool>]) -> String {
+        if tools.is_empty() {
+            return String::new();
+        }
+
         let mut instructions = String::new();
         instructions.push_str("## Tool Use Protocol\n\n");
         instructions

crates/zeroclaw-runtime/src/agent/loop_.rs

@@ -1276,32 +1276,45 @@ pub async fn run_tool_call_loop(
                     .as_ref()
                     .and_then(|usage| record_tool_loop_cost_usage(provider_name, model, usage));
 
-                let response_text = resp.text_or_empty().to_string();
+                let response_text = if tool_specs.is_empty() {
+                    strip_think_tags(resp.text_or_empty())
+                } else {
+                    resp.text_or_empty().to_string()
+                };
                 // First try native structured tool calls (OpenAI-format).
                 // Fall back to text-based parsing (XML tags, markdown blocks,
                 // GLM format) only if the provider returned no native calls —
                 // this ensures we support both native and prompt-guided models.
-                let mut calls: Vec<ParsedToolCall> = resp
-                    .tool_calls
-                    .iter()
-                    .map(|call| ParsedToolCall {
-                        name: call.name.clone(),
-                        arguments: serde_json::from_str::<serde_json::Value>(&call.arguments)
-                            .unwrap_or_else(|_| serde_json::Value::Object(serde_json::Map::new())),
-                        tool_call_id: Some(call.id.clone()),
-                    })
-                    .collect();
+                let mut calls: Vec<ParsedToolCall> = if tool_specs.is_empty() {
+                    Vec::new()
+                } else {
+                    resp.tool_calls
+                        .iter()
+                        .map(|call| ParsedToolCall {
+                            name: call.name.clone(),
+                            arguments: serde_json::from_str::<serde_json::Value>(&call.arguments)
+                                .unwrap_or_else(|_| {
+                                    serde_json::Value::Object(serde_json::Map::new())
+                                }),
+                            tool_call_id: Some(call.id.clone()),
+                        })
+                        .collect()
+                };
                 let mut parsed_text = String::new();
 
-                if calls.is_empty() {
+                if calls.is_empty() && !tool_specs.is_empty() {
                     let (fallback_text, fallback_calls) = parse_tool_calls(&response_text);
                     if !fallback_text.is_empty() {
                         parsed_text = fallback_text;
                     }
                     calls = fallback_calls;
                 }
 
-                let parse_issue = detect_tool_call_parse_issue(&response_text, &calls);
+                let parse_issue = if tool_specs.is_empty() {
+                    None
+                } else {
+                    detect_tool_call_parse_issue(&response_text, &calls)
+                };
                 if let Some(ref issue) = parse_issue {
                     runtime_trace::record_event(
                         "tool_call_parse_issue",
@@ -2060,6 +2073,29 @@ pub async fn run_tool_call_loop(
 /// Build the tool instruction block for the system prompt so the LLM knows
 /// how to invoke tools.
 pub fn build_tool_instructions(tools_registry: &[Box<dyn Tool>]) -> String {
+    build_tool_instructions_for_tools(tools_registry.iter().map(|tool| tool.as_ref()))
+}
+
+/// Build tool instructions for the subset of registered tools that are
+/// effective for the current prompt.
+pub fn build_tool_instructions_for_names(
+    tools_registry: &[Box<dyn Tool>],
+    effective_tool_names: &HashSet<&str>,
+) -> String {
+    build_tool_instructions_for_tools(
+        tools_registry
+            .iter()
+            .map(|tool| tool.as_ref())
+            .filter(|tool| effective_tool_names.contains(tool.name())),
+    )
+}
+
+fn build_tool_instructions_for_tools<'a>(tools: impl IntoIterator<Item = &'a dyn Tool>) -> String {
+    let tools: Vec<&dyn Tool> = tools.into_iter().collect();
+    if tools.is_empty() {
+        return String::new();
+    }
+
     let mut instructions = String::new();
     instructions.push_str("\n## Tool Use Protocol\n\n");
     instructions.push_str("To use a tool, wrap a JSON object in <tool_call></tool_call> tags:\n\n");
@@ -2074,7 +2110,7 @@ pub fn build_tool_instructions(tools_registry: &[Box<dyn Tool>]) -> String {
         .push_str("Continue reasoning with the results until you can give a final answer.\n\n");
     instructions.push_str("### Available Tools\n\n");
 
-    for tool in tools_registry {
+    for tool in tools {
         let desc = tool.description();
         let _ = writeln!(
             instructions,
@@ -2088,6 +2124,15 @@ pub fn build_tool_instructions(tools_registry: &[Box<dyn Tool>]) -> String {
     instructions
 }
 
+fn retain_registered_tool_descriptions(
+    tool_descs: &mut Vec<(&str, &str)>,
+    tools_registry: &[Box<dyn Tool>],
+) {
+    let registered_tool_names: HashSet<&str> =
+        tools_registry.iter().map(|tool| tool.name()).collect();
+    tool_descs.retain(|(name, _)| registered_tool_names.contains(name));
+}
+
 // ── CLI Entrypoint ───────────────────────────────────────────────────────
 // Wires up all subsystems (observer, runtime, security, memory, tools,
 // provider, hardware RAG, peripherals) and enters either single-shot or
@@ -2452,6 +2497,7 @@ pub async fn run(
             "Query connected hardware for reported GPIO pins and LED pin. Use when: user asks what pins are available.",
         ));
     }
+    retain_registered_tool_descriptions(&mut tool_descs, &tools_registry);
     let bootstrap_max_chars = if config.agent.compact_context {
         Some(6000)
     } else {
@@ -3377,6 +3423,19 @@ pub async fn process_message(
             tool_descs.retain(|(name, _)| !excluded.iter().any(|ex| ex == name));
         }
     }
+    let effective_tool_names: HashSet<&str> = tools_registry
+        .iter()
+        .map(|tool| tool.name())
+        .filter(|name| {
+            config.autonomy.level == AutonomyLevel::Full
+                || !config
+                    .autonomy
+                    .non_cli_excluded_tools
+                    .iter()
+                    .any(|excluded| excluded.as_str() == *name)
+        })
+        .collect();
+    tool_descs.retain(|(name, _)| effective_tool_names.contains(name));
 
     let bootstrap_max_chars = if config.agent.compact_context {
         Some(6000)
@@ -3398,7 +3457,10 @@ pub async fn process_message(
         config.agent.max_system_prompt_chars,
     );
     if !native_tools {
-        system_prompt.push_str(&build_tool_instructions(&tools_registry));
+        system_prompt.push_str(&build_tool_instructions_for_names(
+            &tools_registry,
+            &effective_tool_names,
+        ));
     }
     if !deferred_section.is_empty() {
         system_prompt.push('\n');
@@ -6301,6 +6363,14 @@ mod tests {
         assert!(instructions.contains("file_write"));
     }
 
+    #[test]
+    fn build_tool_instructions_empty_registry_returns_empty() {
+        let tools: Vec<Box<dyn Tool>> = vec![];
+        let instructions = build_tool_instructions(&tools);
+
+        assert!(instructions.is_empty());
+    }
+
     #[test]
     fn tools_to_openai_format_produces_valid_schema() {
         use crate::security::SecurityPolicy;
@@ -6942,6 +7012,50 @@ Let me check the result."#;
         );
     }
 
+    #[test]
+    fn non_native_system_prompt_with_no_tools_contains_zero_tool_protocol() {
+        use crate::agent::system_prompt::build_system_prompt_with_mode;
+
+        let tool_summaries: Vec<(&str, &str)> = vec![];
+
+        let system_prompt = build_system_prompt_with_mode(
+            std::path::Path::new("/tmp"),
+            "test-model",
+            &tool_summaries,
+            &[],
+            None,
+            None,
+            false,
+            zeroclaw_config::schema::SkillsPromptInjectionMode::Full,
+            crate::security::AutonomyLevel::default(),
+        );
+
+        assert!(
+            !system_prompt.contains("## Tools"),
+            "No-tools prompt must not include a Tools section"
+        );
+        assert!(
+            !system_prompt.contains("## Tool Use Protocol"),
+            "No-tools prompt must not include tool protocol"
+        );
+        assert!(
+            !system_prompt.contains("<tool_call>"),
+            "No-tools prompt must not mention XML tool calls"
+        );
+        assert!(
+            !system_prompt.contains("<tool_result>"),
+            "No-tools prompt must not mention XML tool results"
+        );
+        assert!(
+            !system_prompt.contains("Use the tools"),
+            "No-tools prompt must not instruct the model to use unavailable tools"
+        );
+        assert!(
+            system_prompt.contains("No tools are available for this turn"),
+            "No-tools prompt should explicitly describe the current capability boundary"
+        );
+    }
+
     // ── Cross-Alias & GLM Shortened Body Tests ──────────────────────────
 
     #[test]