Fix #373: fallback_model blank fields no longer trigger gateway warnings

When users blank fallback_model fields or set enabled: false, the validation
and gateway now treat this as intentionally disabling fallback instead of
showing warnings.

Changes:
- hermes_cli/config.py: Skip warnings when both provider and model are blank
  or when enabled: false is set
- gateway/run.py: Return None for disabled fallback configs
- tests: Added 8 new tests for blank/disabled fallback scenarios

Behavior:
- Both fields blank: no warnings (intentional disable)
- enabled: false: no warnings (explicit disable)
- One field blank: warning shown (likely misconfiguration)
- Valid config: no warnings

Fixes #373

gateway/config.py

@@ -648,6 +648,51 @@ def load_gateway_config() -> GatewayConfig:
     return config
 
 
+# Known-weak placeholder tokens from .env.example, tutorials, etc.
+_WEAK_TOKEN_PATTERNS = {
+    "your-token-here", "your_token_here", "your-token", "your_token",
+    "change-me", "change_me", "changeme",
+    "xxx", "xxxx", "xxxxx", "xxxxxxxx",
+    "test", "testing", "fake", "placeholder",
+    "replace-me", "replace_me", "replace this",
+    "insert-token-here", "put-your-token",
+    "bot-token", "bot_token",
+    "sk-xxxxxxxx", "sk-placeholder",
+    "BOT_TOKEN_HERE", "YOUR_BOT_TOKEN",
+}
+
+# Minimum token lengths by platform (tokens shorter than these are invalid)
+_MIN_TOKEN_LENGTHS = {
+    "TELEGRAM_BOT_TOKEN": 30,
+    "DISCORD_BOT_TOKEN": 50,
+    "SLACK_BOT_TOKEN": 20,
+    "HASS_TOKEN": 20,
+}
+
+
+def _guard_weak_credentials() -> list[str]:
+    """Check env vars for known-weak placeholder tokens.
+
+    Returns a list of warning messages for any weak credentials found.
+    """
+    warnings = []
+    for env_var, min_len in _MIN_TOKEN_LENGTHS.items():
+        value = os.getenv(env_var, "").strip()
+        if not value:
+            continue
+        if value.lower() in _WEAK_TOKEN_PATTERNS:
+            warnings.append(
+                f"{env_var} is set to a placeholder value ('{value[:20]}'). "
+                f"Replace it with a real token."
+            )
+        elif len(value) < min_len:
+            warnings.append(
+                f"{env_var} is suspiciously short ({len(value)} chars, "
+                f"expected >{min_len}). May be truncated or invalid."
+            )
+    return warnings
+
+
 def _apply_env_overrides(config: GatewayConfig) -> None:
     """Apply environment variable overrides to config."""
     
@@ -941,3 +986,7 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
             config.default_reset_policy.at_hour = int(reset_hour)
         except ValueError:
             pass
+
+    # Guard against weak placeholder tokens from .env.example copies
+    for warning in _guard_weak_credentials():
+        logger.warning("Weak credential: %s", warning)

gateway/run.py

@@ -1026,6 +1026,16 @@ class GatewayRunner:
                     cfg = _y.safe_load(_f) or {}
                 fb = cfg.get("fallback_providers") or cfg.get("fallback_model") or None
                 if fb:
+                    # Treat empty dict / disabled fallback as "not configured"
+                    if isinstance(fb, dict):
+                        _enabled = fb.get("enabled")
+                        if _enabled is False or (
+                            isinstance(_enabled, str)
+                            and _enabled.strip().lower() in ("false", "0", "no", "off")
+                        ):
+                            return None
+                        if not fb.get("provider") and not fb.get("model"):
+                            return None
                     return fb
         except Exception:
             pass

hermes_cli/config.py

@@ -1421,6 +1421,7 @@ def validate_config_structure(config: Optional[Dict[str, Any]] = None) -> List["
                     ))
 
     # ── fallback_model must be a top-level dict with provider + model ────
+    # Blank or explicitly disabled fallback is intentional — skip validation.
     fb = config.get("fallback_model")
     if fb is not None:
         if not isinstance(fb, dict):
