samagotchi 0.17.0 → 0.18.1

data/lib/samagotchi/guardrail_wiring.rb

@@ -5,6 +5,8 @@ require "yaml"
 require_relative "config"
 require_relative "log"
 require_relative "guardrails"
+require_relative "memory_bundle/manifest"
+require_relative "version"
 require_relative "hooks"
 require_relative "edit_preview"
 require_relative "tool_activity"
@@ -32,7 +34,10 @@ module Samagotchi
     # @param model_name [#call] → String, nil: the effective model's bare name
     # @param cancelled [#call] → Boolean, whether the running turn is cancelled
     # @param ask       [#call] (fields) → the answer; the Engine's question flow
-    def initialize(scratch:, hooks:, tools:, session:, model_key:, cancelled:, ask:, model_name: -> {})
+    # @param notify    [#call] (message) → shows a guardrails line in every UI
+    #   (a bundle's rules kept because it needs a newer chi)
+    def initialize(scratch:, hooks:, tools:, session:, model_key:, cancelled:, ask:, model_name: -> {},
+                   notify: ->(_message) {})
       @scratch = scratch
       @hooks_lookup = hooks
       @tools_lookup = tools
@@ -41,6 +46,11 @@ module Samagotchi
       @model_name_lookup = model_name
       @cancelled_lookup = cancelled
       @ask = ask
+      @notify = notify
+      # Bundle name → the rules last loaded from it whole, kept while the
+      # installed version needs a newer chi; [name, version] said so once.
+      @loaded_bundle_rules = {}
+      @kept_noticed = {}
       @failures = Guardrails::LoadFailures.new
       @rules_mutex = Mutex.new
       @git = Guardrails::GitInfo.new
@@ -115,7 +125,9 @@ module Samagotchi
 
     # Installed bundles' guardrails/*.yml, by bundle name then file name.
     # A file that is missing, changed since install (sha256) or doesn't
-    # parse is a required load failure.
+    # parse is a required load failure. A bundle whose requires_chi this
+    # chi doesn't meet isn't read (its rules may use keys this chi doesn't
+    # know): the rules last loaded from it stay (#too_new_bundle_rules).
     def bundle_rules
       require_relative "memory_bundle/provenance"
       rules = []
@@ -125,7 +137,13 @@ module Samagotchi
           @failures.add("rules (bundle #{bundle_name})", data[:error], required: true, group: :rules)
           next
         end
+        if (too_new = MemoryBundle::Manifest.requires_chi_failure(data[:requires_chi], Samagotchi::VERSION))
+          rules.concat(too_new_bundle_rules(bundle_name, data, too_new))
+          next
+        end
         dir = MemoryBundle::Provenance.new(name: bundle_name).guardrails_dir
+        loaded = []
+        whole = true
         data[:guardrails].sort_by { |k, _| k.to_s }.each do |basename, meta|
           what = "rules #{basename} (bundle #{bundle_name})"
           path = File.join(dir, basename.to_s)
@@ -139,12 +157,15 @@ module Samagotchi
             doc = YAML.safe_load(File.read(path))
             raise Guardrails::Rules::ParseError, "expected a mapping with rules:" unless doc.is_a?(Hash)
 
-            rules.concat(Guardrails::Rules.parse(doc["rules"], source: "bundle #{bundle_name}"))
+            loaded.concat(Guardrails::Rules.parse(doc["rules"], source: "bundle #{bundle_name}"))
           rescue Guardrails::Rules::ParseError, Psych::Exception => e
             Log.warn(:guardrails, "rules_file_invalid", echo: "[samagotchi:guardrails] #{what}: #{e.message}", bundle: bundle_name, file: basename.to_s)
             @failures.add(what, e.message, required: true, group: :rules)
+            whole = false
           end
         end
+        rules.concat(loaded)
+        @loaded_bundle_rules[bundle_name] = loaded if whole
       end
       rules
     rescue StandardError => e
@@ -192,6 +213,38 @@ module Samagotchi
 
     private
 
