Granular shell/git tool approve and remember per command

Closes #153

Author: ericdallo

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Granular shell/git approve & remember by command + subcommand (e.g. `git checkout`) instead of whole tool; details carry breakdown, approval keys and remembered state. #153
+
 ## 0.146.2
 
 - Fix 400 on GitHub Copilot Claude adaptive-thinking models (e.g. Opus 4.8) when no variant is selected, by defaulting to adaptive thinking. #528

docs/config/tools.md

@@ -355,6 +355,12 @@ Also check the `plan` agent which is safer.
 
 __The `manualApproval` setting was deprecated and replaced by the `approval` one without breaking changes__
 
+### Granular approve & remember for shell commands
+
+When you approve a `eca__shell_command` or `eca__git` tool call choosing "approve and remember", ECA remembers the approved commands for the session instead of whitelisting the whole tool: the command string is parsed and each command in a chain (`&&`, `||`, `;`, `|`) produces a key — command + subcommand for multi-command tools (`git checkout`, `npm install`), the plain command otherwise (`rg`). A future shell call runs automatically only when all its commands were already remembered.
+
+ECA fails closed: commands it cannot safely reason about always ask again, like command/process substitution (`$(...)`, backticks), subshells, heredocs, output redirections to files (except `/dev/null`), and wrapper commands that execute arbitrary code (`sudo`, `bash -c`, `xargs`, `env`, ...).
+
 ### Trust mode by default
 
 Trust mode auto-accepts all tool calls in a chat (it never overrides `deny`). Editors expose a toggle for it, and you can make **new chats start trusted** for every editor via `chat.defaultTrust`:

docs/protocol.md