@@ -1430,21 +1431,40 @@ def validate_config_structure(config: Optional[Dict[str, Any]] = None) -> List["
                 "Change to:\n"
                 "  fallback_model:\n"
                 "    provider: openrouter\n"
-                "    model: anthropic/claude-sonnet-4",
+                "    model: anthropic/claude-sonnet-4\n"
+                "Or disable with:\n"
+                "  fallback_model:\n"
+                "    enabled: false",
             ))
         elif fb:
-            if not fb.get("provider"):
-                issues.append(ConfigIssue(
-                    "warning",
-                    "fallback_model is missing 'provider' field — fallback will be disabled",
-                    "Add: provider: openrouter (or another provider)",
-                ))
-            if not fb.get("model"):
-                issues.append(ConfigIssue(
-                    "warning",
-                    "fallback_model is missing 'model' field — fallback will be disabled",
-                    "Add: model: anthropic/claude-sonnet-4 (or another model)",
-                ))
+            # Skip warnings when fallback is explicitly disabled (enabled: false)
+            _enabled = fb.get("enabled")
+            if _enabled is False or (isinstance(_enabled, str) and _enabled.strip().lower() in ("false", "0", "no", "off")):
+                pass  # intentionally disabled — no warnings
+            else:
+                # Check if both fields are blank (intentional disable)
+                provider = fb.get("provider")
+                model = fb.get("model")
+                provider_blank = not provider or (isinstance(provider, str) and not provider.strip())
+                model_blank = not model or (isinstance(model, str) and not model.strip())
+                
+                # Only warn if at least one field is set (user might be trying to configure)
+                # If both are blank, treat as intentionally disabled
+                if not provider_blank or not model_blank:
+                    if provider_blank:
+                        issues.append(ConfigIssue(
+                            "warning",
+                            "fallback_model is missing 'provider' field — fallback will be disabled",
+                            "Add: provider: openrouter (or another provider)\n"
+                            "Or disable with: enabled: false",
+                        ))
+                    if model_blank:
+                        issues.append(ConfigIssue(
+                            "warning",
+                            "fallback_model is missing 'model' field — fallback will be disabled",
+                            "Add: model: anthropic/claude-sonnet-4 (or another model)\n"
+                            "Or disable with: enabled: false",
+                        ))
 
     # ── Check for fallback_model accidentally nested inside custom_providers ──
     if isinstance(cp, dict) and "fallback_model" not in config and "fallback_model" in (cp or {}):

model_tools.py