+    # The rules of a bundle that needs a newer chi: the ones last loaded
+    # from it, with one notice per bundle version (restart the session to
+    # load the new ones). Never loaded (a chi older than the bundle it
+    # starts with): none, and a required load failure, as the hook loader
+    # does for a guardrail hook, so the calls aren't quietly unguarded.
+    def too_new_bundle_rules(bundle_name, data, reason)
+      kept = @loaded_bundle_rules[bundle_name]
+      unless kept
+        Log.warn(:guardrails, "bundle_rules_requires_chi", echo: "[samagotchi:guardrails] bundle #{bundle_name}: its rules are not loaded: #{reason}",
+                                                           bundle: bundle_name)
+        @failures.add("rules (bundle #{bundle_name})", "#{reason}; update chi (chi update) or uninstall the bundle",
+                      required: true, group: :rules)
+        return []
+      end
+
+      key = [bundle_name, data[:version].to_s]
+      return kept if @kept_noticed[key]
+
+      @kept_noticed[key] = true
+      Log.warn(:guardrails, "bundle_rules_kept", bundle: bundle_name, version: data[:version].to_s,
+                                                 requires_chi: data[:requires_chi].to_s)
+      @notify.call(kept_notice(bundle_name, data))
+      kept
+    end
+
+    def kept_notice(bundle_name, data)
+      id = @session_lookup.call&.id || "ID"
+      "bundle #{bundle_name} #{data[:version]} needs chi #{data[:requires_chi]} and this session runs chi #{Samagotchi::VERSION}: " \
+        "its new rules are not loaded, the ones loaded before still apply. Restart the session to load them " \
+        "(chi sessions stop #{id}, then chi --resume #{id})"
+    end
+
     # [path, mtime, size] of config.yml and every installed bundle's
     # manifest.json and guardrails/ file.
     def rules_stamp

data/lib/samagotchi/guardrails/outside.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require_relative "protected_paths"
+require_relative "../memory_bundle/index_sync"
+
+module Samagotchi
+  module Guardrails
+    # What `outside_repo` means (a rule's path: and git:): a path is outside
+    # when it isn't in the session's repo root (the cwd outside a repo),
+    # with symlinks resolved on both sides. Never outside:
+    # - a memory's file (MemoryBundle::IndexSync.memory_scope): write/edit
+    #   there is what memory_write does; index.md, the bundles dir and the
+    #   rest of chi's config dir still count;
+    # - a tmp dir (Dir.tmpdir, /tmp, /var/tmp), unless the session's root
+    #   is itself in that tmp dir (a sandbox there still gets the check
+    #   between its siblings).
+    # chi's state dir is not special: nothing there is the model's to write.
+    module Outside
+      TMP_DIRS = %w[/tmp /var/tmp].freeze
+
+      # @param path [String] absolute
+      # @param root [String] the session's repo root (or cwd)
+      def self.outside?(path, root:)
+        real = ProtectedPaths.real(path)
+        session = ProtectedPaths.real(root)
+        return false if within?(real, session)
+        return false if MemoryBundle::IndexSync.memory_scope(path)
+        return false if tmp_roots.any? { |tmp| within?(real, tmp) && !within?(session, tmp) }
+
+        true
+      end
+
+      # The tmp dirs that exist, resolved.
+      def self.tmp_roots
+        [Dir.tmpdir, *TMP_DIRS].filter_map do |dir|
+          File.realpath(dir) if File.directory?(dir)
+        rescue SystemCallError
+          nil
+        end.uniq
+      end
+
+      def self.within?(path, root) = path == root || path.start_with?(File.join(root, ""))
+    end
+  end
+end

data/lib/samagotchi/guardrails/parent_approvals.rb

@@ -5,6 +5,7 @@ require_relative "../paths"
 require_relative "../hooks/loader"
 require_relative "approval"
 require_relative "protected_paths"
+require_relative "parent_continue"
 
 module Samagotchi
   module Guardrails
