samagotchi 0.9.0 → 0.10.1

data/lib/samagotchi/config_text_edit.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+require "psych"
+
+module Samagotchi
+  # Sets one section.key in config.yml text, line by line, so the user's
+  # comments and layout stay (YAML.dump would drop them), the way
+  # Bootstrap::ConfigWriter inserts a host. A key already in the block is
+  # replaced on its line (a comment after the old value goes with it), a new
+  # one goes at the end of the block, a missing section at the end of the
+  # file. The result is parsed again and must equal +expected+; when it
+  # doesn't, or the text is something a line edit can't handle (a flow-style
+  # section, anchors, a duplicate section), the whole file is dumped from
+  # +expected+ instead.
+  module ConfigTextEdit
+    DEFAULT_INDENT = 2
+
+    module_function
+
+    # @param text [String, nil] the file's text (nil: no file)
+    # @param section [String] a top-level key ("default")
+    # @param key [String] the key under it; an existing key matches in any case
+    # @param value [String] the value, written as a quoted string
+    # @param expected [Hash] the whole file's data after the change
+    # @return [String] the new text
+    def set(text, section:, key:, value:, expected:)
+      edited = text && edit(text, section, key, value)
+      edited && parse(edited) == expected ? edited : YAML.dump(expected)
+    rescue Psych::Exception
+      YAML.dump(expected)
+    end
+
+    def edit(text, section, key, value)
+      return nil if anchors?(text)
+
+      # A key the lines below can't see (flow style, odd quoting) would end up
+      # written twice, and YAML keeps the last one without a word.
+      original = parse(text)
+      original = {} unless original.is_a?(Hash)
+      section_data = original[section]
+      has_key = section_data.is_a?(Hash) && section_data.keys.any? { |k| k.to_s.downcase == key.downcase }
+
+      eol = text.include?("\r\n") ? "\r\n" : "\n"
+      lines = text.split(/(?<=\n)/)
+      lines[-1] = "#{lines[-1]}#{eol}" if lines.any? && !lines[-1].end_with?("\n")
+      header = /\A#{Regexp.escape(section)}:[ \t]*(#.*)?\z/
+      starts = lines.each_index.select { |i| lines[i].chomp.match?(header) }
+      return nil if starts.length > 1
+
+      return nil if starts.empty? && original.key?(section)
+
+      if starts.empty?
+        lines.concat(["#{section}:#{eol}", "#{" " * DEFAULT_INDENT}#{key}: #{scalar(value)}#{eol}"])
+        return lines.join
+      end
+
+      at = starts.first
+      stop = at + 1
+      stop += 1 while stop < lines.length && inside_block?(lines[stop])
+      children = lines[(at + 1)...stop].reject { |line| line.strip.empty? || comment?(line) }
+      child = children.first ? indent(children.first) : DEFAULT_INDENT
+      new_line = "#{" " * child}#{key}: #{scalar(value)}#{eol}"
+      found = ((at + 1)...stop).find { |i| indent(lines[i]) == child && key_of(lines[i])&.downcase == key.downcase }
+      if found
+        lines[found] = new_line
+      else
+        return nil if has_key
+
+        stop -= 1 while stop > at + 1 && (lines[stop - 1].strip.empty? || (comment?(lines[stop - 1]) && indent(lines[stop - 1]) < child))
+        lines.insert(stop, new_line)
+      end
+      lines.join
+    end
+
+    def key_of(line)
+      line[/\A\s*(["']?)([^"':#\s][^"':#]*?)\1:(?:\s|\z)/, 2]
+    end
+
+    def inside_block?(line)
+      return true if line.strip.empty?
+      return false if line.start_with?("---", "...")
+
+      line.start_with?(" ", "\t") || comment?(line)
+    end
+
+    def comment?(line) = line.lstrip.start_with?("#")
+    def indent(line) = line[/\A */].length
+
+    # JSON's quoting is valid YAML: model ids hold "/" and ":".
+    def scalar(value) = JSON.generate(value.to_s)
+
+    def parse(text) = YAML.safe_load(text, permitted_classes: [], aliases: false)
+
+    def anchors?(text)
+      stack = [Psych.parse_stream(text)]
+      until stack.empty?
+        node = stack.pop
+        return true if node.is_a?(Psych::Nodes::Alias) || (node.respond_to?(:anchor) && node.anchor)
+
+        stack.concat(Array(node.children)) if node.respond_to?(:children)
+      end
+      false
+    end
+  end
+end

data/lib/samagotchi/desktop_command.rb

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "cli/command"
+require_relative "cli/flags"
 require_relative "desktop"
 
 module Samagotchi
   # `chi desktop install|upgrade|uninstall|status`: the native helper that
   # sends selected text to live sessions as a context note (macOS for now).
   class DesktopCommand
+    include CLI::Command
+
     USAGE = <<~TEXT
       Usage: chi desktop <install|upgrade|uninstall|status>
         install [--force] [--login]
@@ -21,6 +25,15 @@ module Samagotchi
 
     SUBCOMMANDS = %w[install upgrade uninstall status].freeze
 
+    # --no-register (hidden) on each; --help is an unknown option after the
+    # subcommand.
+    FLAGS = CLI::Flags.new(args: false) { |f| f.switch "--no-register" }
+    INSTALL_FLAGS = CLI::Flags.new(args: false) do |f|
+      f.switch "--no-register"
+      f.switch "--force"
+      f.switch "--login"
+    end
+
     # @param platform [#call] register: → a Desktop::MacOS-like object
     def initialize(argv, stdout: $stdout, stderr: $stderr, platform: nil, supported: Desktop.supported?)
       @argv = argv.dup
@@ -33,7 +46,7 @@ module Samagotchi
     # @return [Integer] 0 ok, 1 failed, 2 usage
     def run
       sub = @argv.shift
-      if sub.nil? || %w[-h --help help].include?(sub)
+      if sub.nil? || HELP_WORDS.include?(sub)
         @stdout.puts(USAGE)
         return 0
       end
@@ -44,7 +57,9 @@ module Samagotchi
         return 1
       end
 
-      options = parse(sub) or return 2
+      options = parse(sub)
+      return options if options.is_a?(Integer)
+
       # --no-register (hidden): no pbs/lsregister/open/pkill, for installs
       # into temp dirs (HOME=…) that must not touch the real Services.
       helper = @platform.call(register: !options[:no_register])
@@ -56,17 +71,14 @@ module Samagotchi
 
     private
 
-    # @return [Hash, nil] nil after a usage error
+    def command_name = "chi desktop"
+
+    # @return [Hash, Integer] the options, or the usage error's exit status
     def parse(sub)
-      flags = { "--no-register" => :no_register }
-      flags.merge!("--force" => :force, "--login" => :login) if sub == "install"
-      @argv.each_with_object({}) do |arg, options|
-        unless flags.key?(arg)
-          usage_error("unknown option #{arg}")
-          return nil
-        end
-        options[flags[arg]] = true
-      end
+      parsed = (sub == "install" ? INSTALL_FLAGS : FLAGS).parse(@argv)
+      return usage_error(parsed.error.message) if parsed.error
+
+      parsed.options
     end
 
     # The warnings come after a done install: a refused or failed one
@@ -136,11 +148,5 @@ module Samagotchi
     def print_warnings(helper)
       helper.warnings.each { |warning| @stderr.puts("warning: #{warning}") }
     end
-
-    def usage_error(message)
-      @stderr.puts("chi desktop: #{message}")
-      @stderr.puts(USAGE)
-      2
-    end
   end
 end

data/lib/samagotchi/edit_preview.rb

@@ -33,8 +33,8 @@ module Samagotchi
       return before if before.is_a?(Hash)
 
       if call[:name].to_s == "edit"
-        result = Tools::Edit.apply(call[:content], path: path, start_line: call[:start_line],
-                                                   end_line: call[:end_line], read: ->(_) { before })
+        result = Tools::Edit.apply(path: path, old_text: call[:old_text], new_text: call[:new_text],
+                                   start_line: call[:start_line], end_line: call[:end_line], read: ->(_) { before })
         return { error: result.delete_prefix("Error: ") } if result.is_a?(String)
 
         after = result.first

data/lib/samagotchi/engine.rb

@@ -11,7 +11,6 @@ require_relative "context_note"
 require_relative "steer"
 require_relative "turn_note"
 require_relative "model_profile"
-require_relative "thought_stream_splitter"
 require_relative "cancellation_controller"
 require_relative "context_window"
 require_relative "kernel_loop"
@@ -107,7 +106,7 @@ module Samagotchi
       # #profile_resolution decides on first need (see there), so building an
       # Engine makes no network call.
       @given_profile = profile ? ModelProfile.normalize(profile) : nil
-      @model_lookup_names = [@default_model_name]
+      @typed_model_name = @default_model_name
       @profile_resolution = nil
       # Ensure the built-in system bundle is installed (lazy, warn-only).
       # This is the single seam for both TUI and non-TUI (web/worker) paths.
@@ -769,7 +768,7 @@ module Samagotchi
       resolved = ModelProfile.check_host!(ModelProfile.required_model_name(aliased), hosts: @host_registry.entries)
       @effective_model_name = resolved
       bare = bare_model_name(resolved)
-      @model_lookup_names = [model_name, aliased, resolved]
+      @typed_model_name = model_name
       # A profile given to .new was for the starting model.
       @given_profile = nil
       @profile_resolution = nil
@@ -844,7 +843,7 @@ module Samagotchi
       # head system prompt invalidates the cache for the entire conversation
       # (prompt re-evaluated every interval). A tail append keeps the prefix
       # intact — only the new reminder suffix is evaluated. Mirrors the
-      # context-status injection at lib/samagotchi/kernel_loop.rb:447.
+      # context guidance line KernelLoop#run appends (ContextStatus#take_guidance).
       messages << { role: "system", content: reminder_text }
       # Atomically mark all due as fired under one lock and clear the
       # IdleReminders latch so the next interval can be detected.
@@ -1107,29 +1106,15 @@ module Samagotchi
       @guardrail_wiring.state_dir = state_dir
     end
 
-    # The gate's core checks, in order (GuardrailWiring#checks).
-    def guardrail_checks
-      @guardrail_wiring.checks
-    end
-
     # The YAML rules, read again when a file changed (GuardrailWiring#rules).
     # @return [Guardrails::Rules]
     def guardrail_rules
       @guardrail_wiring.rules
     end
 
-    # Installed bundles' guardrails/*.yml (GuardrailWiring#bundle_rules).
-    def bundle_guardrail_rules
-      @guardrail_wiring.bundle_rules
-    end
-
     # @return [Guardrails::LoadFailures]
     attr_reader :guardrail_failures
 
-    def guardrail_protected_paths
-      @guardrail_wiring.protected_paths
-    end
-
     # @return [Guardrails::Approvals]
     def guardrail_approvals
       @guardrail_wiring.approvals
@@ -1165,12 +1150,6 @@ module Samagotchi
       @plugin_failures.message if @guardrail_failures_announced
     end
 
-    # The context the gate sees for a tool call now.
-    # @return [Guardrails::Context]
-    def guardrail_context
-      @guardrail_wiring.context
-    end
-
     # Ask the user to approve a call the gate voted `ask` on
     # (GuardrailWiring#request_approval).
     # @param verdict [Guardrails::Verdict]
@@ -2065,7 +2044,7 @@ module Samagotchi
           (task = current_init_task) ? task.cancelled? : @activity_mutex && active_cancel_controller&.cancelled?
         },
         card: ->(**card) { show_card(**card) },
-        steer: ->(text, source) { steer(text, source: source) },
+        steer: ->(text, label) { steer(text, source: hook_source(label)) },
         stop_turn: ->(reason, label) { hook_stop_turn(reason, label) },
         stop_generation: ->(reason, label) { hook_stop_generation(reason, label) },
         ask_model: lambda { |request, timeout:, max_tokens:, cancel_controller:|
@@ -2108,31 +2087,13 @@ module Samagotchi
     end
     private :ask_side_model
 
-    # config.yml `bundles:`: each bundle's settings by name, for its hooks.
-    # @return [Hash{String => Hash}] {} when absent; a section that isn't a
-    #   mapping warns once and counts as absent
+    # config.yml `bundles:` (ConfigFile.bundle_settings), read once: the
+    # bundle hooks and the plugins both want it.
     def bundle_settings
-      # Read once: the bundle hooks and the plugins both want it.
-      @bundle_settings ||= read_bundle_settings
+      @bundle_settings ||= Samagotchi::ConfigFile.bundle_settings
     end
     private :bundle_settings
 
-    def read_bundle_settings
-      data = Samagotchi::ConfigFile.read_yaml(path: Samagotchi::ConfigFile.global_path)
-      section = data.is_a?(Hash) ? data["bundles"] : nil
-      return {} if section.nil?
-      unless section.is_a?(Hash)
-        Log.warn(:hooks, "bundles_section_invalid", echo: "[samagotchi:hooks] config.yml bundles: must be a mapping of bundle name to settings; ignored")
-        return {}
-      end
-
-      section.each_with_object({}) do |(name, value), acc|
-        acc[name.to_s] = value.is_a?(Hash) ? value : {}
-      end
-    rescue StandardError
-      {}
-    end
-    private :read_bundle_settings
 
     # The session's current model as a recap target: its host's OpenAI API
     # (native llama.cpp hosts serve /v1/chat/completions too), key variable
@@ -2168,44 +2129,29 @@ module Samagotchi
     # only notifying the observer.
     # Wrap a raw kernel stream event and fan it out to the turn sink + observers.
     #
-    # Phase 2 (web-stream-rendering): each :generation_chunk is enriched with two
-    # ADDITIVE fields derived from the raw `content` (which is left untouched —
-    # the TUI thinking spinner, analytics, and Bridge replay all rely on raw):
+    # Each :generation_chunk comes split already, by the loop that streamed it:
+    # besides the raw `content` (left untouched — the TUI thinking spinner,
+    # analytics, and Bridge replay rely on it) it carries
     #   * :text     — visible prose (thinking AND tool_call blocks removed)
     #   * :thinking — thinking-only content
-    # The splitter is profile-aware and resets on each :generation_started so a
-    # turn's multiple generations each start clean.
-    #
-    # Enrichment is profile-scoped:
-    #   * Splitting profiles (explicit think close, e.g. Qwen) ALWAYS emit
-    #     `text`/`thinking` on every :generation_chunk — even when empty — so the
-    #     web client can rely on them and never fall back to raw `content`.
-    #   * Non-splitting profiles (nil think close, e.g. Gemma) leave the event
-    #     unchanged; the web client then falls back to raw `content`, preserving
-    #     today's behavior (no regression).
+    # KernelLoop splits a native stream with a ThoughtStreamSplitter per
+    # generation (every profile, Gemma's thought channel included); the chat
+    # loop gets reasoning apart from the answer. The web routes on those
+    # fields (chunk_router.js).
     #
     # With a :generation_progress hook registered, a Hooks::StreamWatch gets
     # each chunk's thinking and text after the UIs had it.
     def build_stream_event_handler(on_event, cancel_controller: nil)
-      splitter = ThoughtStreamSplitter.for_profile(profile)
-      enrich = profile.thought_close ? :always : :never
       watch = stream_watch(cancel_controller)
       proc do |event|
         progress = nil
         case event[:type]
         when :generation_started
-          splitter = ThoughtStreamSplitter.for_profile(profile)
           watch&.started(event[:iteration])
         when :generation_chunk
-          # The chat loop already splits its stream (reasoning arrives apart
-          # from the answer); only raw native chunks are split here.
-          if event.key?(:text)
-            progress = { thinking: event[:thinking], text: event[:text] }
-          else
-            delta = splitter.feed(event[:content])
-            progress = { thinking: delta[:thinking], text: delta[:text] }
-            event = event.merge(text: delta[:text], thinking: delta[:thinking]) if enrich == :always
-          end
+          # A chunk without the lanes (no loop of ours sends one) counts as text.
+          text = event.key?(:text) ? event[:text] : event[:content]
+          progress = { thinking: event[:thinking].to_s, text: text.to_s }
         end
         # The chat loop asked again without the thinking fields: a notice,
         # not an event of its own.
@@ -2300,11 +2246,10 @@ module Samagotchi
       ModelProfile.resolve(names: model_lookup_names(target), entry: target.entry, client: target.client, bare_model: target.bare_model)
     end
 
-    # The names a models: entry may be under: as typed (maybe an alias), the
-    # part after a host prefix, alias-resolved, bare.
+    # The names a models: entry may be under (HostRegistry#lookup_names):
+    # the model as typed at start or at the last /model, and what it became.
     def model_lookup_names(target)
-      typed = @model_lookup_names.first
-      (@model_lookup_names + [@host_registry.parse_qualified_model(typed).last, target.bare_model]).compact
+      @host_registry.lookup_names(@typed_model_name, resolved: @effective_model_name, target: target)
     end
 
     # Everything that holds a profile follows the resolution: the kernel's

data/lib/samagotchi/events.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # The sets of event types more than one place reads (the Worker, the
+  # Bridge's observers, the TUI, the web), kept here once. The web's own
+  # copies (app.js's stream handlers, turn_events.js's snapshotEvents) are
+  # checked against these by spec/events_drift_spec.rb.
+  module Events
+    # A turn is over: it completed, was canceled, or failed.
+    TURN_END = %i[turn_completed turn_canceled turn_failed].freeze
+    # Turn ends that leave the turn in the conversation: a failed turn's
+    # prompt goes back to the composer instead.
+    TURN_KEPT = %i[turn_completed turn_canceled].freeze
+    # The kinds of a running turn's parts (Bridge::TurnAccumulator), which a
+    # joining UI replays as live events.
+    PART_KINDS = %w[thinking text tool input steer reminder notice].freeze
+    # Types no Engine emits that a UI handles: the Bridge's stream frames
+    # and the web's one synthetic replay event (a prompt merged into the
+    # turn, turn_events.js snapshotEvents).
+    STREAM_FRAMES = %i[snapshot reset stream_closed].freeze
+    SYNTHETIC = %i[merged_input].freeze
+  end
+end

data/lib/samagotchi/guardrail_wiring.rb

@@ -156,13 +156,11 @@ module Samagotchi
     def protected_paths
       @protected ||= begin
         require_relative "memory_bundle/provenance"
-        config = Samagotchi::ConfigFile.read_yaml(path: Samagotchi::ConfigFile.global_path)
-        hooks_dir = config.is_a?(Hash) && config["hooks"].is_a?(Hash) ? config["hooks"]["hooks_dir"] : nil
         Guardrails::ProtectedPaths.new(
           store_dir: File.dirname(@approvals.path),
           bundles_dir: MemoryBundle::Provenance.bundles_dir,
           config_path: Samagotchi::ConfigFile.global_path,
-          hooks_dir: Hooks::Loader.expand_path(hooks_dir || Hooks::Loader.default_hooks_dir)
+          hooks_dir: Hooks::Loader.hooks_dir
         )
       end
     end
@@ -209,8 +207,7 @@ module Samagotchi
     end
 
     def load_rules
-      section = Samagotchi::ConfigFile.read_yaml(path: Samagotchi::ConfigFile.global_path)
-      section = section["guardrails"] if section.is_a?(Hash)
+      section = Samagotchi::ConfigFile.section("guardrails")
       rules = []
       disable = []
       begin

data/lib/samagotchi/hooks/bundle_loader.rb

@@ -30,9 +30,9 @@ module Samagotchi
     # 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).
+    # The +on_error+ policy is applied per hook at fire time (Hooks.wrap):
+    #   - "fail_closed" (on :before_tool_call): a raising guardrail denies
+    #     the tool call (fail-closed).
     #   - "log": warn to stderr and continue.
     #   - "skip" (default): silently continue.
     module BundleLoader
@@ -80,16 +80,14 @@ module Samagotchi
 
             begin
               plugin = instantiate(bundle_name, basename, file, settings: settings)
-              log_failure = Hooks.failure_log_gate(event_sym)
-
-              registry.register_bundle(bundle_name, event_sym, hook_name: basename, priority: priority) do |event|
-                begin
-                  plugin.call(event)
-                rescue Exception => e
-                  # A veto always applies; only the log line is throttled.
-                  handle_error(bundle_name, basename, on_error, fail_closed, event, e) if fail_closed || log_failure.call
-                end
-              end
+              policy = if fail_closed then :deny
+                       elsif on_error == "log" then :log
+                       else :skip
+                       end
+              label = "#{fail_closed ? "guardrail " : ""}#{basename} (bundle #{bundle_name})"
+              handler = Hooks.wrap(label: label, event: event_sym, policy: policy, log: [:hooks, "bundle_hook_failed"],
+                                   fields: { bundle: bundle_name }) { |event| plugin.call(event) }
+              registry.register_bundle(bundle_name, event_sym, hook_name: basename, priority: priority, &handler)
               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)
@@ -119,10 +117,9 @@ module Samagotchi
           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)
+          klass = Hooks.class_for(basename, ns)
           instance = Hooks.build_plugin(klass, settings)
-          raise ArgumentError, "plugin #{class_name} does not respond to #call" unless instance.respond_to?(:call)
+          raise ArgumentError, "plugin #{klass.name.split("::").last} does not respond to #call" unless instance.respond_to?(:call)
           instance
         end
 
@@ -141,20 +138,6 @@ module Samagotchi
             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

data/lib/samagotchi/hooks/loader.rb

@@ -41,6 +41,15 @@ module Samagotchi
           File.join(ConfigFile.config_dir(env: env), "hooks", "")
         end
 
+        # The hooks folder: config.yml's hooks.hooks_dir, or the default,
+        # "~" expanded.
+        # @param data [Hash, nil] the parsed config.yml (read when not given)
+        def hooks_dir(env = ENV, data: ConfigFile.read_yaml(path: ConfigFile.global_path(env: env)))
+          section = data.is_a?(Hash) ? data["hooks"] : nil
+          configured = section.is_a?(Hash) ? section["hooks_dir"] : nil
+          expand_path(configured || default_hooks_dir(env), env)
+        end
+
         # Load hooks from a config hash and return a Registry with registered plugins.
         #
         # @param config_hash [Hash, nil] the hooks section from config.yml
@@ -52,7 +61,7 @@ module Samagotchi
           return Hooks::Registry.new unless config_hash&.key?("hooks")
 
           hooks_config = config_hash["hooks"]
-          hooks_dir = expand_path(hooks_config["hooks_dir"] || default_hooks_dir(env), env)
+          hooks_dir = hooks_dir(env, data: config_hash)
 
           registry = Hooks::Registry.new
           definitions = parse_definitions(hooks_config)
@@ -60,20 +69,10 @@ module Samagotchi
           definitions.each do |defn|
             begin
               plugin = load_plugin(hooks_dir, defn[:path], settings: defn[:settings])
-              log_failure = Hooks.failure_log_gate(defn[:event_type])
               # Persistent: config hooks must fire on every turn, not be wiped
               # by Engine#run_turn's per-turn clear_hooks after turn 1.
-              registry.register_persistent(defn[:event_type].to_sym, label: "#{defn[:path]} (config)") do |event|
-                begin
-                  plugin.call(event)
-                rescue StandardError => e
-                  if defn[:required] && defn[:event_type] == "before_tool_call"
-                    deny_for_raise(event, defn[:path], e)
-                  else
-                    handle_error(defn[:on_error] || "skip", defn[:path], e) if log_failure.call
-                  end
-                end
-              end
+              registry.register_persistent(defn[:event_type].to_sym, label: "#{defn[:path]} (config)",
+                                           &wrapped(plugin, defn))
             rescue ScriptError, StandardError => e
               # ScriptError: a SyntaxError (or LoadError) from `require`.
               Log.error(:hooks, "hook_load_failed", echo: "[samagotchi:hooks] hook #{defn[:path]} failed to load: #{e.class}: #{e.message}", hook: defn[:path].to_s, error: e.class.name)
@@ -130,33 +129,24 @@ module Samagotchi
 
         @plugin_cache[[full_path, settings]] ||= begin
           require full_path
-          class_name = File.basename(path, ".rb").split("_").map(&:capitalize).join
-          klass = Object.const_get(class_name)
+          klass = Hooks.class_for(path)
           instance = Hooks.build_plugin(klass, settings)
           # Validate that the instance responds to #call
-          raise ArgumentError, "Plugin #{class_name} does not respond to #call" unless instance.respond_to?(:call)
+          raise ArgumentError, "Plugin #{klass.name} does not respond to #call" unless instance.respond_to?(:call)
           instance
         end
       end
 
-      # A required before_tool_call hook that raises denies the call.
-      def self.deny_for_raise(event, hook_path, error)
-        return unless event.is_a?(Hash)
-
-        reason = "required hook #{hook_path} raised #{error.class}: #{error.message}"
-        event[:guardrail]&.deny!(reason, rule: "guardrail-load", source: "core", decided_by: "core")
-        event[:blocked] = true
-        event[:block_reason] ||= reason
-      end
-
-      # Handle a hook error based on the on_error config.
-      def self.handle_error(on_error, hook_path, error = nil)
-        case on_error
-        when "log"
-          Log.warn(:hooks, "hook_failed", echo: "[samagotchi:hook] #{error ? "#{error.class}: #{error.message}" : "hook failed"} (#{hook_path})", hook: hook_path.to_s, error: error&.class&.name)
-        when "skip"
-          # Silent — just skip
+      # The plugin's #call under the entry's error policy: a required
+      # before_tool_call hook that raises denies the call; otherwise
+      # on_error: log warns and skip is silent.
+      def self.wrapped(plugin, defn)
+        if defn[:required] && defn[:event_type] == "before_tool_call"
+          policy, label = :deny, "required hook #{defn[:path]}"
+        else
+          policy, label = (defn[:on_error] == "log" ? :log : :skip), "#{defn[:path]} (config)"
         end
+        Hooks.wrap(label: label, event: defn[:event_type].to_sym, policy: policy) { |event| plugin.call(event) }
       end
     end
   end