Fix stale system prompt after switching agent mid-chat #411

Scope the chat-level prompt cache and OpenAI Responses prompt_cache_key
by the active agent so a mid-chat agent switch rebuilds the static
system prompt instead of reusing the first agent's cached one.

🤖 Generated with [eca](https://eca.dev)

Co-Authored-By: eca-agent <git@eca.dev>

Author: ericdallo

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- Fix stale system prompt being reused after switching agent mid-chat by scoping the chat-level prompt cache and the OpenAI Responses `prompt_cache_key` per active agent. #411
 - Improve chat title quality on 3rd-message retitle by filtering tool calls, tool results, reasoning and flag entries from the history passed to the title LLM, and by respecting the last compact marker.
 
 ## 0.128.0

src/eca/features/chat.clj

@@ -60,6 +60,15 @@
 (def ^:private cleared-raw-content
   [{:type "text" :text "[content cleared to reduce context size]"}])
 
+(defn ^:private prompt-cache-key
+  "Builds a provider-agnostic prompt cache key.
+   OpenAI's Responses API sends it as `prompt_cache_key`; other providers
+   currently ignore it. Scoping by agent prevents cache hits across
+   agent switches within the same user session."
+  [agent]
+  (str (System/getProperty "user.name") "@ECA"
+       (when (not-empty agent) (str "/" agent))))
+
 (defn ^:private prune-tool-results!
   "Prunes old tool result content from chat history to reduce context size.
    Walks messages backwards, protecting the most recent tool outputs up to
@@ -619,6 +628,7 @@
                                             (lifecycle/maybe-renew-auth-token chat-ctx)
                                             (get-in @db* [:auth provider]))
                 :variant (:variant chat-ctx)
+                :prompt-cache-key (prompt-cache-key agent)
                 :subagent? (some? (get-in @db* [:chats chat-id :subagent]))
                 :cancelled? (fn []
                               (let [chat (get-in @db* [:chats chat-id])]
@@ -1005,14 +1015,17 @@
                           (f.context/agents-file-contexts db)
                           (f.context/raw-contexts->refined contexts db))
         repo-map* (delay (f.index/repo-map db config {:as-string? true}))
-        cached-static (get-in db [:chats chat-id :prompt-cache :static])
+        prompt-cache (get-in db [:chats chat-id :prompt-cache])
+        cached-static (when (= (:agent prompt-cache) agent)
+                        (:static prompt-cache))
         instructions (if cached-static
                        {:static cached-static
                         :dynamic (f.prompt/build-dynamic-instructions refined-contexts db)}
                        (let [result (f.prompt/build-chat-instructions
                                      refined-contexts rules skills repo-map*
                                      agent config chat-id all-tools db)]
-                         (swap! db* assoc-in [:chats chat-id :prompt-cache :static] (:static result))
+                         (swap! db* update-in [:chats chat-id :prompt-cache]
+                                assoc :static (:static result) :agent agent)
                          result))
         image-contents (->> refined-contexts
                             (filter #(= :image (:type %))))

src/eca/llm_api.clj

@@ -172,7 +172,7 @@
 (defn ^:private prompt!
   [{:keys [provider model model-capabilities instructions user-messages config variant
            on-message-received on-error on-prepare-tool-call on-tools-called on-reason on-usage-updated on-server-web-search
-           past-messages tools provider-auth sync? subagent? cancelled?]
+           past-messages tools provider-auth sync? subagent? cancelled? prompt-cache-key]
     :or {on-error identity}}]
   (let [real-model (real-model-name model model-capabilities)
         tools (when (:tools model-capabilities) tools)
@@ -220,7 +220,8 @@
           :api-url api-url
           :api-key api-key
           :auth-type auth-type
-          :account-id (:account-id provider-auth)}
+          :account-id (:account-id provider-auth)
+          :prompt-cache-key prompt-cache-key}
          callbacks)
 
         (= "anthropic" provider)
@@ -267,7 +268,8 @@
                                                extra-payload)
                          :reasoning-history reasoning-history
                          :api-url api-url
-                         :api-key api-key}]
+                         :api-key api-key
+                         :prompt-cache-key prompt-cache-key}]
           (if (= :openai-responses (:api api-handler))
             (handler
              (assoc base-opts
@@ -356,7 +358,7 @@
 (defn sync-or-async-prompt!
   [{:keys [provider model model-capabilities instructions user-messages config on-first-response-received
            on-message-received on-error on-prepare-tool-call on-tools-called on-reason on-usage-updated on-server-web-search
-           past-messages tools provider-auth refresh-provider-auth-fn variant cancelled? on-retry subagent?]
+           past-messages tools provider-auth refresh-provider-auth-fn variant cancelled? on-retry subagent? prompt-cache-key]
     :or {on-first-response-received identity
          on-message-received identity
          on-error identity
@@ -450,6 +452,7 @@
                               :user-messages user-messages
                               :variant variant
                               :subagent? subagent?
+                              :prompt-cache-key prompt-cache-key
                               :on-error on-error-wrapper
                               :config config})]
                 (let [{:keys [error output-text reason-text reasoning-content tools-to-call call-tools-fn reason-id usage]} result]
@@ -485,6 +488,7 @@
                 :user-messages user-messages
                 :variant variant
                 :subagent? subagent?
+                :prompt-cache-key prompt-cache-key
                 :cancelled? cancelled?
                 :on-message-received on-message-received-wrapper
                 :on-prepare-tool-call on-prepare-tool-call-wrapper

src/eca/llm_providers/openai.clj

@@ -153,7 +153,8 @@
     (and web-search (not codex?)) (conj {:type "web_search_preview"})))
 
 (defn create-response! [{:keys [model user-messages instructions reason? supports-image? api-key api-url url-relative-path
-                                max-output-tokens past-messages tools web-search extra-payload extra-headers auth-type account-id http-client]}
+                                max-output-tokens past-messages tools web-search extra-payload extra-headers auth-type account-id http-client
+                                prompt-cache-key]}
                         {:keys [on-message-received on-error on-prepare-tool-call on-tools-called on-reason on-usage-updated on-server-web-search] :as callbacks}]
   (let [codex? (= :auth/oauth auth-type)
         input (concat (normalize-messages past-messages supports-image?)
@@ -165,7 +166,8 @@
                 :input (if codex?
                          (concat [{:role "system" :content instructions}] input)
                          input)
-                :prompt_cache_key (str (System/getProperty "user.name") "@ECA")
+                :prompt_cache_key (or prompt-cache-key
+                                      (str (System/getProperty "user.name") "@ECA"))
                 :instructions instructions
                 :tools tools
                 :include (when reason?

test/eca/features/chat_test.clj

@@ -979,4 +979,55 @@
                 :role "assistant"}]}
              (h/messages)))))))
 