@@ -115,6 +116,7 @@ module Samagotchi
       def message(reason, typed: false)
         deny = typed ? "deny it (n; WHY), and tell your user" : "deny it (--option Deny --text WHY), and tell your user"
         case reason
+        when :stop_only then ParentContinue.message
         when :protected then "this call changes chi's own config, hooks or guardrails, and only the user can allow it: #{deny}"
         when :off then "allowing a tool call is up to the user: #{deny}"
         else "only Allow once (#{KEY}: once) can be given here: #{deny}"

data/lib/samagotchi/guardrails/parent_continue.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "../config"
+
+module Samagotchi
+  module Guardrails
+    # Whether a parent agent may answer Continue to a session's step-limit
+    # question (kind "continue", ContinueOffer): turn.parent_continue,
+    # config.yml only, default true. Continue grants no permission (every
+    # tool call still meets the guardrails), it spends time and tokens;
+    # false makes parents stop-only. Checked by `chi answer` before it posts
+    # and by the worker's question desk for an answer marked as chi
+    # answer's, the way ParentApprovals is.
+    module ParentContinue
+      KEY = "turn.parent_continue"
+      KIND = "continue"
+      CONTINUE = "Continue"
+
+      module_function
+
+      # @return [Boolean] this process's setting
+      def allowed?
+        Config.get(KEY) != false
+      end
+
+      # Why a parent may not give this answer, or nil.
+      # @param pending [Hash] the pending question (symbol or string keys)
+      # @param selected [Array<String>] the selected labels
+      # @return [Symbol, nil] :stop_only
+      def refusal(pending, selected, allowed: allowed?)
+        return nil if allowed
+        return nil unless (pending[:kind] || pending["kind"]).to_s == KIND
+
+        Array(selected).map(&:to_s).include?(CONTINUE) ? :stop_only : nil
+      end
+
+      def message
+        "a parent agent may only stop this turn here (#{KEY}: false): answer Stop " \
+          "(--option Stop --text WHY), or tell your user it waits"
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails/rules.rb

@@ -14,6 +14,8 @@ module Samagotchi
     #   path:    "outside_repo", or a glob on the resolved paths (absolute
     #            or "**/…" globs match the absolute path; others the path
     #            relative to the repo root, the cwd outside one)
+    #   git:     "outside_repo": a shell call runs a mutating git
+    #            subcommand outside the session's repo (ShellGitDirs)
     #   models:  "small" (Guardrails::ModelSize, guardrails.small_models),
     #            or a glob on the bare model name or the model key, or a
     #            list of them: the rule only votes for a model that matches
@@ -26,17 +28,19 @@ module Samagotchi
     class Rules
       class ParseError < StandardError; end
 
-      KEYS = %w[id tool command path models verdict reason scopes].freeze
+      KEYS = %w[id tool command path git models verdict reason scopes].freeze
+      MATCH_KEYS = %w[tool command path git].freeze
       VERDICTS = %w[ask deny].freeze
       GLOB_FLAGS = File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB
 
-      Rule = Struct.new(:id, :tools, :command, :path, :models, :verdict, :reason, :scopes, :source, keyword_init: true) do
+      Rule = Struct.new(:id, :tools, :command, :path, :git, :models, :verdict, :reason, :scopes, :source, keyword_init: true) do
         def matches?(targets)
           return false unless targets
           return false unless for_model?(targets.model_name, targets.model_key, -> { targets.small_model? })
           return false if tools && !tool_matches?(targets.tool)
           return false if command && !(targets.command && command.match?(targets.command))
           return false if path && !path_matches?(targets)
+          return false if git && !targets.git_outside_repo?
 
           true
         end
@@ -99,12 +103,12 @@ module Samagotchi
 
         verdict = raw["verdict"].to_s
         raise ParseError, "#{label}: verdict must be ask or deny (got #{verdict.inspect})" unless VERDICTS.include?(verdict)
