Support AGENTS.md from parent directories via includeParentAgentsFiles flag

ericdallo · eca-agent · ericdallo · commit afb0c6c6a083 · 2026-05-13T11:25:38.000-03:00
When working in nested workspaces (e.g. /a/b/c/d), project-wide guidance often lives in an AGENTS.md higher up the tree. Previously ECA only looked at the workspace root and the global config dir, forcing users to symlink or duplicate guidance. Adds a new top-level boolean config `includeParentAgentsFiles` (default false). When enabled, AGENTS.md files from each workspace folder's parent chain are included, ordered outermost parent first, then the workspace's own AGENTS.md, then the global file. A shared visited set deduplicates files across overlapping workspaces, and @-mention recursion is preserved. 🤖 Generated with [eca](https://eca.dev) Co-Authored-By: eca-agent <git@eca.dev>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Support including `AGENTS.md` files from parent directories of each workspace folder via new `includeParentAgentsFiles` config flag (disabled by default), ordered outermost parent first.
+
 ## 0.133.6
 
 - Bugfix: `network.caCertFile` (and `clientCert`/`clientKey`/`clientKeyPassphrase`) set via `config.json` were silently ignored due to a key-case mismatch between config normalization and the network reader; only the env-var fallbacks worked. #457
diff --git a/docs/config.json b/docs/config.json
@@ -194,6 +194,12 @@
       "maximum": 100,
       "default": 75
     },
+    "includeParentAgentsFiles": {
+      "type": "boolean",
+      "description": "When true, also include AGENTS.md files from each workspace folder's parent directories, ordered outermost parent first, then the workspace's own AGENTS.md.",
+      "markdownDescription": "When `true`, also include `AGENTS.md` files from each workspace folder's parent directories, ordered outermost parent first, then the workspace's own `AGENTS.md`.",
+      "default": false
+    },
     "index": {
       "type": "object",
       "description": "Indexing configuration for workspace files.",
diff --git a/docs/features.md b/docs/features.md
@@ -111,6 +111,8 @@ So user can include those contexts in 3 different ways for different purposes:
 
 ECA will always include if found the `AGENTS.md` file as context, searching for both `/project-root/AGENTS.md` and `~/.config/eca/AGENTS.md`, it will recursively check for any `@some-file.md` mention as well.
 
+Set the config flag `includeParentAgentsFiles` to `true` to also include `AGENTS.md` files from each workspace's parent directories (up to the filesystem root). Files are emitted outermost parent first, then descending toward the workspace's own `AGENTS.md`, and duplicates across overlapping workspaces are skipped. The flag is disabled by default.
+
 You can ask ECA to create/update this file via `/init` command.
 you can check/debug what goes to final prompt with `/prompt-show` as well.
 
diff --git a/src/eca/config.clj b/src/eca/config.clj
@@ -224,6 +224,7 @@
    :completion {:model "openai/gpt-4.1"}
    :netrcFile nil
    :autoCompactPercentage 75
+   :includeParentAgentsFiles false
    :plugins {"eca" {:source "https://github.com/editor-code-assistant/eca-plugins.git"}}
    :remote {:enabled false}
    :env "prod"})
diff --git a/src/eca/features/chat.clj b/src/eca/features/chat.clj
@@ -1185,7 +1185,7 @@
                                                                                       :state :running
                                                                                       :text "Parsing given context"}))
         refined-contexts (concat
-                          (f.context/agents-file-contexts db)
+                          (f.context/agents-file-contexts db config)
                           (f.context/raw-contexts->refined contexts db))
         {static-rules :static path-scoped-rules :path-scoped} (f.rules/all-rules config (:workspace-folders db) agent full-model)
         all-tools (f.tools/all-tools chat-id agent @db* config)
diff --git a/src/eca/features/context.clj b/src/eca/features/context.clj
@@ -55,24 +55,57 @@
                  nested-results))
        []))))
 
