samagotchi 0.2.0

data/lib/samagotchi/guardrails/rules.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require_relative "verdict"
+require_relative "targets"
+
+module Samagotchi
+  module Guardrails
+    # Declarative rules from config.yml's `guardrails:` section (and, later,
+    # installed bundles). All the fields a rule gives must match:
+    #   tool:    a tool name, a list, or "shell" (execute + task_create);
+    #            a name may be a glob ("mcp_*", "mcp_{git,gh}_*")
+    #   command: a Ruby regex on a shell tool's command
+    #   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)
+    # verdict ask|deny, reason, scopes (for an ask; default all).
+    # `guardrails.disable` switches single rules off (#parse_disable).
+    # A rule that doesn't parse raises ParseError: the Engine then denies
+    # every call (a rule set that silently vanished is what this guards
+    # against). Unknown keys are errors for the same reason (a typo).
+    class Rules
+      class ParseError < StandardError; end
+
+      KEYS = %w[id tool command path verdict reason scopes].freeze
+      VERDICTS = %w[ask deny].freeze
+      GLOB_FLAGS = File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB
+
+      Rule = Struct.new(:id, :tools, :command, :path, :verdict, :reason, :scopes, :source, keyword_init: true) do
+        def matches?(targets)
+          return false unless targets
+          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)
+
+          true
+        end
+
+        def tool_matches?(name)
+          tools.any? { |tool| Rules.glob?(tool) ? File.fnmatch(tool, name.to_s, File::FNM_EXTGLOB) : tool == name }
+        end
+
+        def path_matches?(targets)
+          return targets.outside_repo? if path == "outside_repo"
+
+          base = targets.repo_root || targets.cwd
+          glob = path.start_with?("~") ? File.expand_path(path) : path
+          targets.paths.any? do |p|
+            candidate = glob.start_with?("/", "**") ? p : relative(p, base)
+            candidate && File.fnmatch(glob, candidate, GLOB_FLAGS)
+          end
+        end
+
+        def relative(path, base)
+          prefix = File.join(base, "")
+          path.start_with?(prefix) ? path.delete_prefix(prefix) : nil
+        end
+      end
+
+      # @param list [Array<Hash>, nil] the YAML rules
+      # @param source [String] "config", "bundle <name>"
+      # @return [Array<Rule>]
+      def self.parse(list, source:)
+        return [] if list.nil?
+        raise ParseError, "rules must be a list" unless list.is_a?(Array)
+
+        list.each_with_index.map { |raw, idx| parse_rule(raw, idx, source) }
+      end
+
+      def self.parse_rule(raw, idx, source)
+        raise ParseError, "rule #{idx + 1} is not a mapping" unless raw.is_a?(Hash)
+
+        raw = raw.transform_keys(&:to_s)
+        id = raw["id"].to_s.strip
+        label = id.empty? ? "rule #{idx + 1}" : "rule #{id}"
+        unknown = raw.keys - KEYS
+        raise ParseError, "#{label}: unknown key(s) #{unknown.join(", ")}" unless unknown.empty?
+        raise ParseError, "#{label}: id is required" if id.empty?
+
+        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"
+        end
+
+        Rule.new(id: id, tools: tools_of(raw["tool"], label), command: regex_of(raw["command"], label),
+                 path: path_of(raw["path"], label), verdict: verdict.to_sym,
+                 reason: (raw["reason"] || "rule #{id}").to_s, scopes: scopes_of(raw["scopes"], label), source: source)
+      end
+
+      def self.tools_of(value, label)
+        return nil if value.nil?
+
+        names = Array(value).map(&:to_s)
+        raise ParseError, "#{label}: tool must be a name or a list of names" if names.empty? || names.any?(&:empty?)
+
+        names.flat_map { |n| n == "shell" ? Targets::SHELL_TOOLS : [n] }.uniq
+      end
+
+      # Whether a rule's tool name is a glob.
+      def self.glob?(name) = name.match?(/[*?\[{]/)
+
+      def self.regex_of(value, label)
+        return nil if value.nil?
+
+        Regexp.new(value.to_s)
+      rescue RegexpError => e
+        raise ParseError, "#{label}: command is not a valid regex: #{e.message}"
+      end
+
+      def self.path_of(value, label)
+        return nil if value.nil?
+        raise ParseError, "#{label}: path must be a string" unless value.is_a?(String) && !value.empty?
+
+        value
+      end
+
+      def self.scopes_of(value, label)
+        return nil if value.nil?
+
+        scopes = Array(value).map(&:to_s)
+        bad = scopes - Verdict::SCOPES
+        raise ParseError, "#{label}: unknown scope(s) #{bad.join(", ")}" unless bad.empty?
+
+        scopes
+      end
+
+      # config.yml's `guardrails.disable`: rule ids ("git-rebase", any
+      # source) or "<bundle>:<id>" (that bundle's rule only).
+      # @return [Array<String>]
+      def self.parse_disable(value)
+        return [] if value.nil?
+
+        ids = Array(value)
+        unless ids.all? { |id| id.is_a?(String) && !id.strip.empty? }
+          raise ParseError, "disable must be a list of rule ids (id or bundle:id)"
+        end
+
+        ids.map(&:strip)
+      end
+
+      attr_reader :rules
+
+      # @param rules [Array<Rule>] in order: config first, then bundles by name
+      # @param enabled [Boolean] false: no rules, and hooks' asks are dropped
+      # @param disable [Array<String>] from #parse_disable: rules that don't vote
+      def initialize(rules = [], enabled: true, disable: [])
+        @rules = rules
+        @enabled = enabled
+        @disable = disable
+      end
+
+      def enabled? = @enabled
+
+      def disabled?(rule)
+        @disable.any? { |entry| disables?(entry, rule) }
+      end
+
+      # The disable entries no loaded rule has (a typo, or an uninstalled bundle).
+      def unmatched_disables
+        @disable.reject { |entry| @rules.any? { |rule| disables?(entry, rule) } }
+      end
+
+      # A core check: every matching rule votes (strictest wins).
+      def check(verdict)
+        return verdict unless @enabled
+
+        @rules.each do |rule|
+          next if disabled?(rule)
+          next unless rule.matches?(verdict.targets)
+
+          if rule.verdict == :deny
+            verdict.deny!(rule.reason, rule: rule.id, source: rule.source, decided_by: "rule")
+          else
+            verdict.ask!(rule.reason, scopes: rule.scopes, rule: rule.id, source: rule.source, decided_by: "rule")
+          end
+        end
+        verdict
+      end
+
+      def disables?(entry, rule)
+        bundle, id = entry.include?(":") ? entry.split(":", 2) : [nil, entry]
+        id == rule.id && (bundle.nil? || rule.source == "bundle #{bundle}")
+      end
+      private :disables?
+
+      # A core check that runs right after the hooks: with guardrails
+      # disabled, a hook's ask is dropped (a deny still applies).
+      def hook_asks
+        rules = self
+        Object.new.tap do |check|
+          check.define_singleton_method(:check) do |verdict|
+            verdict.drop_ask! if !rules.enabled? && verdict.ask? && verdict.decided_by == "hook"
+            verdict
+          end
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails/targets.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative "../tools/tool_path"
+require_relative "../tools/memory"
+require_relative "../log"
+
+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).
+    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 [Hash, nil] a plugin tool's arguments (call[:args]), for an
+      #   approval of a call whose targets name no command or path; nil for
+      #   chi's own tools
+      attr_reader :args
+
+      # @param call [Hash] the parsed tool call
+      # @param context [Context]
+      # @param model_key [String, nil] for a memory_write model overlay
+      # @param registry [Tools::Registry, nil] the session's tools: a plugin
+      #   tool's entry says what it acts on (its targets:)
+      def self.for(call, context, model_key: nil, registry: nil)
+        tool = call[:name].to_s
+        base = context.cwd
+        command = nil
+        paths = []
+        cwd = base
+        args = nil
+        case tool
+        when *SHELL_TOOLS
+          command = call[:content].to_s
+          given = call[:cwd].to_s.strip
+          cwd = File.expand_path(given, base) unless given.empty?
+        when "write", "edit"
+          paths << absolute(call[:path], base)
+        when "read"
+          paths << absolute(call[:content], base)
+        when "memory_write"
+          paths << memory_path(call, model_key)
+        else
+          given = plugin_targets(call, registry)
+          command = given[:command]
+          given_cwd = given[:cwd].to_s.strip
+          cwd = File.expand_path(given_cwd, base) unless given_cwd.empty?
+          paths.concat(given[:paths].map { |path| absolute(path, cwd) })
+          entry = registry && registry[tool]
+          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)
+      end
+
+      # What a plugin tool's targets: callable says the call acts on:
+      # {command:, paths:, cwd:}, each optional; a callable that raises or
+      # gives something else counts as nothing (and is logged).
+      def self.plugin_targets(call, registry)
+        entry = registry && registry[call[:name].to_s]
+        none = { command: nil, paths: [], cwd: nil }
+        return none unless entry && !entry.core? && entry.targets
+
+        given = entry.targets.call(call)
+        return none unless given.is_a?(Hash)
+
+        given = given.transform_keys(&:to_sym)
+        command = given[:command].to_s
+        { command: command.empty? ? nil : command, paths: Array(given[:paths]).map(&:to_s), cwd: given[:cwd] }
+      rescue StandardError => e
+        Log.warn(:plugins, "plugin_targets_failed", tool: call[:name].to_s, error: e.class.name,
+                                                    msg: "#{call[:name]} targets failed: #{e.message}")
+        none
+      end
+
+      def self.absolute(path, base)
+        path = Tools::ToolPath.normalize(path)
+        path.empty? ? nil : File.expand_path(path, base)
+      end
+
+      # The file memory_write would write; nil when the call is invalid.
+      def self.memory_path(call, model_key)
+        entry = call[:path].to_s.strip
+        return nil if entry.empty? || call[:scope].to_s.strip.empty?
+
+        dir = Tools::MemoryRead.memories_dir(Tools::MemoryRead.normalize_scope(call[:scope]))
+        overlay = call[:current_model_only].to_s.strip.downcase == "true" && model_key
+        File.expand_path(overlay ? "#{entry}.#{model_key}.md" : "#{entry}.md", dir)
+      rescue StandardError
+        nil
+      end
+
+      def initialize(tool:, command:, paths:, cwd:, repo_root:, args: nil)
+        @args = args
+        @tool = tool
+        @command = command
+        @paths = paths
+        @cwd = cwd
+        @repo_root = repo_root
+      end
+
+      def shell? = SHELL_TOOLS.include?(@tool)
+
+      # Whether any path is outside the repo root (the cwd outside a repo).
+      def outside_repo?
+        root = @repo_root || @cwd
+        @paths.any? { |p| p != root && !p.start_with?(File.join(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? }
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails/verdict.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module Guardrails
+    # The gate's verdict for one tool call. Voters (hooks now, rules later)
+    # call #deny! or #ask!; the strictest vote wins (deny > ask > allow) and
+    # a vote never relaxes it, so a deny is sticky. Of two equal votes the
+    # first one stays.
+    class Verdict
+      STRICTNESS = { allow: 0, ask: 1, deny: 2 }.freeze
+      SCOPES = %w[once session repo rule].freeze
+      DO_NOT_RETRY = "Do not retry it or reach the same result another way; ask the user how to proceed."
+
+      attr_reader :decision, :reason, :rule, :source, :scopes, :decided_by
+      # The call to dispatch; a hook may have replaced the original one.
+      attr_accessor :call
+      # The Context and the final call's Targets (set by the Gate).
+      attr_accessor :context, :targets
+      # The scope the user allowed an ask for ("once", "session", …).
+      attr_accessor :scope
+
+      def initialize(call:)
+        @call = call
+        @decision = :allow
+        @reason = nil
+        @rule = nil
+        @source = nil
+        @scopes = SCOPES
+        @decided_by = nil
+        @legacy = false
+        @note = nil
+        @voter = nil
+        @advice = nil
+      end
+
+      # @param rule [String, nil] the rule id, when a rule decided
+      # @param source [String, nil] where the rule came from ("config", "bundle x")
+      # @param advice [String, nil] what the model should do instead, in
+      #   place of the fixed "Do not retry it…" tail (a hook that rejects a
+      #   call so the model retries it corrected)
+      def deny!(reason, rule: nil, source: nil, decided_by: "hook", advice: nil)
+        @advice = advice.to_s.strip.empty? ? nil : advice.to_s.strip if vote(:deny, reason, rule: rule, source: source, decided_by: decided_by)
+        self
+      end
+
+      # @param scopes [Array<String>, nil] which approval scopes the user may
+      #   pick (default all of SCOPES)
+      def ask!(reason, scopes: nil, rule: nil, source: nil, decided_by: "hook")
+        return self unless vote(:ask, reason, rule: rule, source: source, decided_by: decided_by)
+
+        picked = Array(scopes).map(&:to_s) & SCOPES
+        @scopes = picked.empty? ? SCOPES : picked
+        self
+      end
+
+      # A before_tool_call hook set the old event[:blocked] flag. Its model
+      # text stays "blocked by guardrail: <reason>".
+      def legacy_deny!(reason)
+        @legacy = true if vote(:deny, reason, decided_by: "hook")
+        self
+      end
+
+      # Back to allow (guardrails disabled: a hook's ask doesn't count).
+      def drop_ask!
+        return self unless ask?
+
+        @decision = :allow
+        @reason = @rule = @source = @decided_by = @voter = @advice = nil
+        @scopes = SCOPES
+        self
+      end
+
+      # The user (or the lack of one) settled an ask.
+      # @param note [String, nil] for a deny, what the model is told about
+      #   the user ("The user declined.", "No one to approve it.")
+      def settle!(decision, decided_by: "user", note: nil)
+        @decision = decision
+        @decided_by = decided_by
+        @note = note
+        self
+      end
+
+      def allow? = @decision == :allow
+      def ask? = @decision == :ask
+      def deny? = @decision == :deny
+      def legacy? = @legacy
+
+      # What the model gets for a deny (after the "[tool] Error: " prefix):
+      # who decided, why, and not to route around it (or the voter's own
+      # advice). A user's deny leads with the user's answer, so it doesn't
+      # read as the rule refusing.
+      def deny_text
+        reason = @reason.to_s.strip
+        reason += "." unless reason.empty? || reason.match?(/[.!?]\z/)
+        parts = if @decided_by == "user" && @note
+                  [@note, "It needed approval (#{decider}):", reason]
+                else
+                  ["denied by guardrail (#{decider}):", reason, @note || "The user was not asked."]
+                end
+        (parts << (@advice || DO_NOT_RETRY)).reject(&:empty?).join(" ")
+      end
+
+      # For the activity entry; an allowed ask notes how ("approved (repo)",
+      # "approved earlier (session)").
+      def to_activity
+        note = if allow? && @scope
+                 "approved#{" earlier" if @decided_by == "approval"} (#{@scope})"
+               end
+        { rule: @rule, verdict: @decision.to_s, decided_by: @decided_by, scope: @scope, note: note }.compact
+      end
+
+      private
+
+      def decider
+        return [("rule #{@rule}" if @rule), @source].compact.join(", ") if @rule || @source
+
+        @voter || "hook"
+      end
+
+      def vote(decision, reason, decided_by:, rule: nil, source: nil)
+        return false unless STRICTNESS.fetch(decision) > STRICTNESS.fetch(@decision)
+
+        @decision = decision
+        @reason = reason.to_s.strip
+        @rule = rule&.to_s
+        @source = source&.to_s
+        @decided_by = decided_by
+        @voter = decided_by
+        @legacy = false
+        true
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "guardrails/verdict"
+require_relative "guardrails/context"
+require_relative "guardrails/targets"
+require_relative "guardrails/approval"
+require_relative "guardrails/approvals"
+require_relative "guardrails/protected_paths"
+require_relative "guardrails/load_failures"
+require_relative "guardrails/rules"
+require_relative "guardrails/gate"
+
+module Samagotchi
+  # Tool guardrails: the verdict every model tool call gets before it is
+  # dispatched. ToolRunner asks the Gate; hooks and rules vote.
+  module Guardrails
+  end
+end

data/lib/samagotchi/hooks/bundle_loader.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require_relative "registry"
+require "digest"
+require_relative "../log"
+
+module Samagotchi
+  # Namespace that wraps hook plugin classes per-bundle. Each bundle's hooks are
+  # evaluated inside `Samagotchi::Bundles::<BundleName>` so that two bundles
+  # shipping a file with the same basename (e.g. `guardrails.rb`) cannot collide
+  # on a top-level constant.
+  module Bundles; end
+
+  module Hooks
+    # Loads bundle-owned hook plugins into a Registry.
+    #
+    # Unlike +Hooks::Loader+ (which `require`s a file and resolves a top-level
+    # constant), this loader `module_eval`s each plugin file inside a
+    # per-bundle namespace module. This gives:
+    #   - zero class-name collisions across bundles
+    #   - a clean uninstall path (`Registry#unregister_bundle`)
+    #
+    # Each plugin must define a class whose PascalCase name matches the file
+    # basename and whose instances respond to +call(event)+.
+    #
+    # A "fail_closed" before_tool_call hook is required: if it is missing,
+    # fails to load, or its file's sha256 differs from the one recorded at
+    # install, the failure is reported and the gate denies every tool call.
+    # Any hook whose sha256 differs is not loaded (reinstall the bundle
+    # after editing a hook by hand).
+    #
+    # The +on_error+ policy is applied per hook at fire time:
+    #   - "fail_closed" (on :before_tool_call): a raising guardrail sets
+    #     event[:blocked] = true — the tool call is prevented (fail-closed).
+    #   - "log": warn to stderr and continue.
+    #   - "skip" (default): silently continue.
+    module BundleLoader
+      class << self
+        # Load all hook plugins for a bundle into the given registry.
+        #
+        # @param bundle_name [String]
+        # @param hooks_dir [String] directory containing the bundle's .rb hook files
+        # @param metadata [Hash] basename => { event:, on_error:, priority: }
+        # @param registry [Samagotchi::Hooks::Registry]
+        # @param failures [Guardrails::LoadFailures, nil] collects hooks that
+        #   failed to load
+        # @param settings [Hash] the bundle's section of config.yml
+        #   `bundles:` (string keys); a hook class whose initialize takes an
+        #   argument gets it
+        # @return [Integer] number of hooks successfully registered
+        def load(bundle_name:, hooks_dir:, metadata:, registry:, failures: nil, settings: {})
+          return 0 unless metadata.is_a?(Hash)
+
+          loaded = 0
+          metadata.each do |raw_basename, raw_meta|
+            basename = raw_basename.to_s
+            next if basename.empty?
+
+            meta = ->(key) { raw_meta && (raw_meta[key] || raw_meta[key.to_s]) }
+            event = meta.(:event).to_s
+            # A hook with no declared event cannot be auto-registered.
+            next if event.empty?
+
+            event_sym = event.to_sym
+            on_error = (meta.(:on_error) || "skip").to_s
+            priority = (meta.(:priority) || 100).to_i
+            fail_closed = on_error == "fail_closed" && event_sym == :before_tool_call
+            what = "hook #{basename} (bundle #{bundle_name})"
+            file = hooks_dir && File.join(hooks_dir, basename)
+            unless file && File.exist?(file)
+              failures&.add(what, "the file is missing", required: true) if fail_closed
+              next
+            end
+            if (mismatch = sha_mismatch(file, meta.(:sha256), required: fail_closed))
+              Log.warn(:hooks, "bundle_hook_mismatch", echo: "[samagotchi:hooks] bundle '#{bundle_name}' hook '#{basename}' not loaded: #{mismatch}", bundle: bundle_name, hook: basename.to_s)
+              failures&.add(what, mismatch, required: fail_closed)
+              next
+            end
+
+            begin
+              plugin = instantiate(bundle_name, basename, file, settings: settings)
+
+              registry.register_bundle(bundle_name, event_sym, hook_name: basename, priority: priority) do |event|
+                begin
+                  plugin.call(event)
+                rescue Exception => e
+                  handle_error(bundle_name, basename, on_error, fail_closed, event, e)
+                end
+              end
+              loaded += 1
+            rescue Exception => e
+              Log.error(:hooks, "bundle_hook_load_failed", echo: "[samagotchi:hooks] bundle '#{bundle_name}' hook '#{basename}' failed to load: #{e.class}: #{e.message}", bundle: bundle_name, hook: basename.to_s, error: e.class.name)
+              failures&.add(what, "#{e.class}: #{e.message}", required: fail_closed)
+            end
+          end
+          loaded
+        end
+
+        # Why the file doesn't match the sha256 recorded at install, or nil.
+        # With none recorded, only a required hook counts as a mismatch.
+        def sha_mismatch(file, recorded, required:)
+          expected = recorded.to_s.sub(/\Asha256:/, "")
+          return (required ? "no sha256 recorded for it (reinstall the bundle)" : nil) if expected.empty?
+
+          actual = Digest::SHA256.hexdigest(File.binread(file))
+          return nil if actual == expected
+
+          "its sha256 #{actual[0, 12]}… differs from the installed #{expected[0, 12]}… (edited after install? reinstall the bundle)"
+        end
+
+        # Evaluate a plugin file inside the bundle's namespace module and
+        # return an instance that responds to #call. A class whose
+        # initialize takes an argument gets the settings (one Hash, string
+        # keys); one that takes none is built bare.
+        def instantiate(bundle_name, basename, file, settings: {})
+          ns = namespace_for(bundle_name)
+          content = File.read(file)
+          ns.module_eval(content, file, 1)
+          class_name = File.basename(basename, ".rb").split("_").map(&:capitalize).join
+          klass = ns.const_get(class_name, false)
+          instance = Hooks.build_plugin(klass, settings)
+          raise ArgumentError, "plugin #{class_name} does not respond to #call" unless instance.respond_to?(:call)
+          instance
+        end
+
+        # The (lazily created) namespace module for a bundle.
+        # Sanitization is made injective by appending a short digest so that
+        # `my-bundle` and `my_bundle` do not collide.
+        def namespace_for(bundle_name)
+          raw = bundle_name.to_s
+          base = raw.gsub(/[^A-Za-z0-9_]/, "_")
+          base = "B_#{base}" unless base.match?(/\A[A-Z]/)
+          digest = Digest::MD5.hexdigest(raw)[0, 4]
+          ns_name = "#{base}_#{digest}"
+          if Samagotchi::Bundles.const_defined?(ns_name.to_sym, false)
+            Samagotchi::Bundles.const_get(ns_name.to_sym)
+          else
+            Samagotchi::Bundles.const_set(ns_name.to_sym, Module.new)
+          end
+        end
+
+        # Apply the per-hook on_error policy when a plugin raises.
+        def handle_error(bundle_name, basename, on_error, fail_closed, event, error)
+          if fail_closed && event.is_a?(Hash)
+            event[:blocked] = true
+            reason = "guardrail #{basename} (bundle #{bundle_name}) failed: #{error.class}: #{error.message}"
+            event[:guardrail]&.deny!(reason, rule: "guardrail-load", source: "core", decided_by: "core")
+            existing = event[:block_reason].to_s
+            event[:block_reason] = existing.empty? ? reason : "#{existing}; #{reason}"
+          elsif on_error == "log"
+            Log.warn(:hooks, "bundle_hook_failed", echo: "[samagotchi:hooks] #{basename} (bundle #{bundle_name}) failed: #{error.class}: #{error.message}", bundle: bundle_name, hook: basename.to_s, error: error.class.name)
+          end
+          # "skip" (and fail_closed on non-veto events) is silent.
+        end
+      end
+    end
+  end
+end