-        unless %w[tool command path].any? { |k| raw.key?(k) }
-          raise ParseError, "#{label}: give at least one of tool, command, path"
+        unless MATCH_KEYS.any? { |k| raw.key?(k) }
+          raise ParseError, "#{label}: give at least one of #{MATCH_KEYS.join(", ")}"
         end
 
         Rule.new(id: id, tools: tools_of(raw["tool"], label), command: regex_of(raw["command"], label),
-                 path: path_of(raw["path"], label), models: models_of(raw["models"], label), verdict: verdict.to_sym,
+                 path: path_of(raw["path"], label), git: git_of(raw["git"], label), models: models_of(raw["models"], label), verdict: verdict.to_sym,
                  reason: (raw["reason"] || "rule #{id}").to_s, scopes: scopes_of(raw["scopes"], label), source: source)
       end
 
@@ -135,6 +139,14 @@ module Samagotchi
         value
       end
 
+      # Only "outside_repo" for now (room for globs later).
+      def self.git_of(value, label)
+        return nil if value.nil?
+        raise ParseError, "#{label}: git must be outside_repo" unless value == "outside_repo"
+
+        value
+      end
+
       def self.models_of(value, label)
         return nil if value.nil?
 

data/lib/samagotchi/guardrails/shell_git_dirs.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module Guardrails
+    # Where a shell command runs a git subcommand that changes a checkout
+    # (commit, add, reset, …): the directories, or :unknown for one that
+    # can't be read from the text ($VAR, $(…), `cd -`). Pure text: it
+    # follows cd/pushd/popd, ( … ) subshells, git -C/--git-dir/--work-tree
+    # and GIT_DIR/GIT_WORK_TREE. It catches honest mistakes (cd into
+    # another checkout and commit there); sh -c, scripts, aliases and
+    # $(…) bodies get through. Never raises on odd input.
+    module ShellGitDirs
+      MUTATING = %w[commit add reset checkout switch rebase merge push stash rm mv
+                    cherry-pick revert pull restore am].freeze
+      STASH_READS = %w[list show].freeze
+      # Longest first: "&&" before "&", ";;" before ";".
+      OPERATORS = ["&&", "||", ";;", "|&", ";", "|", "&", "\n", "(", ")"].freeze
+      PREFIXES = %w[command builtin exec time nohup env ! { if then else elif do while until].freeze
+      # git global options that take the next word as their value.
+      VALUE_OPTIONS = %w[-C -c --git-dir --work-tree --namespace].freeze
+      SUBST = "\0SUBST"
+      REDIRECT = /\A\d*[<>]/
+
+      # @param command [String] the shell command
+      # @param cwd [String] where it starts (the call's cwd:, else the session's)
+      # @param home [String] for ~, $HOME, ${HOME} and a bare cd
+      # @return [Array<String, Symbol>] absolute dirs and :unknown, unique
+      def self.for(command, cwd:, home: Dir.home)
+        Walk.new(cwd, home).run(simple_commands(lex(command.to_s)))
+      rescue ArgumentError, EncodingError
+        [] # a NUL byte, invalid UTF-8: the shell would refuse it too
+      end
+
+      # Words and operators ([:word, "x"] / [:op, "&&"]).
+      def self.lex(text)
+        Lexer.new(text).tokens
+      end
+
+      # The token stream split at operators into word lists; ( and ) become
+      # :open / :close markers.
+      def self.simple_commands(tokens)
+        commands = [[]]
+        tokens.each do |kind, value|
+          if kind == :op
+            commands << :open if value == "("
+            commands << :close if value == ")"
+            commands << []
+          else
+            commands.last << value
+          end
+        end
+        commands.reject { |c| c.is_a?(Array) && c.empty? }
+      end
+
+      # A hand-written shell lexer: quotes, backslashes, comments, $(…) and
+      # backticks (an opaque marker inside the word), redirections kept in
+      # their word (2>&1 doesn't split on &), operators.
+      class Lexer
+        def initialize(text)
+          @s = text
+          @i = 0
+          @tokens = []
+          @word = +""
+          @in_word = false
+        end
+
+        def tokens
+          step while @i < @s.size
+          flush
+          @tokens
+        end
+
+        private
+
+        def step
+          c = @s[@i]
+          case c
+          when "\\" then add(@s[@i + 1].to_s, 2)
+          when "'" then single_quote
+          when '"' then double_quote
+          when "`" then backtick
+          when "$" then @s[@i + 1] == "(" ? substitution : add(c, 1)
+          when "#" then @in_word ? add(c, 1) : comment
+          when ">", "<" then redirection
+          when " ", "\t" then flush && (@i += 1)
+          else operator_or_char(c)
+          end
+        end
+
+        def add(text, advance)
+          @word << text
+          @in_word = true
+          @i += advance
+        end
+
+        def flush
+          @tokens << [:word, @word.dup] if @in_word
+          @word.clear
+          @in_word = false
+          true
+        end
+
+        def single_quote
+          close = @s.index("'", @i + 1) || @s.size
+          add(@s[(@i + 1)...close].to_s, close + 1 - @i)
+        end
+
+        def double_quote
+          @i += 1
+          @in_word = true
+          while @i < @s.size && @s[@i] != '"'
+            if @s[@i] == "\\" && @i + 1 < @s.size
+              @word << @s[@i + 1]
+              @i += 2
+            else
+              @word << @s[@i]
+              @i += 1
+            end
+          end
+          @i += 1
+        end
+
+        def backtick
+          close = @s.index("`", @i + 1) || @s.size
+          add(SUBST, close + 1 - @i)
+        end
+
+        def substitution
+          depth = 0
+          j = @i + 1
+          loop do
+            depth += 1 if @s[j] == "("
+            depth -= 1 if @s[j] == ")"
+            j += 1
+            break if depth.zero? || j >= @s.size
+          end
+          add(SUBST, j - @i)
+        end
+
+        def comment
+          @i = @s.index("\n", @i) || @s.size
+        end
+
+        # >, >>, 2>&1, &>, <, <<: kept in the word (the walk drops them).
+        def redirection
+          add(@s[@i], 1)
+          add(@s[@i], 1) while @i < @s.size && @s[@i].match?(/[&\d>-]/) && @word.match?(/>\z/)
+        end
+
+        def operator_or_char(char)
+          op = OPERATORS.find { |o| @s[@i, o.size] == o }
+          return add(char, 1) unless op
+
+          if op == "&" && @word.match?(/\d*>\z/)
+            add(op, 1)
+          else
+            flush
+            @tokens << [:op, op]
+            @i += op.size
+          end
+        end
+      end
+
+      # Follows the current dir through the simple commands and records
+      # where each mutating git runs.
+      class Walk
+        def initialize(cwd, home)
+          @dir = cwd
+          @home = home
+          @subshells = []
+          @pushed = []
+          @found = []
+        end
+
+        def run(commands)
+          commands.each do |words|
+            case words
+            when :open then @subshells << @dir
+            when :close then @dir = @subshells.pop || @dir
+            else simple(words.dup)
+            end
+          end
+          @found.uniq
+        end
+
+        private
+
+        def simple(words)
+          env = {}
+          while (word = words.first)
+            if word.match?(/\A[A-Za-z_]\w*=/)
+              key, value = word.split("=", 2)
+              env[key] = value
+            elsif !PREFIXES.include?(word)
+              break
+            end
+            words.shift
+          end
+          verb = words.shift or return
+          args = words.grep_v(REDIRECT)
+          case verb
+          when "cd" then cd(args)
+          when "pushd"
+            @pushed << @dir
+            @dir = args.first ? expand(args.first, @dir) : nil
+          when "popd" then @dir = @pushed.pop unless @pushed.empty?
+          else git(args, env) if verb == "git" || verb.end_with?("/git")
+          end
+        end
+
+        def cd(args)
+          target = args.reject { |a| %w[-P -L -e -@].include?(a) }.first
+          @dir = if target.nil? then @home
+                 elsif target == "-" then nil
+                 else expand(target, @dir)
+                 end
+        end
+
+        def git(args, env)
+          dir = @dir
+          work_tree = env["GIT_WORK_TREE"] && expand(env["GIT_WORK_TREE"], dir)
+          git_dir = env["GIT_DIR"] && expand(env["GIT_DIR"], dir)
+          sub = nil
+          until args.empty?
+            arg = args.shift
+            case arg
+            when *VALUE_OPTIONS
+              value = args.shift.to_s
+              dir = expand(value, dir) if arg == "-C"
+              git_dir = expand(value, dir) if arg == "--git-dir"
+              work_tree = expand(value, dir) if arg == "--work-tree"
+            when /\A--git-dir=(.*)\z/m then git_dir = expand(Regexp.last_match(1), dir)
+            when /\A--work-tree=(.*)\z/m then work_tree = expand(Regexp.last_match(1), dir)
+            when /\A-/ then next
+            else
+              sub = arg
+              break
+            end
+          end
+          return unless MUTATING.include?(sub)
+          return if sub == "stash" && STASH_READS.include?(args.first)
+
+          @found << (work_tree || repo_of(git_dir) || dir || :unknown)
+        end
+
+        def repo_of(git_dir)
+          return nil unless git_dir
+
+          File.basename(git_dir) == ".git" ? File.dirname(git_dir) : git_dir
+        end
+
+        # An absolute path for +arg+ against +dir+; nil when it can't be
+        # told from the text (a variable, a substitution, a relative path
+        # against an unknown dir).
+        def expand(arg, dir)
+          return nil if arg.include?(SUBST)
+
+          arg = arg.sub(/\A(~|\$HOME|\$\{HOME\})(?=\/|\z)/) { @home }
+          return nil if arg.include?("$") || arg.start_with?("~")
+          return File.expand_path(arg) if arg.start_with?("/")
+
+          dir && File.expand_path(arg, dir)
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails/targets.rb

@@ -4,20 +4,27 @@ require_relative "../tools/tool_path"
 require_relative "../tools/memory"
 require_relative "../log"
 require_relative "model_size"
-require_relative "../memory_bundle/index_sync"
+require_relative "outside"
+require_relative "shell_git_dirs"
 
 module Samagotchi
   module Guardrails
     # What a tool call acts on, resolved the way the tools resolve it: the
     # shell command, absolute paths (against Dir.pwd, as the file tools have
     # no cwd:), the directory a command runs in, its repo root, and whether
-    # a path leaves the repo (the cwd when there is no repo).
+    # a path leaves the session's repo (Outside: the context cwd's repo
+    # root, the cwd when there is no repo; not the call's own cwd:).
     class Targets
       SHELL_TOOLS = %w[execute task_create].freeze
       PATH_TOOLS = %w[write edit read memory_write].freeze
 
       attr_reader :tool, :command, :paths, :cwd, :repo_root
 
+      # @return [String] the session's repo root (the context cwd's; the cwd
+      #   outside a repo): what outside_repo measures from. repo_root is the
+      #   call's (its own cwd: for shell and plugin tools).
+      attr_reader :session_root
+
       # @return [String, nil] the effective model: its bare name (no host
       #   prefix) and its key (ModelOverlay.key_for), for a rule's models:
       attr_reader :model_name, :model_key
@@ -62,7 +69,7 @@ module Samagotchi
           args = call[:args] if entry && !entry.core? && call[:args].is_a?(Hash)
         end
         new(tool: tool, command: command, paths: paths.compact, cwd: cwd, repo_root: context.repo_root(cwd), args: args,
-            model_name: model_name, model_key: model_key)
+            model_name: model_name, model_key: model_key, session_root: context.repo_root(base) || base)
       end
 
       # What a plugin tool's targets: callable says the call acts on:
