Improve subagent failure result for provider errors

When a subagent dies on a provider error the parent agent tends to
give up on it and do the task itself. The failure result now includes
the rate limit reset time and a hint to re-spawn the agent (optionally
with another model) for transient errors, or to switch model for
permanent ones. Anthropic error bodies are parsed so the error code
and a clean message replace the raw status/body dump.

Author: ericdallo

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Improve subagent failure result: rate-limit reset time, parsed Anthropic error code, and retry guidance so the parent agent can re-spawn or switch model.
+
 ## 0.157.0
 
 - Add `chat/inlinePrompt` protocol method: inline editor prompts backed by regular chats, optionally forking an existing chat without replay. New `chatInline` config for model/agent/variant defaults.

src/eca/features/tools/agent.clj

@@ -4,6 +4,7 @@
    [clojure.string :as str]
    [eca.config :as config]
    [eca.features.tools.util :as tools.util]
+   [eca.llm-providers.errors :as llm-providers.errors]
    [eca.logger :as logger]
    [eca.messenger :as messenger]
    [eca.models :as models]
@@ -66,8 +67,16 @@
   (or (extract-final-assistant-text messages)
       "Agent completed without producing output."))
 
+(defn ^:private failure-guidance
+  "Actionable next-step hint for the parent agent based on the error type."
+  [error-type]
+  (when error-type
+    (if (contains? llm-providers.errors/retryable-error-types error-type)
+      "This is a transient provider error. Prefer spawning this agent again for the same task (optionally with a different `model`) instead of performing the task yourself."
+      "Retrying this agent the same way is unlikely to help. Consider spawning it again with a different `model` or handling the task yourself.")))
+
 (defn ^:private failed-agent-result [agent-name prompt-error partial-output]
-  (let [{:keys [message error-type status code request-id response-id]} prompt-error]
+  (let [{:keys [message error-type status code request-id response-id rate-limit-resets-at]} prompt-error]
     {:error true
      :contents [{:type :text
                  :text (str "## Agent '" agent-name "' Failed\n\n"
@@ -82,6 +91,10 @@
                               (str "\nRequest ID: " request-id))
                             (when response-id
                               (str "\nResponse ID: " response-id))
+                            (when rate-limit-resets-at
+                              (str "\nRate limit resets at: " (java.time.Instant/ofEpochMilli (long rate-limit-resets-at))))
+                            (when-let [guidance (failure-guidance error-type)]
+                              (str "\n\n" guidance))
                             (when partial-output
                               (str "\n\n## Partial result\n\n" partial-output)))}]}))
 

src/eca/llm_providers/errors.clj

@@ -215,6 +215,31 @@
 
 (defmethod enrich-provider-error :default [{:keys [error-data]}] error-data)
 
+(defn ^:private anthropic-structured-error
+  "Parses Anthropic's structured error body, e.g.
+   {\"type\":\"error\",\"error\":{\"type\":\"rate_limit_error\",\"message\":\"...\"},\"request_id\":\"...\"}.
+   Returns {:code .. :message .. :request-id ..} or nil when not parseable."
+  [body]
+  (when (string? body)
+    (let [parsed (try (json/parse-string body) (catch Exception _ nil))
+          error (when (map? parsed) (get parsed "error"))
+          code (when (map? error) (get error "type"))
+          message (when (map? error) (get error "message"))]
+      (when (or code message)
+        (cond-> {}
+          code (assoc :code code)
+          message (assoc :message message)
+          (get parsed "request_id") (assoc :request-id (get parsed "request_id")))))))
+
+(defmethod enrich-provider-error "anthropic"
+  [{:keys [error-data]}]
+  (if-let [{:keys [code message request-id]} (anthropic-structured-error (:body error-data))]
+    (cond-> error-data
+      code (assoc :code code)
+      message (assoc :message (str "Anthropic " (or code "error") ": " message))
+      request-id (assoc :request-id request-id))
+    error-data))
+
 (defmulti recoverable-error?
   "Pure predicate: true when the provider offers an interactive recovery for
    this terminal error (e.g. Copilot per-model policy consent). Dispatches on

test/eca/features/tools/agent_test.clj

@@ -305,6 +305,64 @@
                                    :text #"(?s)Failed.*servers are currently overloaded.*Error type: overloaded.*Request ID: req_overloaded.*Partial result.*Partial findings"}]}
                       result))))))
 
