elelem-tools 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0074cea1a49859fbbcd424c4a30cb791b22e49b3a023484386644f50d8590925
-  data.tar.gz: f4fd8cacf3d4e8509aac90aeadb0515757ce429a1390a9138f344919983f3c0e
+  metadata.gz: 4b0f5e3a9dd3ff1d691507d3eaffb33f083d57eb607ce2be6af72862820d56ad
+  data.tar.gz: 918f507fd626ed799f2469412ed990061ba51739363b3296456151691418a0de
 SHA512:
-  metadata.gz: 33be226b5096e099d4c1e7c2e32af8f3ae1c0d581ee82c7250585b439a60972da0b396a26ec258ad6130140ed6b66138672799b48a26b575ffa17f1934fc53bd
-  data.tar.gz: 62e813b53649bce2a34abed94160dda5ba0d1b1e2876977fcce821c4fd5241cda569f2954bdc3b5f42193316c8ef8a2847faf3e8414bfdcbeec1427ab5e11508
+  metadata.gz: 3f1fcbc49703bb6fbf87d96593fe5b7e5be04833c9e8af3f4cc27f9a9fc395fbb5b912b57a00eef9d82b9e5bdcf425d1f58424f9d26d384084eaa7ca9f7c7dc5
+  data.tar.gz: fc5bff90cd435be07a865803f5f269a50b2b98ba4950934031ce19d9131a1ed7e3ee30a4908784221f87e956062a9bf590ef7b4e3afa25f52fe80a24627d0d0c

data/.github/workflows/release.yml

@@ -0,0 +1,61 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          persist-credentials: false
+      - uses: ruby/setup-ruby@3ff19f5e2baf30647122352b96108b1fbe250c64 # v1.299.0
+        with:
+          ruby-version: "4.0"
+          bundler-cache: true
+      - run: bin/test
+      - run: bin/lint
+
+  release-please:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+    steps:
+      - id: release
+        uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  publish:
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          persist-credentials: false
+      - uses: ruby/setup-ruby@3ff19f5e2baf30647122352b96108b1fbe250c64 # v1.299.0
+        with:
+          ruby-version: "4.0"
+          bundler-cache: true
+      - uses: rubygems/release-gem@7f9650160c1a4e7989fdc9855807bdbd421d8b6b # v1.4.1

data/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.3.0"
+}

data/.rubocop.yml

