fix: classify tool-runtime failures and fail safely

CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [Unreleased]
+
+### Added
+
+- Structured tool failure categories, stable fallback actions, and public adapter exceptions.
+- Secret-free `tool_fallback_decision` audit events.
+- Exact regression coverage for the Strix `Tool execute_command not found in agent strix` failure.
+
+### Changed
+
+- Agent invocation now retries explicitly idempotent transient tool failures with bounded exponential backoff within a per-agent budget.
+- A shared four-attempt ceiling now bounds the configured same-agent tool retry budget.
+- Fail-closed tool decisions now have dedicated JSON and SSE error contracts, and preserve the observed failure kind in secret-free audit evidence.
+- Missing or unavailable tools move to the next eligible agent instead of terminating the workflow immediately.
+
+### Security
+
+- Ambiguous non-idempotent outcomes, invalid arguments, permission denial, and policy denial fail closed.
+- Fallback errors and audit events do not copy provider exception text, tool arguments, outputs, or credentials; fail-closed exceptions also sever the original cause chain so later traceback logging cannot recover them.

README.md

@@ -304,6 +304,7 @@ python tests/test_admin_contract.py
 python tests/test_conventions.py
 python tests/test_api_contract.py
 python tests/test_security_hardening.py
+python tests/test_tool_execution_fallback.py
 python tests/test_repository_security_metadata.py
 python tests/test_product_planning_contract.py
 python tests/test_plugin_driven_artifacts.py

contextual_orchestrator/__init__.py

@@ -39,6 +39,15 @@
 from .kv_config import InMemoryConfigStore, get_config_store
 from .orchestrator import ModelAgent, TaskOrchestrator, WorkflowStep, load_agents
 from .token_counting import HeuristicTokenCounter, build_token_counter
+from .tool_fallback import (
+    MAX_TOOL_RETRY_ATTEMPTS,
+    ToolExecutionError,
+    ToolFallbackAction,
+    ToolFallbackStoppedError,
+    ToolFailureDecision,
+    ToolFailureKind,
+    classify_tool_failure,
+)
 
 __all__ = [
     "ModelAgent",
@@ -48,6 +57,14 @@
     "get_credential",
     "register_credential",
     "NotConfigured",
+    "MAX_TOOL_RETRY_ATTEMPTS",
+    # tool fallback
+    "ToolExecutionError",
+    "ToolFallbackAction",
+    "ToolFallbackStoppedError",
+    "ToolFailureDecision",
+    "ToolFailureKind",
+    "classify_tool_failure",
     # cost review
     "ATTRIBUTION_DIMENSIONS",
     "AttributionDimensions",

contextual_orchestrator/model_discovery.py

@@ -30,6 +30,19 @@
 DISCOVERY_TIMEOUT_SECONDS = 15.0
 
 
+def _provider_discovery_error_code(exc: Exception) -> str:
+    """Map provider failures to stable codes without retaining provider response text."""
+    if isinstance(exc, urllib.error.HTTPError):
+        return f"http_status_{exc.code}"
+    if isinstance(exc, TimeoutError):
+        return "timeout"
+    if isinstance(exc, urllib.error.URLError):
+        return "transport_error"
+    if isinstance(exc, ValueError):
+        return "invalid_response"
+    return "provider_error"
+
+
 @dataclass(frozen=True)
 class ProviderModelSource:
     """Where and how to discover one provider's models."""
@@ -99,9 +112,10 @@ class DiscoveredModel:
 class ProviderDiscoveryError(RuntimeError):
     """Raised when a provider's model list could not be fetched (network/auth failure)."""
 
-    def __init__(self, provider_name: str, detail: str) -> None:
+    def __init__(self, provider_name: str, error_code: str) -> None:
         self.provider_name = provider_name
-        super().__init__(f"model discovery failed for provider {provider_name!r}: {detail}")
+        self.error_code = error_code
+        super().__init__(f"model discovery failed for provider {provider_name!r}: {error_code}")
 
 
 def _fetch_json(url: str, *, api_key: str, auth_scheme: str, timeout: float) -> Any:
@@ -191,7 +205,7 @@ def discover_provider_models(
     try:
         payload = _fetch_json(url, api_key=api_key, auth_scheme=source.auth_scheme, timeout=timeout)
     except (urllib.error.URLError, TimeoutError, ValueError) as exc:  # pragma: no cover - network path
-        raise ProviderDiscoveryError(source.provider_name, str(exc)) from exc
+        raise ProviderDiscoveryError(source.provider_name, _provider_discovery_error_code(exc)) from None
     if source.style == "bytez":
         return _parse_bytez(payload, source)
     return _parse_openai_compatible(payload, source)