@@ -1179,7 +1179,7 @@ interface ChatToolCallRejectedContent {
 
 type ToolCallOrigin = 'mcp' | 'native' | 'server' | 'unknown';
 
-type ToolCallDetails = FileChangeDetails | JsonOutputsDetails | SubagentDetails | TaskDetails;
+type ToolCallDetails = FileChangeDetails | JsonOutputsDetails | SubagentDetails | TaskDetails | ShellCommandDetails;
 
 interface FileChangeDetails {
     type: 'fileChange';
@@ -1323,6 +1323,53 @@ interface TaskItem {
     blockedBy?: number[];
 }
 
+/**
+ * Breakdown of a shell command tool call.
+ * Present when the server could safely parse the command; clients can use it
+ * to show what an "approve & remember" would remember.
+ */
+interface ShellCommandDetails {
+    type: 'shellCommand';
+
+    /**
+     * The individual commands extracted from the shell invocation.
+     * Chained commands (&&, ||, ;, |) are split into separate entries.
+     */
+    commands: ShellCommandBreakdown[];
+
+    /**
+     * Whether the command runs in background as a job.
+     */
+    background?: boolean;
+}
+
+interface ShellCommandBreakdown {
+    /**
+     * The command being executed, e.g. "ls", "git".
+     */
+    command: string;
+
+    /**
+     * All arguments to the command, including flags.
+     * e.g. ["-la", "*.clj"] for "ls -la *.clj".
+     */
+    args: string[];
+
+    /**
+     * The key that "approve & remember" would remember for this command,
+     * e.g. "git checkout" or "rg". Absent when this command can never be
+     * auto-approved (wrapper commands like sudo/xargs, file output
+     * redirections, dynamic command words).
+     */
+    approvalKey?: string;
+
+    /**
+     * Whether approvalKey is already remembered for this session.
+     * Only present when approvalKey is present.
+     */
+    remembered?: boolean;
+}
+
 /**
  * Extra information about a chat
  */
@@ -1375,6 +1422,8 @@ interface ChatToolCallApproveParams {
 
     /**
      * The approach to save this tool call.
+     * For tools with granular approval (eca shell_command and git), 'session' remembers
+     * the specific approved commands (e.g. "git checkout") instead of the whole tool.
      */
     save?: 'session';
 

src/eca/db.clj

@@ -146,6 +146,10 @@
    :stopping false
    :models {}
    :mcp-clients {}
+   ;; Approved tool calls remembered for this session (not cached):
+   ;; {tool-name {:remember-to-approve? boolean
+   ;;             :remembered-command-keys #{string}}}
+   :tool-calls {}
 
    ;; cacheable, bump db `version` when changing any below
    :chats {}

src/eca/features/chat.clj

@@ -1788,8 +1788,14 @@
                                   {:reason {:code :user-choice-allow
                                             :text "Tool call allowed by user choice"}})
         (when (= "session" save)
-          (let [tool-call-name (get-in @db* [:chats chat-id :tool-calls tool-call-id :name])]
-            (swap! db* assoc-in [:tool-calls tool-call-name :remember-to-approve?] true)))))))
+          (let [{tool-call-name :name arguments :arguments} (get-in @db* [:chats chat-id :tool-calls tool-call-id])]
+            (if-let [{keys' :keys} (f.tools/tool-approval-keys tool-call-name arguments)]
+              ;; Granular remember (e.g. shell commands): remember only the
+              ;; derived keys instead of whitelisting the whole tool. #153
+              (when (seq keys')
+                (swap! db* update-in [:tool-calls tool-call-name :remembered-command-keys]
+                       (fnil into #{}) keys'))
+              (swap! db* assoc-in [:tool-calls tool-call-name :remember-to-approve?] true))))))))
 
 (defn tool-call-reject
   [{:keys [chat-id tool-call-id]} db* messenger config metrics]

src/eca/features/tools.clj

@@ -60,21 +60,30 @@
   ([all-tools tool args db config agent-name]
    (approval all-tools tool args db config agent-name nil))
   ([all-tools tool args db config agent-name {:keys [trust]}]
-   (let [{:keys [server name require-approval-fn]} tool
-         remember-to-approve? (get-in db [:tool-calls name :remember-to-approve?])
+   (let [{:keys [server name require-approval-fn approval-keys-fn]} tool
+         remembered? (if approval-keys-fn
+                       ;; Granular remember: every derived key (e.g. "git checkout")
+                       ;; must have been remembered, and the command must be fully
+                       ;; understood (:complete?), otherwise still ask.
+                       (let [{keys' :keys complete? :complete?} (approval-keys-fn args)
+                             remembered-keys (get-in db [:tool-calls name :remembered-command-keys] #{})]
+                         (boolean (and complete?
+                                       (seq keys')
+                                       (every? remembered-keys keys'))))
+                       (boolean (get-in db [:tool-calls name :remember-to-approve?])))
          native-tools (filter #(= :native (:origin %)) all-tools)
          {:keys [allow ask deny byDefault]}   (merge (get-in config [:toolCall :approval])
                                                      (get-in config [:agent agent-name :toolCall :approval]))
          result (cond
-                  remember-to-approve?
+                  (some #(approval-matches? % (:name server) name args native-tools) deny)
+                  :deny
+
+                  remembered?
                   :allow
 
                   (and require-approval-fn (require-approval-fn args {:db db}))
                   :ask
 
-                  (some #(approval-matches? % (:name server) name args native-tools) deny)
-                  :deny
-
                   (some #(approval-matches? % (:name server) name args native-tools) ask)
                   :ask
 
@@ -130,6 +139,27 @@
        x))
    m))
 
+(defn ^:private static-native-definitions
+  "Native tool definitions that don't depend on chat/db/config."
+  []
+  (merge {}
+         f.tools.filesystem/definitions
+         f.tools.shell/definitions
+         f.tools.git/definitions
+         f.tools.editor/definitions
+         f.tools.chat/definitions
+         f.tools.skill/definitions
+         f.tools.task/definitions
+         f.tools.background/definitions
+         f.tools.ask-user/definitions))
+
+(defn tool-approval-keys
+  "Returns {:keys #{...} :complete? bool} when the native tool `tool-name`
+   defines granular approval keys for these arguments, else nil."
+  [tool-name arguments]
+  (when-let [approval-keys-fn (get-in (static-native-definitions) [tool-name :approval-keys-fn])]
+    (approval-keys-fn arguments)))
+
 (defn ^:private native-definitions
   [chat-id agent-name db config]
   (into
@@ -142,16 +172,7 @@
                       :readFileMaxLines (get-in config [:toolCall :readFile :maxLines])
                       :fullModel        (get-in db [:chats chat-id :model])
                       :variant          (get-in db [:chats chat-id :variant])}))]))
-   (merge {}
-          f.tools.filesystem/definitions
-          f.tools.shell/definitions
-          f.tools.git/definitions
-          f.tools.editor/definitions
-          f.tools.chat/definitions
-          f.tools.skill/definitions
-          f.tools.task/definitions
-          f.tools.background/definitions
-          f.tools.ask-user/definitions
+   (merge (static-native-definitions)
           (f.tools.agent/definitions config db)
           (f.tools.custom/definitions config)
           (f.tools.fetch-rule/definitions config db chat-id agent-name))))

src/eca/features/tools/git.clj

@@ -4,6 +4,7 @@
    [clojure.string :as string]
    [eca.cache :as cache]
    [eca.features.tools.shell :as shell]
+   [eca.features.tools.shell-parser :as shell-parser]
    [eca.features.tools.util :as tools.util]
    [eca.logger :as logger]
    [eca.shared :as shared]))
@@ -14,6 +15,10 @@
 
 (def ^:private default-timeout 120000)
 
+(defmethod tools.util/tool-call-details-before-invocation :git
+  [_name arguments _server {:keys [db]}]
+  (shell/shell-command-details "git" (get arguments "command") db))
+
 (defn ^:private git-command [arguments {:keys [db tool-call-id call-state-fn state-transition-fn]}]
   (let [command (get arguments "command")]
     (or (tools.util/invalid-arguments
@@ -102,6 +107,7 @@
                                          :description "Concise 2-3 word description of what is being done (e.g. \"staged changes\", \"all test files\")."}}
                  :required ["command" "operation"]}
     :handler #'git-command
+    :approval-keys-fn (fn [arguments] (shell-parser/approval-keys (get arguments "command")))
     :summary-fn #'git-command-summary}})
 
 (defmethod tools.util/tool-call-destroy-resource! :eca__git [name resource-kwd resource]

src/eca/features/tools/shell.clj

@@ -5,6 +5,7 @@
    [clojure.string :as string]
    [eca.config :as config]
    [eca.features.background-tasks :as bg]
+   [eca.features.tools.shell-parser :as shell-parser]
    [eca.features.tools.util :as tools.util]
    [eca.logger :as logger]
    [eca.messenger :as messenger]
@@ -17,10 +18,29 @@
 (def ^:private default-timeout 60000)
 (def ^:private max-timeout (* 60000 10))
 
+(defn shell-command-details
+  "Builds the shellCommand tool call details for a command string, marking
+   each command with whether its approval key is already remembered for
+   `tool-name`. Returns nil when the command cannot be parsed."
+  [tool-name command db]
+  (when-let [parsed (shell-parser/parse command)]
+    (let [remembered-keys (get-in db [:tool-calls tool-name :remembered-command-keys] #{})]
+      (-> parsed
+          (update :commands (fn [commands]
+                              (mapv (fn [{:keys [approvalKey] :as cmd}]
+                                      (cond-> cmd
+                                        approvalKey (assoc :remembered (contains? remembered-keys approvalKey))))
+                                    commands)))
+          (assoc :type :shellCommand)))))
+
 (defmethod tools.util/tool-call-details-before-invocation :shell_command
-  [_name arguments _server _ctx]
-  (when (get arguments "background")
-    {:background true}))
+  [_name arguments _server {:keys [db]}]
+  (let [background? (boolean (get arguments "background"))]
+    (if-let [details (shell-command-details "shell_command" (get arguments "command") db)]
+      (cond-> details
+        background? (assoc :background true))
+      (when background?
+        {:background true}))))
 
 (defn start-shell-process!
   "Start a shell process, returning the process object for deref/management.
@@ -262,6 +282,7 @@
                  :required ["command"]}
     :handler #'shell-command
     :require-approval-fn (tools.util/require-approval-when-outside-workspace ["working_directory"])
+    :approval-keys-fn (fn [arguments] (shell-parser/approval-keys (get arguments "command")))
     :summary-fn #'shell-command-summary}})
 
 (defmethod tools.util/tool-call-destroy-resource! :eca__shell_command [name resource-kwd resource]