@@ -0,0 +1,62 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 4.0
+  SuggestExtensions: false
+  Exclude:
+    - "pkg/**/*"
+    - "bin/**/*"
+    - "vendor/**/*"
+    - "fixtures/**/*"
+
+Metrics:
+  Enabled: false
+
+Naming/PredicateMethod:
+  AllowedMethods:
+    - call
+    - run
+    - summarize
+    - prompt
+
+Naming/MethodParameterName:
+  AllowedNames:
+    - me
+    - id
+    - as
+    - io
+
+Style/GlobalVars:
+  Exclude:
+    - "spec/**/*"
+
+Lint/EmptyBlock:
+  Exclude:
+    - "spec/**/*"
+
+Lint/UselessDefaultValueArgument:
+  Enabled: false
+
+Lint/RedundantRequireStatement:
+  Enabled: false
+
+Lint/UnusedBlockArgument:
+  IgnoreEmptyBlocks: true
+  AllowUnusedKeywordArguments: true
+
+Style/Documentation:
+  Enabled: false
+
+Style/FormatStringToken:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## [0.3.0](https://github.com/elelem-sh/tools/compare/v0.2.0...v0.3.0) (2026-11-15)
+
+
+### Bug Fixes
+
+* a built command skips its prompt only after a person approved the tool that built it (elelem-sh/elelem.sh[#3](https://github.com/elelem-sh/tools/issues/3)) ([0f47899](https://github.com/elelem-sh/tools/commit/0f4789942fe36b780beab507f2d406286852ca1e))
+* a command a tool builds itself does not ask again after the tool was approved (elelem-sh/elelem.sh[#3](https://github.com/elelem-sh/tools/issues/3)) ([097b5b9](https://github.com/elelem-sh/tools/commit/097b5b98411857bd2b94ea439a41ce175ac889cd))
+* a failed verify check is an error, so the model sees ok: false ([acddd22](https://github.com/elelem-sh/tools/commit/acddd22fe00653bf5f09110dc4d84434f17e8f37))
+* a failing git command is an error, and grep with no matches is not (elelem-sh/elelem.sh[#20](https://github.com/elelem-sh/tools/issues/20)) ([fedc829](https://github.com/elelem-sh/tools/commit/fedc8295646dfed601cc2e9120434738b9542ac1))
+* ask before running a tool whose permission policy is misspelled ([4adf5f6](https://github.com/elelem-sh/tools/commit/4adf5f6d22230dca701cdd72b8ee45efc346655a))
+* edit counts overlapping matches and edits files that are not UTF-8 (elelem-sh/elelem.sh[#21](https://github.com/elelem-sh/tools/issues/21)) ([c3c2f73](https://github.com/elelem-sh/tools/commit/c3c2f737358d9df67f4fd75a4c952c70ab960b60))
+* edit fails when old is missing or repeated, and takes new literally (elelem-sh/elelem.sh[#21](https://github.com/elelem-sh/tools/issues/21)) ([c2fd4eb](https://github.com/elelem-sh/tools/commit/c2fd4eb9f78ce1c13717c9e04ac7d08e5256bb2a))
+* end of input at a permission prompt refuses (elelem-sh/elelem.sh[#2](https://github.com/elelem-sh/tools/issues/2)) ([dd75f4b](https://github.com/elelem-sh/tools/commit/dd75f4b2d5749b6972f2cfc7e24718654c4f809d))
+* git always asks for its exact command line, since repository config can make any git command run a program ([d50005a](https://github.com/elelem-sh/tools/commit/d50005a9be0d56f1561887f7abe55ee4c3be23bb))
+* git asks once, at execute, for its exact command line ([4dc6bd9](https://github.com/elelem-sh/tools/commit/4dc6bd975c7fa3441af6baee50d72e8662a176eb))
+* grep and glob also fall back when rg or fd cannot run (elelem-sh/elelem.sh[#20](https://github.com/elelem-sh/tools/issues/20)) ([8a5a5d7](https://github.com/elelem-sh/tools/commit/8a5a5d7924dcfebd310efbb8cbcb841e02de48c3))
+* grep and glob fall back only when rg or fd is not installed (elelem-sh/elelem.sh[#20](https://github.com/elelem-sh/tools/issues/20)) ([43180e3](https://github.com/elelem-sh/tools/commit/43180e30477eeeec5388a953376c2b53f14b865b))
+* grep, glob, list and git never take a model-chosen value as an option that runs a program ([0aca202](https://github.com/elelem-sh/tools/commit/0aca2029521e1793c0e631dfa4df24c7eafebe46))
+* only Enter, y or yes allow at a permission prompt (elelem-sh/elelem.sh[#2](https://github.com/elelem-sh/tools/issues/2)) ([d853f3b](https://github.com/elelem-sh/tools/commit/d853f3bf714142ce1f1303744815baa1ab44af97))
+* only read-only git commands share the git approval; any other git command asks for its exact command line ([bbc1a0f](https://github.com/elelem-sh/tools/commit/bbc1a0ff5bc66b9c95b145653942f768df90a1a1))
+* permission prompts escape characters that could redraw them (elelem-sh/elelem.sh[#2](https://github.com/elelem-sh/tools/issues/2)) ([fa46378](https://github.com/elelem-sh/tools/commit/fa463789635d446fced2b84dc6358d51c9389ed5))
+* permission prompts show the command, and verify is allowed by default (elelem-sh/elelem.sh[#3](https://github.com/elelem-sh/tools/issues/3)) ([97c3437](https://github.com/elelem-sh/tools/commit/97c3437b6ec494c9b27d61e6ab11ee2632d5d3ed))
+* require elelem ~> 0.12, the floor builtins/skills actually need ([48b5818](https://github.com/elelem-sh/tools/commit/48b5818282b37877d72c55aeb79ec20ded25c1b4))
+* require elelem 0.13.1, verify each written file, and grep with no matches is not an error ([4dfab39](https://github.com/elelem-sh/tools/commit/4dfab39bb738f3e41e3d2cb28093a22204409911))
+* verify escapes the path before passing it to the shell ([ed52cf8](https://github.com/elelem-sh/tools/commit/ed52cf8f4682225fff4d0a1380f6c44fb59dd614))

data/lib/elelem/tools/compact.rb

@@ -6,7 +6,7 @@ Elelem.configure do |config|
       response = agent.turn("Summarize: accomplishments, state, next steps. Brief.")
       agent.conversation.clear!
       agent.conversation.add(role: "user", content: "Context: #{response}")
-      agent.output.say "  → compacted"
+      agent.output.say "  -> compacted"
     end
   end
 end

data/lib/elelem/tools/edit.rb

@@ -3,15 +3,19 @@
 Elelem.configure do |config|
   config.setup(:edit) do |agent|
     agent.toolbox.add("edit",
-      description: "Replace first occurrence of text in file",
-      params: { path: { type: "string" }, old: { type: "string" }, new: { type: "string" } },
-      required: ["path", "old", "new"]
-    ) do |args|
-      path = Pathname.new(args["path"]).expand_path
-      content = path.read
+                      description: "Replace the one occurrence of old with new in a file",
+                      params: { path: { type: "string" }, old: { type: "string" }, new: { type: "string" } },
+                      required: %w[path old new]) do |args|
+      content = Pathname.new(args["path"]).expand_path.read
+      first = content.index(args["old"]) unless args["old"].empty?
+      next { error: "old not found" } unless first
+      # index also finds overlapping matches, and copes with invalid bytes.
+      next { error: "old matches more than once; include more context" } if content.index(args["old"], first + 1)
+
+      # The block form takes new literally, so \0 and \1 are not expanded.
       agent.toolbox
-        .run("write", { "path" => args["path"], "content" => content.sub(args["old"], args["new"]) })
-        .merge(replaced: args["old"], with: args["new"])
+           .run("write", { "path" => args["path"], "content" => content.sub(args["old"]) { args["new"] } })
+           .merge(replaced: args["old"], with: args["new"])
     end
   end
 end

data/lib/elelem/tools/eval.rb

@@ -12,11 +12,10 @@ Elelem.configure do |config|
     DESC
 
     agent.toolbox.add("eval",
-      description: description,
-      params: { ruby: { type: "string" } },
-      required: ["ruby"]
-    ) do |args|
-      { result: binding.eval(args["ruby"]) }
+                      description: description,
+                      params: { ruby: { type: "string" } },
+                      required: ["ruby"]) do |args|
+      { result: binding.eval(args["ruby"]) } # rubocop:disable Security/Eval
     end
   end
 end

data/lib/elelem/tools/exec.rb

@@ -2,9 +2,49 @@
 
 module Elelem
   module Tools
+    # glob, grep and list run their command through execute. When a person was
+    # just asked about the outer call, which shows the same arguments, the
+    # command it builds does not ask again. When the outer call was allowed
+    # without asking, the command still asks. A deny on execute always applies.
+    # git is not one of them: repository config can make any git command run a
+    # program, so git is allowed by default and execute asks for its exact
+    # command line, once.
     def self.exec(toolbox, *args)
       command = args.flatten.map { |a| Shellwords.escape(a.to_s) }.join(" ")
-      toolbox.run("execute", { "command" => command })
+      nested { toolbox.run("execute", { "command" => command }) }
+    end
+
+    def self.nested
+      outer = Thread.current[:elelem_tools_nested]
+      Thread.current[:elelem_tools_nested] = true
+      yield
+    ensure
+      Thread.current[:elelem_tools_nested] = outer
+    end
+
+    def self.nested?
+      Thread.current[:elelem_tools_nested] == true
+    end
+
+    def self.approved?
+      Thread.current[:elelem_tools_approved] == true
+    end
+
+    def self.approved=(value)
+      Thread.current[:elelem_tools_approved] = value
+    end
+
+    # rg and grep exit 1 when nothing matches. That is an answer, not a failure.
+    def self.no_matches(result)
+      return result unless result[:exit_status] == 1 && result[:content].to_s.strip.empty?
+
+      result.to_h.except(:ok, :error).merge(content: "no matches")
+    end
+
+    # bash exits 127 when the command is not installed, 126 when it cannot run
+    # it. rg exits 1 when nothing matches, which is not a reason to fall back.
+    def self.missing?(result)
+      [126, 127].include?(result[:exit_status])
     end
   end
 end

data/lib/elelem/tools/fork.rb

@@ -2,8 +2,8 @@
 
 module Elelem
   module Tools
-    def self.fork(agent, system_prompt:)
-      Elelem::Agent.new(agent.provider, toolbox: agent.toolbox, output: agent.output, input: agent.input, system_prompt: system_prompt)
+    def self.fork(agent, template:)
+      Elelem::Agent.new(agent.provider, toolbox: agent.toolbox, output: agent.output, template: template)
     end
   end
 end

data/lib/elelem/tools/git.rb

@@ -3,11 +3,13 @@
 Elelem.configure do |config|
   config.setup(:git) do |agent|
     agent.toolbox.add("git",
-      description: "Run git command",
-      params: { command: { type: "string" }, args: { type: "array", items: { type: "string" } } },
-      required: ["command"]
-    ) do |args|
-      Elelem::Tools.exec(agent.toolbox, "git", args["command"], *(args["args"] || []))
+                      description: "Run git command",
+                      params: { command: { type: "string" }, args: { type: "array", items: { type: "string" } } },
+                      required: ["command"]) do |args|
+      # Not Tools.exec: config (aliases, hooks, filters, textconv, signing) can
+      # make any git command run a program, so execute asks for the exact line.
+      line = ["git", args["command"], *(args["args"] || [])].map { |a| Shellwords.escape(a.to_s) }.join(" ")
+      agent.toolbox.run("execute", { "command" => line })
     end
 
     agent.toolbox.after("git") do |_, result|

data/lib/elelem/tools/glob.rb

@@ -3,13 +3,16 @@
 Elelem.configure do |config|
   config.setup(:glob) do |agent|
     agent.toolbox.add("glob",
-      description: "Find files matching pattern",
-      params: { pattern: { type: "string" }, path: { type: "string" } },
-      required: ["pattern"]
-    ) do |args|
+                      description: "Find files matching pattern",
+                      params: { pattern: { type: "string" }, path: { type: "string" } },
+                      required: ["pattern"]) do |args|
       path = args["path"].to_s.empty? ? "." : args["path"]
-      result = Elelem::Tools.exec(agent.toolbox, "fd", "--glob", args["pattern"], path)
-      result[:ok] ? result : Elelem::Tools.exec(agent.toolbox, "find", path, "-name", args["pattern"])
+      # find has no --, so a path like -delete becomes ./-delete.
+      path = "./#{path}" if path.start_with?("-")
+      result = Elelem::Tools.exec(agent.toolbox, "fd", "--glob", "--", args["pattern"], path)
+      next result unless Elelem::Tools.missing?(result)
+
+      Elelem::Tools.exec(agent.toolbox, "find", path, "-name", args["pattern"])
     end
   end
 end

data/lib/elelem/tools/grep.rb

@@ -3,22 +3,25 @@
 Elelem.configure do |config|
   config.setup(:grep) do |agent|
     agent.toolbox.add("grep",
-      description: "Search file contents",
-      params: { pattern: { type: "string" }, path: { type: "string" }, glob: { type: "string" } },
-      required: ["pattern"]
-    ) do |args|
+                      description: "Search file contents",
+                      params: { pattern: { type: "string" }, path: { type: "string" }, glob: { type: "string" } },
+                      required: ["pattern"]) do |args|
       path = args["path"].to_s.empty? ? "." : args["path"]
       glob = args["glob"]
 
-      rg_args = ["rg", "-n", args["pattern"], path]
+      # -e and -- keep a pattern or path starting with - from being read as an
+      # option, such as rg --pre=CMD, which runs a program on every file.
+      rg_args = ["rg", "-n"]
       rg_args += ["-g", glob] if glob
+      rg_args += ["-e", args["pattern"], "--", path]
       result = Elelem::Tools.exec(agent.toolbox, *rg_args)
-      next result if result[:ok]
-
-      grep_args = ["grep", "-rn"]
-      grep_args += ["--include", glob] if glob
-      grep_args += [args["pattern"], path]
-      Elelem::Tools.exec(agent.toolbox, *grep_args)
+      if Elelem::Tools.missing?(result)
+        grep_args = ["grep", "-rn"]
+        grep_args += ["--include", glob] if glob
+        grep_args += ["-e", args["pattern"], "--", path]
+        result = Elelem::Tools.exec(agent.toolbox, *grep_args)
+      end
+      Elelem::Tools.no_matches(result)
     end
   end
 end

data/lib/elelem/tools/init.rb

@@ -3,7 +3,7 @@
 Elelem.configure do |config|
   config.setup(:init) do |agent|
     agent.commands.register("init", description: "Generate AGENTS.md") do
-      system_prompt = <<~PROMPT
+      template = <<~PROMPT
         AGENTS.md generator. Analyze codebase and write AGENTS.md to project root.
 
         # AGENTS.md Spec (https://agents.md/)
@@ -25,7 +25,7 @@ Elelem.configure do |config|
         Keep it minimal. No fluff.
       PROMPT
 
-      Elelem::Tools.fork(agent, system_prompt: system_prompt).turn("Generate AGENTS.md for this project")
+      Elelem::Tools.fork(agent, template: template).turn("Generate AGENTS.md for this project")
     end
   end
 end

data/lib/elelem/tools/interview.rb

@@ -3,12 +3,11 @@
 Elelem.configure do |config|
   config.setup(:interview) do |agent|
     agent.toolbox.add("interview",
-      description: "Ask the user a question and wait for their response",
-      params: {
-        question: { type: "string", description: "The question to ask the user" },
-      },
-      required: ["question"]
-    ) do |args|
+                      description: "Ask the user a question and wait for their response",
+                      params: {
+                        question: { type: "string", description: "The question to ask the user" }
+                      },
+                      required: ["question"]) do |args|
       agent.output.say(args["question"], as: :markdown)
       { answer: agent.input.ask("> ") }
     end

data/lib/elelem/tools/list.rb

@@ -3,14 +3,13 @@
 Elelem.configure do |config|
   config.setup(:list) do |agent|
     agent.toolbox.add("list",
-      description: "List directory contents",
-      params: { path: { type: "string" }, recursive: { type: "boolean" } },
-      required: [],
-      aliases: ["ls"]
-    ) do |args|
+                      description: "List directory contents",
+                      params: { path: { type: "string" }, recursive: { type: "boolean" } },
+                      required: [],
+                      aliases: ["ls"]) do |args|
       path = args["path"] && !args["path"].empty? ? args["path"] : "."
       flags = args["recursive"] ? "-laR" : "-la"
-      Elelem::Tools.exec(agent.toolbox, "ls", flags, path)
+      Elelem::Tools.exec(agent.toolbox, "ls", flags, "--", path)
     end
   end
 end

data/lib/elelem/tools/permissions.json

@@ -1,5 +1,7 @@
 {
   "execute": "ask",
+  "git": "allow",
   "read": "allow",
+  "verify": "allow",
   "write": "allow"
 }

data/lib/elelem/tools/permissions.rb

@@ -9,25 +9,39 @@ module Elelem
         ".agents/permissions.json"
       ].freeze
 
+      # Enter, y or yes. Anything else refuses: no, a typo, or end of input (Ctrl+D, nil).
+      YES = ["", "y", "yes"].freeze
+
       def initialize(rules: default_rules)
         @rules = rules
       end
 
       def check(tool_name, args, input:)
         policy = @rules[tool_name.to_sym] || :ask
-        case policy
-        when :allow then true
-        when :deny then raise "Permission denied: #{tool_name}"
-        when :ask then prompt(tool_name, args, input)
-        end
+        raise "Permission denied: #{tool_name}" if policy == :deny
+        return nested(tool_name, args, input, policy) if Tools.nested?
+
+        # Remember whether a person just saw and approved this call. Only then
+        # may the command it builds skip its own prompt.
+        Tools.approved = false
+        return true if policy == :allow
+
+        prompt(tool_name, args, input).tap { Tools.approved = input.interactive? }
       end
 
       private
 
+      def nested(tool_name, args, input, policy)
+        policy == :allow || Tools.approved? || prompt(tool_name, args, input)
+      end
+
       def load_config(path)
         return {} unless File.exist?(path)
 
-        JSON.parse(File.read(path)).transform_keys(&:to_sym).transform_values(&:to_sym)
+        data = JSON.parse(File.read(path))
+        return {} unless data.is_a?(Hash)
+
+        data.transform_keys(&:to_sym).transform_values { |v| v.to_s.to_sym }
       rescue JSON::ParserError
         {}
       end
@@ -35,12 +49,22 @@ module Elelem
       def prompt(tool_name, args, input)
         return true unless input.interactive?
 
-        answer = input.ask("  Allow? [Y/n] > ")&.downcase
-        raise "User denied permission: #{tool_name}" if answer == "n"
+        answer = input.ask("  Allow #{tool_name}#{subject(tool_name, args)}? [Y/n] > ")
+        raise "User denied permission: #{tool_name}" unless YES.include?(answer&.strip&.downcase)
 
         true
       end
 
+      # The whole command, never cut, so nothing hidden gets approved.
+      def subject(tool_name, args)
+        return "" if args.nil? || args.empty?
+
+        command = args["command"] if tool_name.to_s == "execute"
+        text = command ? command.to_s : JSON.generate(args)
+        # Control and format characters (\r, ESC, bidi overrides) could redraw the prompt.
+        " `#{text.match?(/[\p{Cc}\p{Cf}]/) ? text.dump : text}`"
+      end
+
       def default_rules
         LOAD_PATHS.reduce({}) do |rules, path|
           rules.merge(load_config(File.expand_path(path)))

data/lib/elelem/tools/shell.rb

@@ -2,7 +2,7 @@
 
 Elelem.configure do |config|
   config.setup(:shell) do |agent|
-    strip_ansi = ->(text) do
+    strip_ansi = lambda do |text|
       text
         .gsub(/^Script started.*?\n/, "")
         .gsub(/\nScript done.*$/, "")
@@ -11,7 +11,7 @@ Elelem.configure do |config|
         .gsub(/\e[PX^_].*?\e\\/, "")
         .gsub(/\e./, "")
         .gsub(/[\b]/, "")
-        .gsub(/\r/, "")
+        .gsub("\r", "")
     end
 
     agent.commands.register("shell", description: "Start interactive shell") do

data/lib/elelem/tools/task.rb

@@ -3,11 +3,10 @@
 Elelem.configure do |config|
   config.setup(:task) do |agent|
     agent.toolbox.add("task",
-      description: "Delegate subtask to focused agent (complex searches, multi-file analysis)",
-      params: { prompt: { type: "string" } },
-      required: ["prompt"]
-    ) do |args|
-      sub = Elelem::Tools.fork(agent, system_prompt: "Research agent. Search, analyze, report. Be concise.")
+                      description: "Delegate subtask to focused agent (complex searches, multi-file analysis)",
+                      params: { prompt: { type: "string" } },
+                      required: ["prompt"]) do |args|
+      sub = Elelem::Tools.fork(agent, template: "Research agent. Search, analyze, report. Be concise.")
       sub.turn(args["prompt"])
       { result: sub.conversation.last[:content] }
     end

data/lib/elelem/tools/verify.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "shellwords"
+
 class Verifiers
   SYNTAX = {
     ".rb" => "ruby -c %{path}",
@@ -8,7 +10,7 @@ class Verifiers
     ".go" => "go vet %{path}",
     ".rs" => "cargo check --quiet",
     ".ts" => "npx tsc --noEmit %{path}",
-    ".js" => "node --check %{path}",
+    ".js" => "node --check %{path}"
   }.freeze
 
   def self.for(path)
@@ -16,7 +18,7 @@ class Verifiers
 
     cmds = []
     ext = File.extname(path)
-    cmds << (SYNTAX[ext] % { path: path }) if SYNTAX[ext]
+    cmds << format(SYNTAX[ext], path: Shellwords.escape(path)) if SYNTAX[ext]
     cmds << test_runner
     cmds.compact
   end
@@ -29,19 +31,21 @@ end
 Elelem.configure do |config|
   config.setup(:verify) do |agent|
     agent.toolbox.add("verify",
-      description: "Verify file syntax and run tests",
-      params: { path: { type: "string" } },
-      required: ["path"]
-    ) do |args|
+                      description: "Verify file syntax and run tests",
+                      params: { path: { type: "string" } },
+                      required: ["path"]) do |args|
       path = args["path"]
-      Verifiers.for(path).inject({ verified: [] }) do |memo, cmd|
+      Verifiers.for(path).each_with_object({ verified: [] }) do |cmd, memo|
         agent.output.doing("execute", { "command" => cmd })
         v = agent.toolbox.run("execute", { "command" => cmd })
-        break v.merge(path: path, command: cmd) if v[:exit_status] != 0
+        break v.to_h.merge(path: path, command: cmd) unless v.ok?
 
         memo[:verified] << cmd
-        memo
       end
     end
+
+    agent.toolbox.after("write") do |_, result|
+      result[:verify] = agent.toolbox.run("verify", { "path" => result[:path] }).to_h unless result[:error]
+    end
   end
 end

data/lib/elelem/tools/version.rb

@@ -2,6 +2,6 @@
 
 module Elelem
   module Tools
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/release-please-config.json

@@ -0,0 +1,13 @@
+{
+  "bootstrap-sha": "b15526735ac2f36abe2ac102d87a484ff3d3916b",
+  "packages": {
+    ".": {
+      "release-type": "ruby",
+      "package-name": "elelem-tools",
+      "version-file": "lib/elelem/tools/version.rb",
+      "bump-minor-pre-major": true,
+      "include-component-in-tag": false,
+      "release-as": "0.3.0"
+    }
+  }
+}

data/spec/elelem/tools/arguments_spec.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# A pattern or path the model chooses must never become an option that runs
+# a program or deletes files.
+RSpec.describe "tool arguments that look like options" do
+  around { |example| Dir.mktmpdir { |dir| Dir.chdir(dir) { example.run } } }
+
+  before do
+    File.write("notes.txt", "hello\n")
+    File.write("x.sh", "#!/bin/sh\ntouch pwned\n")
+    File.chmod(0o755, "x.sh")
+  end
+
+  it "grep searches for a pattern like --pre=CMD instead of running CMD" do
+    run_tool("grep", { "pattern" => "--pre=./x.sh" })
+
+    expect(File).not_to exist("pwned")
+  end
+
+  it "grep finds a pattern that starts with -" do
+    File.write("flags.txt", "-v\n")
+
+    expect(run_tool("grep", { "pattern" => "-v" })[:content]).to include("flags.txt")
+  end
+
+  it "glob does not take a path like -delete as an action" do
+    run_tool("glob", { "pattern" => "zzz", "path" => "-delete" })
+
+    expect(File).to exist("notes.txt")
+  end
+
+  it "list takes a path like -R as a name" do
+    expect(run_tool("list", { "path" => "-R" })).not_to be_ok
+  end
+
+  describe "git" do
+    def executes_for(call)
+      seen = []
+      session.toolbox.before("execute") do |a|
+        seen << [a["command"], Elelem::Tools.nested?]
+        raise "stopped"
+      end
+      run_tool("git", call)
+      seen
+    end
+
+    it "asks for the exact command line of a read-only command, since config can make it run programs" do
+      expect(executes_for({ "command" => "status", "args" => ["--short"] })).to eq([["git status --short", false]])
+    end
+
+    it "asks for the exact command line of any other command" do
+      expect(executes_for({ "command" => "rebase", "args" => ["-xtouch pwned", "HEAD~1"] }))
+        .to eq([["git rebase -xtouch\\ pwned HEAD\\~1", false]])
+    end
+  end
+
+  it "git still runs ordinary commands" do
+    system("git", "init", "-q", ".")
+
+    expect(run_tool("git", { "command" => "status", "args" => ["--short"] })).to be_ok
+  end
+end

data/spec/elelem/tools/edit_spec.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+RSpec.describe "the edit tool" do
+  around { |example| Dir.mktmpdir { |dir| Dir.chdir(dir) { example.run } } }
+
+  before { File.write("a.txt", "one two two") }
+
+  it "replaces the one occurrence" do
+    expect(run_tool("edit", { "path" => "a.txt", "old" => "one", "new" => "1" })).to be_ok
+    expect(File.read("a.txt")).to eq("1 two two")
+  end
+
+  it "fails when old is missing" do
+    expect(run_tool("edit", { "path" => "a.txt", "old" => "three", "new" => "3" })[:error]).to eq("old not found")
+    expect(File.read("a.txt")).to eq("one two two")
+  end
+
+  it "fails when old matches more than once" do
+    expect(run_tool("edit", { "path" => "a.txt", "old" => "two", "new" => "2" })[:error]).to match(/more than once/)
+  end
+
+  it "counts overlapping matches" do
+    File.write("a.txt", "aaa")
+
+    expect(run_tool("edit", { "path" => "a.txt", "old" => "aa", "new" => "b" })[:error]).to match(/more than once/)
+  end
+
+  it "edits a file with bytes that are not UTF-8" do
+    File.binwrite("a.txt", "caf\xE9 one")
+    run_tool("edit", { "path" => "a.txt", "old" => "one", "new" => "1" })
+
+    expect(File.binread("a.txt")).to eq("caf\xE9 1".b)
+  end
+
+  it "takes new literally" do
+    run_tool("edit", { "path" => "a.txt", "old" => "one", "new" => "\\0 \\1" })
+
+    expect(File.read("a.txt")).to eq("\\0 \\1 two two")
+  end
+end

data/spec/elelem/tools/fallback_spec.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+RSpec.describe "the grep and glob fallbacks" do
+  # A PATH with bash and the fallbacks, but no rg or fd.
+  around do |example|
+    original = ENV.fetch("PATH")
+    Dir.mktmpdir do |dir|
+      bin = File.join(dir, "bin")
+      Dir.mkdir(bin)
+      %w[bash grep find].each do |cmd|
+        found = ENV.fetch("PATH").split(":").map { |d| File.join(d, cmd) }.find { |f| File.executable?(f) }
+        File.symlink(found, File.join(bin, cmd))
+      end
+      File.write(File.join(dir, "notes.txt"), "needle\n")
+      ENV["PATH"] = bin
+      @bin = bin
+      Dir.chdir(dir) { example.run }
+    ensure
+      ENV["PATH"] = original
+    end
+  end
+
+  it "falls back when rg is there but cannot run" do
+    File.binwrite(File.join(@bin, "rg"), "\x7FELF\x00\x00")
+    File.chmod(0o755, File.join(@bin, "rg"))
+    result = run_tool("grep", { "pattern" => "needle" })
+
+    expect(result[:content]).to include("notes.txt")
+  end
+
+  it "does not fall back when rg runs and finds nothing" do
+    File.write(File.join(@bin, "rg"), "#!/bin/sh\nexit 1\n")
+    File.chmod(0o755, File.join(@bin, "rg"))
+    result = run_tool("grep", { "pattern" => "needle" })
+
+    expect([result[:exit_status], result[:content]]).to eq([1, "no matches"])
+    expect(result).to be_ok
+  end
+
+  it "greps with grep when rg is not installed" do
+    result = run_tool("grep", { "pattern" => "needle" })
+
+    expect(result[:exit_status]).to eq(0)
+    expect(result[:content]).to include("notes.txt")
+  end
+
+  it "globs with find when fd is not installed" do
+    result = run_tool("glob", { "pattern" => "*.txt" })
+
+    expect(result[:exit_status]).to eq(0)
+    expect(result[:content]).to include("notes.txt")
+  end
+end

data/spec/elelem/tools/git_spec.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+RSpec.describe "the git tool" do
+  around { |example| Dir.mktmpdir { |dir| Dir.chdir(dir) { example.run } } }
+
+  it "reports a failing git command as an error" do
+    result = run_tool("git", { "command" => "log" })
+
+    expect(result).not_to be_ok
+    expect(result[:error]).to include(result[:exit_status].to_s)
+  end
+
+  it "passes a working git command through" do
+    system("git", "init", "-q", ".")
+
+    expect(run_tool("git", { "command" => "status" })).to be_ok
+  end
+
+  it "asks once, showing the command line it runs" do
+    home = Dir.home
+    ENV["HOME"] = Dir.pwd # ignore ~/.agents/permissions.json
+    system("git", "init", "-q", ".")
+    prompts = []
+    input = Class.new do
+      define_method(:interactive?) { true }
+      define_method(:ask) { |text| prompts << text and "y" }
+    end.new
+    session = Elelem::Config.build_session("demo", input: input, output: Elelem::NullOutput.new)
+
+    expect(session.toolbox.run("git", { "command" => "status" })).to be_ok
+    expect(prompts).to eq(["  Allow execute `git status`? [Y/n] > "])
+  ensure
+    ENV["HOME"] = home
+  end
+end

data/spec/elelem/tools/permissions_spec.rb

@@ -7,6 +7,10 @@ RSpec.describe Elelem::Tools::Permissions do
 
   describe "#check" do
     context "with default allow policies" do
+      it "allows verify, whose commands are still checked as execute" do
+        expect(subject.check("verify", { "path" => "a.rb" }, input: input)).to be true
+      end
+
       it "allows read without prompting" do
         expect(subject.check("read", {}, input: input)).to be true
         expect(input).not_to have_received(:ask)
@@ -43,6 +47,135 @@ RSpec.describe Elelem::Tools::Permissions do
 
         it { expect { subject.check("execute", {}, input: input) }.to raise_error(/User denied permission/) }
       end
+
+      context "at end of input" do
+        let(:answer) { nil }
+
+        it { expect { subject.check("execute", {}, input: input) }.to raise_error(/User denied permission/) }
+      end
+
+      context "when the answer is an empty line" do
+        let(:answer) { "" }
+
+        it { expect(subject.check("execute", {}, input: input)).to be true }
+      end
+
+      %w[y Y yes YES].each do |yes|
+        context "when the answer is #{yes}" do
+          let(:answer) { yes }
+
+          it { expect(subject.check("execute", {}, input: input)).to be true }
+        end
+      end
+
+      %w[no np nope x].each do |other|
+        context "when the answer is #{other}" do
+          let(:answer) { other }
+
+          it { expect { subject.check("execute", {}, input: input) }.to raise_error(/User denied permission/) }
+        end
+      end
+
+      context "with arguments" do
+        let(:answer) { "y" }
+
+        it "shows the whole command" do
+          subject.check("execute", { "command" => "rg -n foo ." }, input: input)
+
+          expect(input).to have_received(:ask).with("  Allow execute `rg -n foo .`? [Y/n] > ")
+        end
+
+        it "escapes newlines so no line is hidden" do
+          subject.check("execute", { "command" => "ls\nrm -rf x" }, input: input)
+
+          expect(input).to have_received(:ask).with("  Allow execute `\"ls\\nrm -rf x\"`? [Y/n] > ")
+        end
+
+        it "escapes characters that could redraw the prompt" do
+          subject.check("execute", { "command" => "rm -rf ~ \r  Allow execute `ls" }, input: input)
+
+          expect(input).to have_received(:ask).with("  Allow execute `\"rm -rf ~ \\r  Allow execute `ls\"`? [Y/n] > ")
+        end
+
+        it "shows other tools' arguments as JSON" do
+          subject.check("grep", { "pattern" => "foo" }, input: input)
+
+          expect(input).to have_received(:ask).with("  Allow grep `{\"pattern\":\"foo\"}`? [Y/n] > ")
+        end
+      end
+    end
+
+    context "inside a tool that runs its own command" do
+      let(:input) { double(interactive?: true) }
+      let(:answers) { [] }
+
+      before { allow(input).to receive(:ask) { answers.shift } }
+
+      def run_tool(permissions, name)
+        permissions.check(name, { "pattern" => "x" }, input: input)
+        Elelem::Tools.nested { permissions.check("execute", { "command" => "rg -n x ." }, input: input) }
+      end
+
+      it "does not ask again after the person approved the tool" do
+        answers.push("y")
+
+        expect(run_tool(subject, "grep")).to be true
+        expect(input).to have_received(:ask).once
+      end
+
+      it "still asks for the command when the tool was allowed without asking" do
+        answers.push("n")
+        allowed = described_class.new(rules: { git: :allow })
+
+        expect { run_tool(allowed, "git") }.to raise_error(/User denied permission: execute/)
+      end
+
+      it "still refuses a denied execute" do
+        answers.push("y")
+        denied = described_class.new(rules: { execute: :deny })
+
+        expect { run_tool(denied, "grep") }.to raise_error(/Permission denied: execute/)
+      end
+
+      it "forgets the approval at the next tool" do
+        answers.push("y", "n")
+        permissions = described_class.new(rules: { list: :allow })
+        run_tool(permissions, "grep")
+
+        expect { run_tool(permissions, "list") }.to raise_error(/User denied permission: execute/)
+      end
+    end
+
+    context "with a misspelled policy on an interactive input" do
+      subject { described_class.new(rules: { execute: :dney }) }
+
+      let(:input) { double(ask: "n", interactive?: true) }
+
+      it "asks" do
+        expect { subject.check("execute", {}, input: input) }.to raise_error(/User denied permission/)
+        expect(input).to have_received(:ask)
+      end
+    end
+  end
+
+  describe "loading a config" do
+    it "asks for a value that is not a string" do
+      Dir.mktmpdir do |dir|
+        path = File.join(dir, "permissions.json")
+        File.write(path, '{"execute": false}')
+        rules = subject.send(:load_config, path)
+        input = double(ask: "n", interactive?: true)
+        expect { described_class.new(rules: rules).check("execute", {}, input: input) }
+          .to raise_error(/User denied permission/)
+      end
+    end
+
+    it "ignores a file that is not an object" do
+      Dir.mktmpdir do |dir|
+        path = File.join(dir, "permissions.json")
+        File.write(path, "[]")
+        expect(subject.send(:load_config, path)).to eq({})
+      end
     end
   end
 end

data/spec/elelem/tools/verify_spec.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+RSpec.describe "the verify tool" do
+  around { |example| Dir.mktmpdir { |dir| Dir.chdir(dir) { example.run } } }
+
+  it "fails when a check fails" do
+    File.write("bad.rb", "def oops")
+    result = run_tool("verify", { "path" => "bad.rb" })
+
+    expect(result).not_to be_ok
+    expect(result[:error]).to include(result[:exit_status].to_s)
+  end
+
+  it "checks a written file once, in the write's own result" do
+    checks = []
+    session.toolbox.before("execute") { |args| checks << args["command"] }
+    result = run_tool("write", { "path" => "bad.rb", "content" => "def oops" })
+
+    expect(result[:verify]).to include(command: "ruby -c bad.rb", ok: false)
+    expect(checks).to eq(["ruby -c bad.rb"])
+  end
+
+  it "passes when every check passes" do
+    File.write("good.rb", "1")
+
+    expect(run_tool("verify", { "path" => "good.rb" })[:verified]).to eq(["ruby -c good.rb"])
+  end
+
+  it "passes the path to the shell as one word" do
+    path = "a b; touch pwned.rb"
+    File.write(path, "1")
+
+    expect(run_tool("verify", { "path" => path })).to be_ok
+    expect(File).not_to exist("pwned.rb")
+  end
+end

data/spec/spec_helper.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
 require_relative "../lib/elelem/tools"
+require_relative "support/session"
 
 RSpec.configure do |config|
   config.disable_monkey_patching!
+  config.include SessionHelper
 
   config.expect_with :rspec do |c|
     c.syntax = :expect

data/spec/support/session.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SessionHelper
+  def session
+    @session ||= Elelem::Config.build_session("demo", input: Elelem::NullInput.new, output: Elelem::NullOutput.new)
+  end
+
+  def run_tool(name, args)
+    session.toolbox.run(name, args)
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: elelem-tools
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - mo khan
@@ -13,30 +13,22 @@ dependencies:
   name: elelem
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.11'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
+        version: 0.13.1
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0.11'
-- !ruby/object:Gem::Dependency
-  name: elelem-builtins
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.13.1
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '1'
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
@@ -86,7 +78,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/release.yml"
+- ".release-please-manifest.json"
 - ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
 - LICENSE.txt
 - Rakefile
 - lib/elelem/tools.rb
@@ -108,15 +104,23 @@ files:
 - lib/elelem/tools/task.rb
 - lib/elelem/tools/verify.rb
 - lib/elelem/tools/version.rb
+- release-please-config.json
+- spec/elelem/tools/arguments_spec.rb
+- spec/elelem/tools/edit_spec.rb
+- spec/elelem/tools/fallback_spec.rb
+- spec/elelem/tools/git_spec.rb
 - spec/elelem/tools/permissions_spec.rb
+- spec/elelem/tools/verify_spec.rb
 - spec/spec_helper.rb
-homepage: https://src.mokhan.ca/elelem/tools
+- spec/support/session.rb
+homepage: https://elelem.sh
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://src.mokhan.ca/elelem/tools
-  source_code_uri: https://src.mokhan.ca/elelem/tools
+  homepage_uri: https://elelem.sh
+  source_code_uri: https://github.com/elelem-sh/tools
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -131,7 +135,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.20
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Optional tools for elelem.
 test_files: []