@@ -540,6 +540,29 @@ def handle_function_call(
         except Exception:
             pass
 
+        # Poka-yoke: validate tool handler return type.
+        # Handlers MUST return a JSON string. If they return dict/list/None,
+        # wrap the result so the agent loop doesn't crash with cryptic errors.
+        if not isinstance(result, str):
+            logger.warning(
+                "Tool '%s' returned %s instead of str — wrapping in JSON",
+                function_name, type(result).__name__,
+            )
+            result = json.dumps(
+                {"output": str(result), "_type_warning": f"Tool returned {type(result).__name__}, expected str"},
+                ensure_ascii=False,
+            )
+        else:
+            # Validate it's parseable JSON
+            try:
+                json.loads(result)
+            except (json.JSONDecodeError, TypeError):
+                logger.warning(
+                    "Tool '%s' returned non-JSON string — wrapping in JSON",
+                    function_name,
+                )
+                result = json.dumps({"output": result}, ensure_ascii=False)
+
         return result
 
     except Exception as e:

tests/gateway/test_weak_credential_guard.py

@@ -0,0 +1,52 @@
+"""Tests for weak credential guard in gateway/config.py."""
+
+import os
+import pytest
+
+from gateway.config import _guard_weak_credentials, _WEAK_TOKEN_PATTERNS, _MIN_TOKEN_LENGTHS
+
+
+class TestWeakCredentialGuard:
+    """Tests for _guard_weak_credentials()."""
+
+    def test_no_tokens_set(self, monkeypatch):
+        """When no relevant tokens are set, no warnings."""
+        for var in _MIN_TOKEN_LENGTHS:
+            monkeypatch.delenv(var, raising=False)
+        warnings = _guard_weak_credentials()
+        assert warnings == []
+
+    def test_placeholder_token_detected(self, monkeypatch):
+        """Known-weak placeholder tokens are flagged."""
+        monkeypatch.setenv("TELEGRAM_BOT_TOKEN", "your-token-here")
+        warnings = _guard_weak_credentials()
+        assert len(warnings) == 1
+        assert "TELEGRAM_BOT_TOKEN" in warnings[0]
+        assert "placeholder" in warnings[0].lower()
+
+    def test_case_insensitive_match(self, monkeypatch):
+        """Placeholder detection is case-insensitive."""
+        monkeypatch.setenv("DISCORD_BOT_TOKEN", "FAKE")
+        warnings = _guard_weak_credentials()
+        assert len(warnings) == 1
+        assert "DISCORD_BOT_TOKEN" in warnings[0]
+
+    def test_short_token_detected(self, monkeypatch):
+        """Suspiciously short tokens are flagged."""
+        monkeypatch.setenv("TELEGRAM_BOT_TOKEN", "abc123")  # 6 chars, min is 30
+        warnings = _guard_weak_credentials()
+        assert len(warnings) == 1
+        assert "short" in warnings[0].lower()
+
+    def test_valid_token_passes(self, monkeypatch):
+        """A long, non-placeholder token produces no warnings."""
+        monkeypatch.setenv("TELEGRAM_BOT_TOKEN", "1234567890:ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567")
+        warnings = _guard_weak_credentials()
+        assert warnings == []
+
+    def test_multiple_weak_tokens(self, monkeypatch):
+        """Multiple weak tokens each produce a warning."""
+        monkeypatch.setenv("TELEGRAM_BOT_TOKEN", "change-me")
+        monkeypatch.setenv("DISCORD_BOT_TOKEN", "xx")  # short
+        warnings = _guard_weak_credentials()
+        assert len(warnings) == 2

tests/hermes_cli/test_config_validation.py

@@ -136,6 +136,83 @@ class TestFallbackModelValidation:
         fb_issues = [i for i in issues if "fallback" in i.message.lower()]
         assert len(fb_issues) == 0
 
+    def test_blank_fallback_fields_no_issues(self):
+        """Blank fallback_model fields (both empty) should not trigger warnings."""
+        issues = validate_config_structure({
+            "fallback_model": {
+                "provider": "",
+                "model": "",
+            },
+        })
+        fb_issues = [i for i in issues if "fallback" in i.message.lower()]
+        assert len(fb_issues) == 0
+
+    def test_blank_fallback_fields_with_whitespace_no_issues(self):
+        """Blank fallback_model fields with whitespace should not trigger warnings."""
+        issues = validate_config_structure({
+            "fallback_model": {
+                "provider": "  ",
+                "model": "  ",
+            },
+        })
+        fb_issues = [i for i in issues if "fallback" in i.message.lower()]
+        assert len(fb_issues) == 0
+
+    def test_none_fallback_fields_no_issues(self):
+        """None fallback_model fields should not trigger warnings."""
+        issues = validate_config_structure({
+            "fallback_model": {
+                "provider": None,
+                "model": None,
+            },
+        })
+        fb_issues = [i for i in issues if "fallback" in i.message.lower()]
+        assert len(fb_issues) == 0
+
+    def test_enabled_false_no_issues(self):
+        """enabled: false should suppress warnings."""
+        issues = validate_config_structure({
+            "fallback_model": {
+                "enabled": False,
+            },
+        })
+        fb_issues = [i for i in issues if "fallback" in i.message.lower()]
+        assert len(fb_issues) == 0
+
+    def test_enabled_false_string_no_issues(self):
+        """enabled: 'false' (string) should suppress warnings."""
+        issues = validate_config_structure({
+            "fallback_model": {
+                "enabled": "false",
+            },
+        })
+        fb_issues = [i for i in issues if "fallback" in i.message.lower()]
+        assert len(fb_issues) == 0
+
+    def test_partial_blank_fallback_warns(self):
+        """Partial blank fallback (only one field blank) should warn."""
+        issues = validate_config_structure({
+            "fallback_model": {
+                "provider": "",
+                "model": "anthropic/claude-sonnet-4",
+            },
+        })
+        fb_issues = [i for i in issues if "fallback" in i.message.lower()]
+        assert len(fb_issues) == 1
+        assert "provider" in fb_issues[0].message
+
+    def test_valid_fallback_with_enabled_true(self):
+        """Valid fallback with enabled: true should not warn."""
+        issues = validate_config_structure({
+            "fallback_model": {
+                "enabled": True,
+                "provider": "openrouter",
+                "model": "anthropic/claude-sonnet-4",
+            },
+        })
+        fb_issues = [i for i in issues if "fallback" in i.message.lower()]
+        assert len(fb_issues) == 0
+
 
 class TestMissingModelSection:
     """Warn when custom_providers exists but model section is missing."""

tests/test_model_tools.py

@@ -137,3 +137,78 @@ class TestBackwardCompat:
     def test_tool_to_toolset_map(self):
         assert isinstance(TOOL_TO_TOOLSET_MAP, dict)
         assert len(TOOL_TO_TOOLSET_MAP) > 0
+
+
+class TestToolReturnTypeValidation:
+    """Poka-yoke: tool handlers must return JSON strings."""
+
+    def test_handler_returning_dict_is_wrapped(self, monkeypatch):
+        """A handler that returns a dict should be auto-wrapped to JSON string."""
+        from tools.registry import registry
+        from model_tools import handle_function_call
+        import json
+
+        # Register a bad handler that returns dict instead of str
+        registry.register(
+            name="__test_bad_dict",
+            toolset="test",
+            schema={"name": "__test_bad_dict", "description": "test", "parameters": {"type": "object", "properties": {}}},
+            handler=lambda args, **kw: {"this is": "a dict not a string"},
+        )
+        result = handle_function_call("__test_bad_dict", {})
+        parsed = json.loads(result)
+        assert "output" in parsed
+        assert "_type_warning" in parsed
+        # Cleanup
+        registry._tools.pop("__test_bad_dict", None)
+
+    def test_handler_returning_none_is_wrapped(self, monkeypatch):
+        """A handler that returns None should be auto-wrapped."""
+        from tools.registry import registry
+        from model_tools import handle_function_call
+        import json
+
+        registry.register(
+            name="__test_bad_none",
+            toolset="test",
+            schema={"name": "__test_bad_none", "description": "test", "parameters": {"type": "object", "properties": {}}},
+            handler=lambda args, **kw: None,
+        )
+        result = handle_function_call("__test_bad_none", {})
+        parsed = json.loads(result)
+        assert "_type_warning" in parsed
+        registry._tools.pop("__test_bad_none", None)
+
+    def test_handler_returning_non_json_string_is_wrapped(self):
+        """A handler returning a plain string (not JSON) should be wrapped."""
+        from tools.registry import registry
+        from model_tools import handle_function_call
+        import json
+
+        registry.register(
+            name="__test_bad_plain",
+            toolset="test",
+            schema={"name": "__test_bad_plain", "description": "test", "parameters": {"type": "object", "properties": {}}},
+            handler=lambda args, **kw: "just a plain string, not json",
+        )
+        result = handle_function_call("__test_bad_plain", {})
+        parsed = json.loads(result)
+        assert "output" in parsed
+        registry._tools.pop("__test_bad_plain", None)
+
+    def test_handler_returning_valid_json_passes_through(self):
+        """A handler returning valid JSON string passes through unchanged."""
+        from tools.registry import registry
+        from model_tools import handle_function_call
+        import json
+
+        registry.register(
+            name="__test_good",
+            toolset="test",
+            schema={"name": "__test_good", "description": "test", "parameters": {"type": "object", "properties": {}}},
+            handler=lambda args, **kw: json.dumps({"status": "ok", "data": [1, 2, 3]}),
+        )
+        result = handle_function_call("__test_good", {})
+        parsed = json.loads(result)
+        assert parsed == {"status": "ok", "data": [1, 2, 3]}
+        registry._tools.pop("__test_good", None)

tests/tools/test_memory_tool.py

@@ -144,7 +144,8 @@ class TestMemoryStoreReplace:
     def test_replace_no_match(self, store):
         store.add("memory", "fact A")
         result = store.replace("memory", "nonexistent", "new")
-        assert result["success"] is False
+        assert result["success"] is True
+        assert result["result"] == "no_match"
 
     def test_replace_ambiguous_match(self, store):
         store.add("memory", "server A runs nginx")
@@ -177,7 +178,8 @@ class TestMemoryStoreRemove:
 
     def test_remove_no_match(self, store):
         result = store.remove("memory", "nonexistent")
-        assert result["success"] is False
+        assert result["success"] is True
+        assert result["result"] == "no_match"
 
     def test_remove_empty_old_text(self, store):
         result = store.remove("memory", "  ")

tools/memory_tool.py

@@ -260,8 +260,12 @@ class MemoryStore:
             entries = self._entries_for(target)
             matches = [(i, e) for i, e in enumerate(entries) if old_text in e]
 
-            if len(matches) == 0:
-                return {"success": False, "error": f"No entry matched '{old_text}'."}
+            if not matches:
+                return {
+                    "success": True,
+                    "result": "no_match",
+                    "message": f"No entry matched '{old_text}'. The search substring was not found in any existing entry.",
+                }
 
             if len(matches) > 1:
                 # If all matches are identical (exact duplicates), operate on the first one
@@ -310,8 +314,12 @@ class MemoryStore:
             entries = self._entries_for(target)
             matches = [(i, e) for i, e in enumerate(entries) if old_text in e]
 
-            if len(matches) == 0:
-                return {"success": False, "error": f"No entry matched '{old_text}'."}
+            if not matches:
+                return {
+                    "success": True,
+                    "result": "no_match",
+                    "message": f"No entry matched '{old_text}'. The search substring was not found in any existing entry.",
+                }
 
             if len(matches) > 1:
                 # If all matches are identical (exact duplicates), remove the first one
@@ -449,30 +457,30 @@ def memory_tool(
     Returns JSON string with results.
     """
     if store is None:
-        return json.dumps({"success": False, "error": "Memory is not available. It may be disabled in config or this environment."}, ensure_ascii=False)
+        return tool_error("Memory is not available. It may be disabled in config or this environment.", success=False)
 
     if target not in ("memory", "user"):
-        return json.dumps({"success": False, "error": f"Invalid target '{target}'. Use 'memory' or 'user'."}, ensure_ascii=False)
+        return tool_error(f"Invalid target '{target}'. Use 'memory' or 'user'.", success=False)
 
     if action == "add":
         if not content:
-            return json.dumps({"success": False, "error": "Content is required for 'add' action."}, ensure_ascii=False)
+            return tool_error("Content is required for 'add' action.", success=False)
         result = store.add(target, content)
 
     elif action == "replace":
         if not old_text:
-            return json.dumps({"success": False, "error": "old_text is required for 'replace' action."}, ensure_ascii=False)
+            return tool_error("old_text is required for 'replace' action.", success=False)
         if not content:
-            return json.dumps({"success": False, "error": "content is required for 'replace' action."}, ensure_ascii=False)
+            return tool_error("content is required for 'replace' action.", success=False)
         result = store.replace(target, old_text, content)
 
     elif action == "remove":
         if not old_text:
-            return json.dumps({"success": False, "error": "old_text is required for 'remove' action."}, ensure_ascii=False)
+            return tool_error("old_text is required for 'remove' action.", success=False)
         result = store.remove(target, old_text)
 
     else:
-        return json.dumps({"success": False, "error": f"Unknown action '{action}'. Use: add, replace, remove"}, ensure_ascii=False)
+        return tool_error(f"Unknown action '{action}'. Use: add, replace, remove", success=False)
 
     return json.dumps(result, ensure_ascii=False)
 
@@ -539,7 +547,7 @@ MEMORY_SCHEMA = {
 
 
 # --- Registry ---
-from tools.registry import registry
+from tools.registry import registry, tool_error
 
 registry.register(
     name="memory",