+(deftest prompt-cache-agent-switch-test
+  (testing "Static prompt cache is rebuilt when switching agents within the same chat"
+    (h/reset-components!)
+    (let [build-calls* (atom 0)
+          real-build f.prompt/build-chat-instructions]
+      (with-redefs [f.prompt/build-chat-instructions
+                    (fn [& args]
+                      (swap! build-calls* inc)
+                      (apply real-build args))
+                    ;; Test config doesn't populate :agent, so validate-agent-name
+                    ;; would fall back to "code" for every input. Short-circuit it
+                    ;; so the test can actually exercise an agent switch.
+                    config/validate-agent-name (fn [agent-name _config] agent-name)]
+        (let [mocks {:all-tools-mock (constantly [])
+                     :api-mock (fn [{:keys [on-message-received]}]
+                                 (on-message-received {:type :finish}))}
+              {:keys [chat-id]} (prompt! {:message "Hi" :agent "code"} mocks)]
+          (is (= 1 @build-calls*)
+              "First prompt should build the static instructions once")
+          (h/reset-messenger!)
+          (prompt! {:message "Still code" :chat-id chat-id :agent "code"} mocks)
+          (is (= 1 @build-calls*)
+              "Second prompt with the same agent should reuse cached instructions")
+          (h/reset-messenger!)
+          (prompt! {:message "Switch to plan" :chat-id chat-id :agent "plan"} mocks)
+          (is (= 2 @build-calls*)
+              "Switching agent should invalidate the cache and rebuild instructions")
+          (h/reset-messenger!)
+          (prompt! {:message "Back to code" :chat-id chat-id :agent "code"} mocks)
+          (is (= 3 @build-calls*)
+              "Switching back to the first agent should also trigger a rebuild"))))))
+
+(deftest prompt-cache-key-includes-agent-test
+  (testing "sync-or-async-prompt! receives prompt-cache-key scoped by active agent"
+    (h/reset-components!)
+    (with-redefs [config/validate-agent-name (fn [agent-name _config] agent-name)]
+      (let [captured* (atom [])
+            mocks {:all-tools-mock (constantly [])
+                   :api-mock (fn [{:keys [on-message-received] :as params}]
+                               (swap! captured* conj (:prompt-cache-key params))
+                               (on-message-received {:type :finish}))}
+            {:keys [chat-id]} (prompt! {:message "hi" :agent "code"} mocks)]
+        (h/reset-messenger!)
+        (prompt! {:message "hello" :chat-id chat-id :agent "plan"} mocks)
+        (is (= 2 (count @captured*)))
+        (is (every? some? @captured*))
+        (is (string/ends-with? (first @captured*) "/code")
+            "First prompt's cache key should be suffixed by /code")
+        (is (string/ends-with? (second @captured*) "/plan")
+            "Second prompt's cache key should be suffixed by /plan")))))
+
 

