Accept tools: as a YAML list in markdown agents (Claude form)

Markdown agents written for Claude Code or OpenCode commonly express
allowed tools as a flat list (tools: [read, search, agent]) rather
than as ECA's byDefault/allow/deny map. The parser previously called
(into {} <list-of-strings>), which throws, and the exception was
swallowed by agent-md-file->agent, silently dropping the whole agent.
The tools field is now normalized: map form is unchanged, sequential
form is wrapped as byDefault: ask + allow: <list>, and any other
shape is ignored without crashing. Adds unit tests plus an end-to-end
plugin test using the reporter's exact frontmatter.

Author: ericdallo

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Markdown agents now accept `tools:` as a flat YAML list (Claude convention), normalized to `byDefault: ask` + `allow`. Previously such agents were silently dropped.
+
 ## 0.134.5
 
 - Markdown agents now honor the YAML `name:` field and strip all filename extensions for the agent id (e.g. `foo.agent.md` → `foo`), matching Claude/OpenCode plugin conventions.

docs/config/agents.md

@@ -142,6 +142,18 @@ Subagents can be configured in config or markdown and support/require these fiel
 
         This is equivalent to `argsMatchers` in JSON config. Patterns on tools other than `eca__shell_command` are currently ignored.
 
+    !!! info "Claude-compatible tools list"
+
+        For Claude Code / OpenCode plugin compatibility, `tools` can also be given as a flat YAML list. It is treated as `byDefault: ask` plus the list as `allow`:
+
+        ```yaml
+        tools:
+          - eca__read_file
+          - eca__grep
+        ```
+
+        The entries must be ECA tool ids for the allowlist to take effect; unknown names are accepted but will not match any real tool.
+
     !!! info "Tool call approval"
         
         For more complex tool call approval, use toolCall via config

src/eca/features/agents.clj

@@ -48,29 +48,41 @@
      {}
      tool-entries)))
 