@@ -102,7 +109,9 @@ module Samagotchi
         nil
       end
 
-      def initialize(tool:, command:, paths:, cwd:, repo_root:, args: nil, model_name: nil, model_key: nil)
+      def initialize(tool:, command:, paths:, cwd:, repo_root:, args: nil, model_name: nil, model_key: nil,
+                     session_root: nil)
+        @session_root = session_root || repo_root || cwd
         @args = args
         @model_name = model_name
         @model_key = model_key
@@ -123,20 +132,28 @@ module Samagotchi
         @small_model = ModelSize.small?(@model_name, @model_key)
       end
 
-      # Whether any path is outside the repo root (the cwd outside a repo).
-      # A memory's file doesn't count (MemoryBundle::IndexSync.memory_scope):
-      # write/edit there is what memory_write does, unasked; index.md, the
-      # bundles dir and the rest of chi's config dir still count.
+      # Whether any path is outside the session's repo (Outside.outside?:
+      # symlinks resolved; a memory's file and tmp dirs don't count).
       def outside_repo?
-        root = @repo_root || @cwd
-        @paths.any? do |p|
-          p != root && !p.start_with?(File.join(root, "")) && !MemoryBundle::IndexSync.memory_scope(p)
-        end
+        @paths.any? { |p| Outside.outside?(p, root: @session_root) }
+      end
+
+      # Where a shell call runs mutating git (ShellGitDirs: dirs, and
+      # :unknown for one the text doesn't tell); [] for other tools.
+      def git_dirs
+        @git_dirs ||= shell? ? ShellGitDirs.for(@command, cwd: @cwd) : []
+      end
+
+      # Whether a shell call runs mutating git outside the session's repo
+      # (an :unknown dir doesn't count).
+      def git_outside_repo?
+        git_dirs.any? { |dir| dir.is_a?(String) && Outside.outside?(dir, root: @session_root) }
       end
 
       # The hook event's targets: hash.
       def to_h