test/eca/llm_providers/openai_test.clj

@@ -291,6 +291,40 @@
                     (first @tools-called*)))
         (is (= 2 (count @requests*)))))))
 
+(deftest create-response-prompt-cache-key-test
+  (testing "prompt_cache_key uses the provided :prompt-cache-key verbatim"
+    (let [requests* (atom [])]
+      (with-redefs [llm-providers.openai/base-responses-request!
+                    (fn [{:keys [on-stream] :as opts}]
+                      (swap! requests* conj opts)
+                      (on-stream "response.completed"
+                                 {:response {:output []
+                                             :usage {:input_tokens 0 :output_tokens 0}
+                                             :status "completed"}}))]
+        (llm-providers.openai/create-response!
+         (assoc (base-provider-params) :prompt-cache-key "alice@ECA/plan")
+         (base-callbacks {}))
+        (is (= 1 (count @requests*)))
+        (is (= "alice@ECA/plan"
+               (get-in (first @requests*) [:body :prompt_cache_key]))
+            "Body should pass the caller-supplied cache key unchanged"))))
+  (testing "prompt_cache_key falls back to $USER@ECA when :prompt-cache-key is absent"
+    (let [requests* (atom [])]
+      (with-redefs [llm-providers.openai/base-responses-request!
+                    (fn [{:keys [on-stream] :as opts}]
+                      (swap! requests* conj opts)
+                      (on-stream "response.completed"
+                                 {:response {:output []
+                                             :usage {:input_tokens 0 :output_tokens 0}
+                                             :status "completed"}}))]
+        (llm-providers.openai/create-response!
+         (base-provider-params)
+         (base-callbacks {}))
+        (is (= 1 (count @requests*)))
+        (is (= (str (System/getProperty "user.name") "@ECA")
+               (get-in (first @requests*) [:body :prompt_cache_key]))
+            "Body should use the default $USER@ECA key when no cache key is provided")))))
+
 (deftest create-response-tool-calls-fallback-via-atom-test
   (testing "empty output in response.completed still triggers on-tools-called via atom fallback"
     (let [tools-called* (atom [])