+(defn ^:private normalize-tools
+  "Coerces the YAML `tools:` value into the map form ECA expects.
+   - Map form is returned as-is (ECA convention: byDefault/allow/ask/deny).
+   - Sequential form (Claude convention: a flat list of allowed tool names)
+     is normalized to {byDefault ask, allow <list>}.
+   - Any other shape (string, number, malformed) is treated as absent."
+  [tools]
+  (cond
+    (map? tools) tools
+    (sequential? tools) {"byDefault" "ask" "allow" (vec tools)}
+    :else nil))
+
 (defn ^:private md->agent-config
   [{:keys [description mode model steps tools body inherit]}]
-  (cond-> {}
-    inherit (assoc :inherit (str inherit))
-    description (assoc :description description)
-    mode (assoc :mode (str mode))
-    model (assoc :defaultModel (str model))
-    steps (assoc :maxSteps (long steps))
-    (seq body) (assoc :systemPrompt body)
-    tools (assoc :toolCall
-                 (let [tools-map (if (map? tools) tools (into {} tools))]
-                   (cond-> {:approval {}}
-                     (get tools-map "byDefault")
-                     (assoc-in [:approval :byDefault] (get tools-map "byDefault"))
-
-                     (get tools-map "allow")
-                     (assoc-in [:approval :allow] (tools-list->approval-map (get tools-map "allow")))
-
-                     (get tools-map "deny")
-                     (assoc-in [:approval :deny] (tools-list->approval-map (get tools-map "deny")))
-
-                     (get tools-map "ask")
-                     (assoc-in [:approval :ask] (tools-list->approval-map (get tools-map "ask"))))))))
+  (let [tools-map (normalize-tools tools)]
+    (cond-> {}
+      inherit (assoc :inherit (str inherit))
+      description (assoc :description description)
+      mode (assoc :mode (str mode))
+      model (assoc :defaultModel (str model))
+      steps (assoc :maxSteps (long steps))
+      (seq body) (assoc :systemPrompt body)
+      tools-map (assoc :toolCall
+                       (cond-> {:approval {}}
+                         (get tools-map "byDefault")
+                         (assoc-in [:approval :byDefault] (get tools-map "byDefault"))
+
+                         (get tools-map "allow")
+                         (assoc-in [:approval :allow] (tools-list->approval-map (get tools-map "allow")))
+
+                         (get tools-map "deny")
+                         (assoc-in [:approval :deny] (tools-list->approval-map (get tools-map "deny")))
+
+                         (get tools-map "ask")
+                         (assoc-in [:approval :ask] (tools-list->approval-map (get tools-map "ask"))))))))
 
 (defn ^:private agent-name-from-frontmatter
   "Returns the agent id from YAML frontmatter `name:` when present and non-blank,

test/eca/features/agents_test.clj

@@ -128,7 +128,53 @@
           config (#'agents/md->agent-config parsed)]
       (is (= "A primary agent" (:description config)))
       (is (= "Do work." (:systemPrompt config)))
-      (is (nil? (:mode config))))))
+      (is (nil? (:mode config)))))
+
+  (testing "tools as a YAML list normalizes to byDefault=ask + allow map (Claude form)"
+    (let [md (str "---\n"
+                  "description: Reviewer\n"
+                  "tools:\n"
+                  "  - read\n"
+                  "  - search\n"
+                  "  - agent\n"
+                  "---\n\n"
+                  "Body.")
+          parsed (shared/parse-md md)
+          config (#'agents/md->agent-config parsed)]
+      (is (match? {:description "Reviewer"
+                   :systemPrompt "Body."
+                   :toolCall {:approval {:byDefault "ask"
+                                         :allow {"read" {}
+                                                 "search" {}
+                                                 "agent" {}}}}}
+                  config))))
+
+  (testing "tools as a malformed string is ignored without crashing the agent"
+    (let [config (#'agents/md->agent-config {:description "no tools" :tools "read"})]
+      (is (= "no tools" (:description config)))
+      (is (nil? (:toolCall config)))))
+
+  (testing "tools as a number is ignored without crashing the agent"
+    (let [config (#'agents/md->agent-config {:description "no tools" :tools 42})]
+      (is (= "no tools" (:description config)))
+      (is (nil? (:toolCall config))))))
+
+(deftest normalize-tools-test
+  (testing "map form passes through unchanged"
+    (is (= {"byDefault" "ask" "allow" ["read"]}
+           (#'agents/normalize-tools {"byDefault" "ask" "allow" ["read"]}))))
+  (testing "vector form is wrapped as byDefault=ask + allow"
+    (is (= {"byDefault" "ask" "allow" ["read" "search"]}
+           (#'agents/normalize-tools ["read" "search"]))))
+  (testing "list form (clojure list) is also accepted"
+    (is (= {"byDefault" "ask" "allow" ["read" "search"]}
+           (#'agents/normalize-tools '("read" "search")))))
+  (testing "nil returns nil"
+    (is (nil? (#'agents/normalize-tools nil))))
+  (testing "string returns nil (treated as malformed)"
+    (is (nil? (#'agents/normalize-tools "read"))))
+  (testing "number returns nil (treated as malformed)"
+    (is (nil? (#'agents/normalize-tools 42)))))
 
 (deftest md-agents-from-directory-test
   (let [tmp-dir (fs/create-temp-dir)
@@ -310,6 +356,33 @@
   (testing "handles filenames with multiple dots"
     (is (= "foo" (#'agents/agent-name-from-filename (fs/file "foo.bar.baz.md"))))))
 
+(deftest claude-tools-list-loads-agent-test
+  (let [tmp-dir (fs/create-temp-dir)
+        agents-dir (fs/file tmp-dir "agents")]
+    (try
+      (fs/create-dirs agents-dir)
+      ;; Lucas's exact reproducer: tools as a YAML list (Claude convention).
+      (spit (fs/file agents-dir "glp-engineer.agent.md")
+            (str "---\n"
+                 "name: GLP-Reviewer\n"
+                 "description: \"Review any design document with DRC-style structured feedback and rubric scoring\"\n"
+                 "tools:\n"
+                 "  - read\n"
+                 "  - search\n"
+                 "  - agent\n"
+                 "---\n\n"
+                 "You are a reviewer."))
+      (let [result (#'agents/agent-md-file->agent (fs/file agents-dir "glp-engineer.agent.md"))]
+        (testing "agent is loaded (not silently dropped by tools-list parse error)"
+          (is (some? result)))
+        (testing "agent id comes from YAML name"
+          (is (= "glp-reviewer" (first result))))
+        (testing "description is preserved"
+          (is (= "Review any design document with DRC-style structured feedback and rubric scoring"
+                 (get-in (second result) [:description])))))
+      (finally
+        (fs/delete-tree tmp-dir)))))
+
 (deftest agent-id-precedence-test
   (let [tmp-dir (fs/create-temp-dir)
         agents-dir (fs/file tmp-dir "agents")]

test/eca/features/plugins_test.clj

@@ -313,6 +313,54 @@
       (is (= [{:path "/a/commands/cmd.md"}] (:commands result)))
       (is (= [{:path "/b/rules/rule.mdc"}] (:rules result))))))
 
+(deftest plugin-agent-with-claude-tools-list-becomes-primary-test
+  (let [tmp-dir (fs/create-temp-dir)
+        source-dir (fs/file tmp-dir "repo")
+        plugin-dir (fs/file source-dir "plugins" "test" "design-review")
+        prev-plugin-components @config/plugin-components*
+        prev-init-config @config/initialization-config*]
+    (try
+      (fs/create-dirs (fs/file source-dir ".eca-plugin"))
+      (fs/create-dirs (fs/file plugin-dir "agents"))
+      (spit (fs/file source-dir ".eca-plugin" "marketplace.json")
+            (json/generate-string
+             {:plugins [{:name "design-review"
+                         :description "Design review plugin"
+                         :source "./plugins/test/design-review"}]}))
+      ;; Lucas's exact reproducer: Claude-style frontmatter with tools-as-list.
+      (spit (fs/file plugin-dir "agents" "glp-engineer.agent.md")
+            (str "---\n"
+                 "name: GLP-Reviewer\n"
+                 "description: \"Review any design document with DRC-style structured feedback and rubric scoring\"\n"
+                 "tools:\n"
+                 "  - read\n"
+                 "  - search\n"
+                 "  - agent\n"
+                 "---\n\n"
+                 "Role & Goal: review designs."))
+      (let [resolved (plugins/resolve-all!
+                      {"local" {:source (str source-dir)}
+                       "install" ["design-review"]})]
+        (testing "plugin discovery loads the Claude-style agent without dropping it"
+          (is (contains? (:agents resolved) "glp-reviewer")))
+
+        (reset! config/plugin-components* resolved)
+        (reset! config/initialization-config* {:pureConfig false})
+        (let [final-config (#'config/all* {:workspace-folders []})
+              primaries (set (config/primary-agent-names final-config))]
+          (testing "tools list is normalized to byDefault=ask + allow"
+            (is (match? {:approval {:byDefault "ask"
+                                    :allow {"read" {}
+                                            "search" {}
+                                            "agent" {}}}}
+                        (get-in final-config [:agent "glp-reviewer" :toolCall]))))
+          (testing "agent appears in primary-agent-names"
+            (is (contains? primaries "glp-reviewer")))))
+      (finally
+        (reset! config/plugin-components* prev-plugin-components)
+        (reset! config/initialization-config* prev-init-config)
+        (fs/delete-tree tmp-dir)))))
+
 (deftest plugin-agent-without-mode-becomes-primary-test
   (let [tmp-dir (fs/create-temp-dir)
         source-dir (fs/file tmp-dir "repo")