-        { command: @command, paths: @paths, cwd: @cwd, repo_root: @repo_root, outside_repo: outside_repo? }
+        { command: @command, paths: @paths, cwd: @cwd, repo_root: @repo_root, outside_repo: outside_repo?,
+          git_dirs: git_dirs.map(&:to_s) }
       end
     end
   end

data/lib/samagotchi/guardrails.rb

@@ -2,6 +2,8 @@
 
 require_relative "guardrails/verdict"
 require_relative "guardrails/context"
+require_relative "guardrails/outside"
+require_relative "guardrails/shell_git_dirs"
 require_relative "guardrails/targets"
 require_relative "guardrails/model_size"
 require_relative "guardrails/approval"

data/lib/samagotchi/iteration_limit.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "log"
+
+module Samagotchi
+  # A turn's iteration limit (how many model ↔ tool rounds before the turn
+  # stops and offers to continue), one resolver for the Engine, the worker
+  # and the REPL.
+  module IterationLimit
+    KEY = "turn.max_iterations"
+    # A turn's limit unless turn.max_iterations says otherwise, and the
+    # loops' own default.
+    DEFAULT = 100
+    # A --no-interrupt / --non-interactive turn's, at least: nobody is there
+    # to answer a continue offer.
+    NO_INTERRUPT = 1000
+
+    # @param no_interrupt [Boolean] the turn runs with nobody to answer: the
+    #   larger of NO_INTERRUPT and the configured limit, so a configured one
+    #   above 1000 is never lowered
+    # @return [Integer]
+    def self.for(no_interrupt: false) = no_interrupt ? [NO_INTERRUPT, configured].max : configured
+
+    # turn.max_iterations (env SAMAGOTCHI_TURN_MAX_ITERATIONS); one below 1
+    # is DEFAULT, with a warning.
+    # @return [Integer]
+    def self.configured
+      value = Config.get(KEY)
+      return DEFAULT if value.nil?
+      return value if value.is_a?(Integer) && value >= 1
+
+      Log.warn(:config, "invalid_value", echo: "Warning: #{KEY} must be 1 or more, got #{value.inspect} — using #{DEFAULT}",
+                                         key: KEY)
+      DEFAULT
+    end
+  end
+end