+(defn ^:private ancestor-paths
+  "Return all ancestor directories of `path` in outermost-first order.
+   Excludes `path` itself."
+  [path]
+  (loop [p (fs/parent path)
+         acc '()]
+    (if (nil? p)
+      (vec acc)
+      (recur (fs/parent p) (conj acc p)))))
+
+(defn ^:private safe-canonicalize
+  "Canonicalize `path`, falling back to a non-resolved `fs/path` if the
+   path does not exist (e.g. a stale workspace folder or test fixture)."
+  [path]
+  (try (fs/canonicalize path)
+       (catch Exception _ (fs/path path))))
+
 (defn agents-file-contexts
   "Search for AGENTS.md file both in workspaceRoot and global config dir.
+   When `:includeParentAgentsFiles` is true in `config`, also include
+   AGENTS.md files from each workspace's parent directories, ordered
+   outermost parent first, then the workspace's own AGENTS.md.
    Process any found @paths mentions recursively, supporting both relative and absolute paths.
    Deduplicates files to avoid reading the same file multiple times."
-  [db]
+  [db config]
   ;; TODO make it customizable by agent
-  (let [agent-file "AGENTS.md"
-        local-agent-files (keep (fn [{:keys [uri]}]
-                                  (let [agent-file (fs/path (shared/uri->filename uri) agent-file)]
-                                    (when (fs/readable? agent-file)
-                                      (fs/canonicalize agent-file))))
-                                (:workspace-folders db))
-        global-agent-file (let [agent-file (fs/path (shared/global-config-dir) agent-file)]
-                            (when (fs/readable? agent-file)
-                              (fs/canonicalize agent-file)))]
-    (->> (concat local-agent-files
-                 (when global-agent-file [global-agent-file]))
-         (mapcat #(parse-agents-file (str %))))))
+  (let [agent-file-name "AGENTS.md"
+        include-parents? (boolean (:includeParentAgentsFiles config))
+        readable-agent-file-in (fn [dir]
+                                 (let [p (fs/path dir agent-file-name)]
+                                   (when (fs/readable? p)
+                                     (str (fs/canonicalize p)))))
+        {:keys [paths seen]}
+        (reduce
+         (fn [{:keys [paths seen]} {:keys [uri]}]
+           (let [ws-path (safe-canonicalize (shared/uri->filename uri))
+                 candidate-dirs (cond-> []
+                                  include-parents? (into (ancestor-paths ws-path))
+                                  true (conj ws-path))
+                 new-paths (->> candidate-dirs
+                                (keep readable-agent-file-in)
+                                (remove seen))]
+             {:paths (into paths new-paths)
+              :seen (into seen new-paths)}))
+         {:paths [] :seen #{}}
+         (:workspace-folders db))
+        global-agent-file (readable-agent-file-in (shared/global-config-dir))
+        all-paths (cond-> paths
+                    (and global-agent-file (not (contains? seen global-agent-file)))
+                    (conj global-agent-file))]
+    (mapcat parse-agents-file all-paths)))
 
 (defn ^:private file->refined-context [path lines-range]
   (if (fs/readable? path)
diff --git a/test/eca/features/context_test.clj b/test/eca/features/context_test.clj
@@ -7,7 +7,7 @@
    [eca.features.index :as f.index]
    [eca.features.tools.mcp :as f.mcp]
    [eca.llm-api :as llm-api]
-   [eca.shared :refer [multi-str]]
+   [eca.shared :as shared :refer [multi-str]]
    [eca.test-helper :as h]
    [matcher-combinators.matchers :as m]
    [matcher-combinators.test :refer [match?]]))
@@ -338,6 +338,130 @@
               :content a-content}])
            (#'f.context/parse-agents-file a-file))))))
 
+(deftest agents-file-contexts-test
+  (testing "Flag disabled: only the workspace's own AGENTS.md plus global"
+    (h/reset-components!)
+    (let [ws "/a/b/c/d"
+          ws-agents (str ws "/AGENTS.md")
+          global-dir "/global"
+          global-agents (str global-dir "/AGENTS.md")
+          readable #{ws-agents global-agents}]
+      (swap! (h/db*) assoc :workspace-folders [{:uri "file:///a/b/c/d"}])
+      (with-redefs [shared/uri->filename (constantly ws)
+                    shared/global-config-dir (constantly global-dir)
+                    fs/canonicalize identity
+                    fs/path (fn [& parts] (string/join "/" (map str parts)))
+                    fs/readable? (fn [p] (contains? readable (str p)))
+                    llm-api/refine-file-context (constantly "content")]
+        (is (match?
+             [{:type :agents-file :path ws-agents :content "content"}
+              {:type :agents-file :path global-agents :content "content"}]
+             (f.context/agents-file-contexts (h/db) {:includeParentAgentsFiles false}))))))
+
+  (testing "Flag enabled: parents emitted outermost first, then workspace, then global"
+    (h/reset-components!)
+    (let [ws "/a/b/c/d"
+          parent-ab-agents "/a/b/AGENTS.md"
+          parent-abc-agents "/a/b/c/AGENTS.md"
+          global-dir "/global"
+          global-agents (str global-dir "/AGENTS.md")
+          readable #{parent-ab-agents parent-abc-agents global-agents}
+          parent-map {"/a/b/c/d" "/a/b/c"
+                      "/a/b/c" "/a/b"
+                      "/a/b" "/a"
+                      "/a" "/"
+                      "/" nil}]
+      (swap! (h/db*) assoc :workspace-folders [{:uri "file:///a/b/c/d"}])
+      (with-redefs [shared/uri->filename (constantly ws)
+                    shared/global-config-dir (constantly global-dir)
+                    fs/canonicalize identity
+                    fs/parent (fn [p] (get parent-map (str p)))
+                    fs/path (fn [& parts] (string/join "/" (map str parts)))
+                    fs/readable? (fn [p] (contains? readable (str p)))
+                    llm-api/refine-file-context (constantly "content")]
+        (is (match?
+             [{:type :agents-file :path parent-ab-agents :content "content"}
+              {:type :agents-file :path parent-abc-agents :content "content"}
+              {:type :agents-file :path global-agents :content "content"}]
+             (f.context/agents-file-contexts (h/db) {:includeParentAgentsFiles true}))))))
+
+  (testing "Flag enabled but no parent has AGENTS.md: behaves like disabled"
+    (h/reset-components!)
+    (let [ws "/a/b/c/d"
+          ws-agents (str ws "/AGENTS.md")
+          global-dir "/global"
+          global-agents (str global-dir "/AGENTS.md")
+          readable #{ws-agents global-agents}
+          parent-map {"/a/b/c/d" "/a/b/c"
+                      "/a/b/c" "/a/b"
+                      "/a/b" "/a"
+                      "/a" "/"
+                      "/" nil}]
+      (swap! (h/db*) assoc :workspace-folders [{:uri "file:///a/b/c/d"}])
+      (with-redefs [shared/uri->filename (constantly ws)
+                    shared/global-config-dir (constantly global-dir)
+                    fs/canonicalize identity
+                    fs/parent (fn [p] (get parent-map (str p)))
+                    fs/path (fn [& parts] (string/join "/" (map str parts)))
+                    fs/readable? (fn [p] (contains? readable (str p)))
+                    llm-api/refine-file-context (constantly "content")]
+        (is (match?
+             [{:type :agents-file :path ws-agents :content "content"}
+              {:type :agents-file :path global-agents :content "content"}]
+             (f.context/agents-file-contexts (h/db) {:includeParentAgentsFiles true}))))))
+
+  (testing "Two nested workspaces share ancestors via dedup"
+    (h/reset-components!)
+    (let [a-agents "/a/AGENTS.md"
+          ab-agents "/a/b/AGENTS.md"
+          abc-agents "/a/b/c/AGENTS.md"
+          global-dir "/global"
+          global-agents (str global-dir "/AGENTS.md")
+          readable #{a-agents ab-agents abc-agents global-agents}
+          parent-map {"/a/b/c/d" "/a/b/c"
+                      "/a/b/c" "/a/b"
+                      "/a/b" "/a"
+                      "/a" "/"
+                      "/" nil}
+          uri->filename-map {"file:///a/b" "/a/b"
+                             "file:///a/b/c/d" "/a/b/c/d"}]
+      (swap! (h/db*) assoc :workspace-folders [{:uri "file:///a/b"}
+                                               {:uri "file:///a/b/c/d"}])
+      (with-redefs [shared/uri->filename (fn [u] (get uri->filename-map u))
+                    shared/global-config-dir (constantly global-dir)
+                    fs/canonicalize identity
+                    fs/parent (fn [p] (get parent-map (str p)))
+                    fs/path (fn [& parts] (string/join "/" (map str parts)))
+                    fs/readable? (fn [p] (contains? readable (str p)))
+                    llm-api/refine-file-context (constantly "content")]
+        (is (match?
+             [{:type :agents-file :path a-agents}
+              {:type :agents-file :path ab-agents}
+              {:type :agents-file :path abc-agents}
+              {:type :agents-file :path global-agents}]
+             (f.context/agents-file-contexts (h/db) {:includeParentAgentsFiles true}))))))
+
+  (testing "Workspace at filesystem root: no parent walk"
+    (h/reset-components!)
+    (let [ws "/"
+          ws-agents "//AGENTS.md"
+          global-dir "/global"
+          global-agents (str global-dir "/AGENTS.md")
+          readable #{ws-agents global-agents}
+          parent-map {"/" nil}]
+      (swap! (h/db*) assoc :workspace-folders [{:uri "file:///"}])
+      (with-redefs [shared/uri->filename (constantly ws)
+                    shared/global-config-dir (constantly global-dir)
+                    fs/canonicalize identity
+                    fs/parent (fn [p] (get parent-map (str p)))
+                    fs/path (fn [& parts] (string/join "/" (map str parts)))
+                    fs/readable? (fn [p] (contains? readable (str p)))
+                    llm-api/refine-file-context (constantly "content")]
+        (is (match?
+             [{:type :agents-file :path ws-agents}
+              {:type :agents-file :path global-agents}]
+             (f.context/agents-file-contexts (h/db) {:includeParentAgentsFiles true})))))))
+
 (deftest contexts-str-from-prompt-test
   (testing "not context mention"
     (is (match?