+  (testing "rate-limited error includes reset time and retry guidance"
+    (let [db* (atom {:chats {"chat-1" {:id "chat-1" :model "test/model"}}})
+          subagent-chat-id "subagent-tc-rate-limited"]
+      (with-redefs [requiring-resolve
+                    (fn [sym]
+                      (case sym
+                        eca.features.chat/prompt
+                        (fn [_params _db* _messenger _config _metrics]
+                          (swap! db* assoc-in [:chats subagent-chat-id :status] :idle)
+                          (swap! db* assoc-in [:chats subagent-chat-id :prompt-error]
+                                 {:message "Anthropic rate_limit_error: This request would exceed your rate limit"
+                                  :error-type :rate-limited
+                                  :status 429
+                                  :code "rate_limit_error"
+                                  :rate-limit-resets-at 1756204800000}))
+                        (clojure.lang.RT/var (namespace sym) (name sym))))]
+        (let [result ((spawn-handler)
+                      {"agent" "explorer" "task" "find files"}
+                      {:db* db*
+                       :config test-config
+                       :messenger (h/messenger)
+                       :metrics (h/metrics)
+                       :chat-id "chat-1"
+                       :tool-call-id "tc-rate-limited"
+                       :call-state-fn (constantly {:status :executing})})]
+          (is (match? {:error true
+                       :contents [{:type :text
+                                   :text #"(?s)Failed.*rate limit.*Error type: rate-limited.*Status: 429.*Code: rate_limit_error.*Rate limit resets at: 2025-08-26T10:40:00Z.*transient provider error\. Prefer spawning this agent again"}]}
+                      result))))))
+
+  (testing "non-retryable error advises against retrying the same way"
+    (let [db* (atom {:chats {"chat-1" {:id "chat-1" :model "test/model"}}})
+          subagent-chat-id "subagent-tc-auth"]
+      (with-redefs [requiring-resolve
+                    (fn [sym]
+                      (case sym
+                        eca.features.chat/prompt
+                        (fn [_params _db* _messenger _config _metrics]
+                          (swap! db* assoc-in [:chats subagent-chat-id :status] :idle)
+                          (swap! db* assoc-in [:chats subagent-chat-id :prompt-error]
+                                 {:message "Invalid API key"
+                                  :error-type :auth
+                                  :status 401}))
+                        (clojure.lang.RT/var (namespace sym) (name sym))))]
+        (let [result ((spawn-handler)
+                      {"agent" "explorer" "task" "find files"}
+                      {:db* db*
+                       :config test-config
+                       :messenger (h/messenger)
+                       :metrics (h/metrics)
+                       :chat-id "chat-1"
+                       :tool-call-id "tc-auth"
+                       :call-state-fn (constantly {:status :executing})})]
+          (is (match? {:error true
+                       :contents [{:type :text
+                                   :text #"(?s)Failed.*Invalid API key.*Error type: auth.*Status: 401.*unlikely to help"}]}
+                      result))))))
+
   (testing "an error status without structured details still returns failure"
     (let [db* (atom {:chats {"chat-1" {:id "chat-1" :model "test/model"}}})
           subagent-chat-id "subagent-tc-error-status"]

test/eca/llm_providers/errors_test.clj

@@ -13,6 +13,43 @@
       (is (nil? (llm-providers.errors/recover-error!
                  {:provider "unknown" :error-data error-data :db {}}))))))
 
+(deftest enrich-anthropic-provider-error-test
+  (let [body "{\"type\":\"error\",\"error\":{\"type\":\"rate_limit_error\",\"message\":\"This request would exceed your rate limit\"},\"request_id\":\"req_123\"}"]
+    (testing "structured error body populates code, message and request-id, keeping raw body"
+      (is (= {:status 429
+              :body body
+              :message "Anthropic rate_limit_error: This request would exceed your rate limit"
+              :code "rate_limit_error"
+              :request-id "req_123"}
+             (llm-providers.errors/enrich-provider-error
+              {:provider "anthropic"
+               :model "m"
+               :error-data {:status 429
+                            :body body
+                            :message "Anthropic response status: 429 body: ..."}}))))
+
+    (testing "enriched error still classifies as rate-limited"
+      (is (= {:error/type :rate-limited}
+             (llm-providers.errors/classify-error
+              (llm-providers.errors/enrich-provider-error
+               {:provider "anthropic"
+                :model "m"
+                :error-data {:status 429
+                             :body body
+                             :message "Anthropic response status: 429 body: ..."}})))))
+
+    (testing "non-JSON body keeps error untouched"
+      (let [error-data {:status 502
+                        :body "<html>bad gateway</html>"
+                        :message "Anthropic response status: 502 body: <html>bad gateway</html>"}]
+        (is (= error-data (llm-providers.errors/enrich-provider-error
+                           {:provider "anthropic" :model "m" :error-data error-data})))))
+
+    (testing "missing body keeps error untouched"
+      (let [error-data {:message "Anthropic error response: something went wrong"}]
+        (is (= error-data (llm-providers.errors/enrich-provider-error
+                           {:provider "anthropic" :model "m" :error-data error-data})))))))
+
 (deftest classify-error-context-overflow-test
   (testing "Anthropic prompt too long"
     (is (= {:error/type :context-overflow}