robot_lab 0.2.1 → 0.2.7

data/examples/common.rb

@@ -7,23 +7,95 @@ ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "prompts")
 
 require_relative "../lib/robot_lab"
 
+# ── Local LLM Configuration ───────────────────────────────────────────────────
+#
+# Every example runs against a LOCAL model served by Ollama. No API keys, no
+# network egress, no per-token cost. Pull the model once before running:
+#
+#   ollama pull qwen3.6
+#
+# Ollama models are not in RubyLLM's model registry, so a `provider:` must be
+# supplied alongside `model:` — that is what makes RubyLLM skip the registry
+# lookup (see Robot#initialize, which sets assume_model_exists when provider is
+# given). Use the `llm_opts` helper below so every robot gets both.
+
 LlmConfig = Data.define(:provider, :model)
 
 LLM = {
-  default:   LlmConfig.new(provider: "openai",    model: "gpt-5.4"),
-  local:     LlmConfig.new(provider: "ollama",    model: "llama3.2"),
-  anthropic: LlmConfig.new(provider: "anthropic", model: "claude-opus-4-7")
+  default: LlmConfig.new(provider: "ollama", model: "qwen3.6:latest"),
+  small:   LlmConfig.new(provider: "ollama", model: "qwen2.5:7b"),
+  large:   LlmConfig.new(provider: "ollama", model: "llama3.3:latest")
 }.freeze
 
-RubyLLM.configure do |c|
-  c.logger        = Logger.new(File::NULL)
-  c.default_model = LLM[:default].model
-end
+OLLAMA_API_BASE = ENV.fetch("OLLAMA_API_BASE", "http://localhost:11434/v1")
 
+# ORDER MATTERS. The first touch of RobotLab.config runs Config#after_load,
+# which calls RubyLLM.configure itself and would clobber anything set before
+# it. So configure RobotLab first, then RubyLLM — the later block wins.
 RobotLab.configure do |c|
   c.logger = Logger.new(File::NULL)
 end
 
+RubyLLM.configure do |c|
+  c.logger          = Logger.new(File::NULL)
+  c.default_model   = LLM[:default].model
+  c.ollama_api_base = OLLAMA_API_BASE
+
+  # A large local model on consumer hardware is far slower than a hosted API,
+  # and robot_lab's bundled 120s default is comfortably exceeded by a long
+  # answer from a 20B+ model — which surfaces mid-run as Net::ReadTimeout.
+  #
+  # Integer(), not the raw env string: this value reaches Net::HTTP directly,
+  # and a String raises "can't convert String into time interval". That is
+  # also why the ROBOT_LAB_RUBY_LLM__REQUEST_TIMEOUT env var is the wrong
+  # lever here — env values arrive as strings.
+  c.request_timeout = Integer(ENV.fetch("LLM_REQUEST_TIMEOUT", "900"))
+  c.max_retries     = 1
+end
+
+# Which LLM entry an unqualified llm_opts resolves to. Lets you run any
+# example against a faster model without editing it — worth knowing for the
+# multi-robot demos (14, 15, 16), which are 30+ sequential LLM calls and take
+# over half an hour on a 20B+ model:
+#
+#   LLM_PROFILE=small bundle exec ruby examples/14_rusty_circuit/open_mic.rb
+LLM_PROFILE = ENV.fetch("LLM_PROFILE", "default").to_sym
+
+unless LLM.key?(LLM_PROFILE)
+  abort "Unknown LLM_PROFILE #{LLM_PROFILE.inspect}. Choose one of: #{LLM.keys.join(', ')}"
+end
+
+# Provider + model keyword pair for RobotLab.build / Robot.new.
+#
+# Both are required for a local Ollama model. Splat it into any robot
+# constructor:
+#
+#   RobotLab.build(name: "helper", **llm_opts)          # honors LLM_PROFILE
+#   RobotLab.build(name: "cheap",  **llm_opts(:small))  # pinned regardless
+#
+# @param key [Symbol, nil] which entry of LLM to use; defaults to LLM_PROFILE
+# @return [Hash] { provider:, model: }
+def llm_opts(key = nil)
+  cfg = LLM.fetch(key || LLM_PROFILE)
+  { provider: cfg.provider, model: cfg.model }
+end
+
+# Fail fast with an actionable message when Ollama isn't reachable, instead of
+# letting every example die inside an HTTP adapter.
+def require_ollama!
+  require "net/http"
+  uri = URI(OLLAMA_API_BASE.sub(%r{/v1/?$}, "") + "/api/tags")
+  Net::HTTP.start(uri.host, uri.port, open_timeout: 2, read_timeout: 2) { |h| h.get(uri.request_uri) }
+rescue StandardError => e
+  abort <<~ERROR
+    Cannot reach Ollama at #{OLLAMA_API_BASE} (#{e.class}).
+
+    Start it and pull the model used by the examples:
+      ollama serve
+      ollama pull #{LLM[:default].model.sub(/:latest\z/, "")}
+  ERROR
+end
+
 # ── Example Output Helpers ─────────────────────────────────────────────────────
 
 module ExOut

data/examples/xyzzy.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+# xyzzy.rb — single-file RobotLab hook extension demo
+#
+# Demonstrates the Hook handler class pattern: implement class methods for
+# every hook under a dedicated namespace and log each callback with its
+# context snapshot. Useful as a live trace of the full hook pipeline during
+# development.
+#
+# Fully Ractor-safe: no class-level mutable state. LOG_PATH is a frozen
+# string constant (shareable); each call opens its own file handle.
+#
+# stdout : one tagline per hook call  →  [xyzzy] HH:MM:SS.mmm hook_name
+# logfile: full context snapshot written to LOG_PATH via PP.pp
+#
+# The log destination is read from XYZZY_LOG_PATH at load time and frozen
+# into a constant. Set it BEFORE requiring this file to redirect the log;
+# there is deliberately no writer method, so the constant stays shareable.
+#
+# Usage (from any example that requires common):
+#   ENV["XYZZY_LOG_PATH"] = "/tmp/xyzzy.log"   # optional, must precede require
+#   require_relative "xyzzy"
+
+require "pp"
+require "fileutils"
+
+module RobotLab
+  class Xyzzy < Hook
+    self.namespace = :xyzzy
+
+    LOG_PATH = File.expand_path(
+      ENV.fetch("XYZZY_LOG_PATH", "~/.robot_lab/xyzzy_hooks.log")
+    ).freeze
+    FileUtils.mkdir_p(File.dirname(LOG_PATH))
+
+    class << self
+      def before_run(ctx)               = log_hook(:before_run, ctx)
+      def after_run(ctx)                = log_hook(:after_run, ctx)
+      def on_error(ctx)                 = log_hook(:on_error, ctx)
+      def before_llm_generation(ctx)    = log_hook(:before_llm_generation, ctx)
+      def after_llm_generation(ctx)     = log_hook(:after_llm_generation, ctx)
+      def before_tool_call(ctx)         = log_hook(:before_tool_call, ctx)
+      def after_tool_call(ctx)          = log_hook(:after_tool_call, ctx)
+      def before_network_run(ctx)       = log_hook(:before_network_run, ctx)
+      def after_network_run(ctx)        = log_hook(:after_network_run, ctx)
+      def before_task(ctx)              = log_hook(:before_task, ctx)
+      def after_task(ctx)               = log_hook(:after_task, ctx)
+
+      def around_run(ctx, &block)
+        log_hook(:around_run, ctx)
+        block.call
+      end
+
+      def around_llm_generation(ctx, &block)
+        log_hook(:around_llm_generation, ctx)
+        block.call
+      end
+
+      def around_tool_call(ctx, &block)
+        log_hook(:around_tool_call, ctx)
+        block.call
+      end
+
+      def around_network_run(ctx, &block)
+        log_hook(:around_network_run, ctx)
+        block.call
+      end
+
+      def around_task(ctx, &block)
+        log_hook(:around_task, ctx)
+        block.call
+      end
+
+      private
+
+      def log_hook(hook_name, ctx)
+        ts       = Time.now.strftime('%H:%M:%S.%3N')
+        snapshot = context_snapshot(ctx)
+        $stdout.puts "  [xyzzy] #{ts} #{hook_name}"
+        File.open(LOG_PATH, "a") { |f| f.puts "#{ts} #{hook_name} | #{PP.pp(snapshot, +"").chomp}" }
+      end
+
+      def context_snapshot(ctx)
+        {
+          robot:   ctx.respond_to?(:robot)   ? ctx.robot&.name    : nil,
+          request: ctx.respond_to?(:request) ? ctx.request        : nil,
+          network: ctx.respond_to?(:network) ? ctx.network&.name  : nil,
+          task:    ctx.respond_to?(:task)    ? ctx.task           : nil,
+          error:   ctx.respond_to?(:error)   ? ctx.error&.message : nil
+        }.compact
+      end
+    end
+  end
+end
+
+RobotLab.register_extension(:xyzzy, RobotLab::Xyzzy) if RobotLab.respond_to?(:register_extension)
+RobotLab.on(RobotLab::Xyzzy)

data/lib/robot_lab/agent_skill.rb

@@ -8,7 +8,7 @@ module RobotLab
   # A skill is a directory containing SKILL.md with required front matter
   # fields (name, description) and optional scripts/, references/, assets/.
   class AgentSkill
-    attr_reader :name, :description, :path
+    attr_reader :name, :description, :path, :capabilities
 
     # @param skill_md_path [String, Pathname] path to the SKILL.md file
     # @raise [ConfigurationError] if name or description is missing
@@ -17,8 +17,9 @@ module RobotLab
       content = File.read(skill_md_path)
       front_matter, @_body = parse_skill_md(content)
 
-      @name        = front_matter["name"]
-      @description = front_matter["description"]
+      @name         = front_matter["name"]
+      @description  = front_matter["description"]
+      @capabilities = Capabilities.from_front_matter(front_matter)
 
       raise ConfigurationError, "SKILL.md at #{skill_md_path} missing 'name'"        if @name.to_s.strip.empty?
       raise ConfigurationError, "SKILL.md at #{skill_md_path} missing 'description'" if @description.to_s.strip.empty?
@@ -41,7 +42,7 @@ module RobotLab
     # Non-executable scripts are skipped with a warning.
     def script_tools
       @script_tools ||= scripts.filter_map do |script_path|
-        ScriptTool.from_path(script_path)
+        ScriptTool.from_path(script_path, capabilities: @capabilities, skill_dir: @path.to_s)
       end
     end
 

data/lib/robot_lab/budget/ledger.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Budget
+    # Thread-safe reserve/reconcile ledger for tracking consumption against
+    # per-dimension limits (e.g. :tokens, :cost).
+    #
+    # Call +reserve!+ before doing billable work, so an already-exhausted
+    # budget is caught before the work is attempted rather than after.
+    # Once the work completes, +reconcile!+ replaces the reservation with
+    # the actual amount consumed (which may be more or less than what was
+    # reserved — LLM call sizes aren't known in advance). +release!+ drops
+    # an unused reservation without recording any consumption.
+    #
+    # A dimension with no configured limit is treated as unlimited:
+    # +reserve!+ never raises for it and +remaining+ returns
+    # +Float::INFINITY+.
+    #
+    # @example
+    #   ledger = RobotLab::Budget::Ledger.new(limits: { tokens: 10_000, cost: 0.50 })
+    #   ledger.reserve!(:tokens, ledger.remaining(:tokens))
+    #   # ... do the billable work ...
+    #   ledger.reconcile!(:tokens, ledger.remaining(:tokens), actual_tokens_used)
+    class Ledger
+      # @!attribute [r] limits
+      #   @return [Hash{Symbol=>Numeric}] per-dimension ceilings
+      # @!attribute [r] consumed
+      #   @return [Hash{Symbol=>Numeric}] actual amount consumed per dimension so far
+      attr_reader :limits, :consumed
+
+      # @param limits [Hash{Symbol=>Numeric}] per-dimension ceilings; a dimension absent
+      #   from this hash is treated as unlimited
+      # @param consumed [Hash{Symbol=>Numeric}] starting consumption (e.g. restored from a prior run)
+      def initialize(limits: {}, consumed: {})
+        @mutex = Mutex.new
+        @limits = limits
+        @consumed = Hash.new(0).merge(consumed)
+        @reserved = Hash.new(0)
+      end
+
+      # Reserves +amount+ against +key+'s remaining budget.
+      #
+      # A no-op (never raises) when +key+ has no configured limit.
+      #
+      # @param key [Symbol] the budget dimension
+      # @param amount [Numeric] the amount to reserve
+      # @raise [RobotLab::BudgetExceeded] if the reservation would exceed the limit
+      # @return [void]
+      def reserve!(key, amount)
+        @mutex.synchronize do
+          limit = @limits[key]
+          next unless limit
+
+          committed = @consumed[key] + @reserved[key]
+          if committed + amount > limit
+            raise BudgetExceeded, "budget exceeded for #{key}: #{committed + amount} > #{limit}"
+          end
+
+          @reserved[key] += amount
+        end
+      end
+
+      # Replaces a prior reservation with the actual amount consumed.
+      #
+      # @param key [Symbol] the budget dimension
+      # @param reserved_amount [Numeric] the amount previously passed to +reserve!+
+      # @param actual_amount [Numeric] the amount actually consumed
+      # @return [void]
+      def reconcile!(key, reserved_amount, actual_amount)
+        @mutex.synchronize do
+          @reserved[key] = [0, @reserved[key] - reserved_amount].max
+          @consumed[key] += actual_amount
+        end
+      end
+
+      # Drops a reservation without recording any consumption (e.g. the
+      # reserved work was skipped).
+      #
+      # @param key [Symbol] the budget dimension
+      # @param amount [Numeric] the amount previously passed to +reserve!+
+      # @return [void]
+      def release!(key, amount)
+        @mutex.synchronize { @reserved[key] = [0, @reserved[key] - amount].max }
+      end
+
+      # @param key [Symbol] the budget dimension
+      # @return [Numeric] remaining budget for +key+, floored at 0; +Float::INFINITY+ when unlimited
+      def remaining(key)
+        @mutex.synchronize do
+          limit = @limits[key]
+          next Float::INFINITY unless limit
+
+          [limit - @consumed[key] - @reserved[key], 0].max
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/capabilities.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Declared execution capabilities for a skill script: which paths it may read
+  # and write, whether it may use the network, how long it may run, and how much
+  # it is trusted.
+  #
+  # A skill declares what it *wants* in SKILL.md front matter; the global config
+  # declares the *ceiling* of what any skill may have. The effective grant is the
+  # intersection of the two (see {#intersect}) — anything the skill asks for that
+  # the ceiling does not permit is dropped.
+  class Capabilities
+    DEFAULT_TIMEOUT = 60
+    TRUST_LEVELS    = %w[core external].freeze
+
+    attr_reader :fs_read, :fs_write, :network, :timeout, :trust
+
+    def initialize(fs_read: [], fs_write: [], network: false, timeout: DEFAULT_TIMEOUT, trust: "external")
+      @fs_read  = Array(fs_read).map(&:to_s)
+      @fs_write = Array(fs_write).map(&:to_s)
+      @network  = network ? true : false
+      @timeout  = timeout.to_i.positive? ? timeout.to_i : DEFAULT_TIMEOUT
+      @trust    = TRUST_LEVELS.include?(trust.to_s) ? trust.to_s : "external"
+    end
+
+    # Build from a SKILL.md front matter hash (string or symbol keys).
+    def self.from_front_matter(front_matter)
+      fm = front_matter || {}
+      new(
+        fs_read:  fm_value(fm, :fs_read, []),
+        fs_write: fm_value(fm, :fs_write, []),
+        network:  fm_value(fm, :network, false),
+        timeout:  fm_value(fm, :timeout, DEFAULT_TIMEOUT),
+        trust:    fm_value(fm, :trust, "external")
+      )
+    end
+
+    # Look up a front-matter key tolerating string or symbol keys.
+    def self.fm_value(front_matter, key, default)
+      value = front_matter[key.to_s]
+      value = front_matter[key] if value.nil?
+      value.nil? ? default : value
+    end
+
+    # Build the ceiling from the global config's sandbox section.
+    def self.ceiling(config = RobotLab.config)
+      section = config.respond_to?(:sandbox) ? config.sandbox : nil
+      return new(fs_read: ["."]) unless section
+
+      new(
+        fs_read:  section.fs_read  || ["."],
+        fs_write: section.fs_write || [],
+        network:  section.network  || false,
+        timeout:  section.timeout  || DEFAULT_TIMEOUT
+      )
+    end
+
+    def core? = trust == "core"
+
+    # Effective grant = this (declared) ∩ ceiling. Paths survive only when
+    # inside a ceiling root; network requires both; timeout is the smaller;
+    # trust stays as declared.
+    def intersect(ceiling)
+      self.class.new(
+        fs_read:  clamp_paths(@fs_read, ceiling.fs_read),
+        fs_write: clamp_paths(@fs_write, ceiling.fs_write),
+        network:  @network && ceiling.network,
+        timeout:  [@timeout, ceiling.timeout].min,
+        trust:    @trust
+      )
+    end
+
+    private
+
+    def clamp_paths(requested, allowed)
+      roots = expand(allowed)
+      expand(requested).select { |p| roots.any? { |r| p == r || p.start_with?("#{r}/") } }
+    end
+
+    def expand(paths)
+      Array(paths).map { |p| File.expand_path(p.to_s) }
+    end
+  end
+end

data/lib/robot_lab/config/defaults.yml

@@ -25,6 +25,16 @@ defaults:
   mcp: :none
   tools: :none
 
+  # Skill-script sandboxing (opt-in). When enabled, skill scripts run confined
+  # to the effective grant (their SKILL.md declaration ∩ this ceiling). macOS
+  # uses sandbox-exec; other platforms run unconfined with a warning.
+  sandbox:
+    enabled: false        # opt-in; off = scripts run exactly as before
+    fs_read: ["."]        # ceiling: paths any skill may read (relative to cwd)
+    fs_write: []          # ceiling: paths any skill may write
+    network: false        # ceiling: may any skill use the network
+    timeout: 60           # ceiling: max seconds a skill script may run
+
   # Chat Configuration (passed to RubyLLM.chat)
   # These are global defaults that can be overridden per-robot or per-run
   chat:

data/lib/robot_lab/config.rb

@@ -8,7 +8,8 @@ module RobotLab
   # Provides:
   # - Nested configuration with a dedicated `ruby_llm:` section
   # - Environment-specific settings (development, test, production)
-  # - XDG config file loading (~/.config/robot_lab/config.yml)
+  # - XDG config file loading (~/.config/robot_lab/robot_lab.yml — the filename
+  #   repeats the `config_name`; `config.yml` is never read)
   # - Environment variable overrides (ROBOT_LAB_*)
   # - Automatic RubyLLM configuration application
   #
@@ -21,10 +22,14 @@ module RobotLab
   #   # ROBOT_LAB_RUBY_LLM__MODEL=gpt-4
   #   # ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY=sk-ant-...
   #
-  # @example User config file (~/.config/robot_lab/config.yml)
-  #   defaults:
-  #     ruby_llm:
-  #       anthropic_api_key: <%= ENV['ANTHROPIC_API_KEY'] %>
+  # @example User config file (~/.config/robot_lab/robot_lab.yml)
+  #   # Flat keys, or a section named for the current environment. A `defaults:`
+  #   # wrapper is IGNORED here — it applies only to the gem's bundled
+  #   # defaults.yml. This file is NOT run through ERB, so keep secrets in
+  #   # environment variables or in ./config/robot_lab.yml (which is).
+  #   ruby_llm:
+  #     model: claude-sonnet-4
+  #     request_timeout: 120
   #
   class Config < MywayConfig::Base
     config_name :robot_lab
@@ -153,16 +158,16 @@ module RobotLab
     def resolved_template_path
       return template_path if template_path
 
-      if defined?(Rails) && Rails.root
-        Rails.root.join('app', 'prompts').to_s
+      if defined?(::Rails) && ::Rails.root
+        ::Rails.root.join('app', 'prompts').to_s
       else
         'prompts'
       end
     end
 
     def default_logger
-      if defined?(Rails) && Rails.respond_to?(:logger)
-        Rails.logger
+      if defined?(::Rails) && ::Rails.respond_to?(:logger)
+        ::Rails.logger
       else
         require 'logger'
         Logger.new($stdout, level: Logger::INFO)

data/lib/robot_lab/error.rb

@@ -26,9 +26,19 @@ module RobotLab
 
   # Raised when MCP communication fails.
   #
+  # @param retryable [Boolean, nil] opt-in hint for RobotLab::Errors.retryable? —
+  #   set true at the raise site for transient failures (connection drop, timeout)
+  #
   # @example
-  #   raise MCPError, "Connection to MCP server refused"
-  class MCPError < Error; end
+  #   raise MCPError.new("Connection to MCP server refused", retryable: true)
+  class MCPError < Error
+    attr_reader :retryable
+
+    def initialize(message = nil, retryable: nil)
+      @retryable = retryable
+      super(message)
+    end
+  end
 
   # Raised when message bus communication fails.
   #
@@ -36,6 +46,16 @@ module RobotLab
   #   raise BusError, "No bus configured on this robot"
   class BusError < Error; end
 
+  # Raised when a Robot's configured token or cost budget is already
+  # exhausted before an LLM call is attempted (see RobotLab::Budget::Ledger).
+  # Distinct from InferenceError, which covers a call that completed but
+  # pushed cumulative usage over budget — BudgetExceeded means the call
+  # was refused outright.
+  #
+  # @example
+  #   raise BudgetExceeded, "budget exceeded for cost: 0.62 > 0.5"
+  class BudgetExceeded < Error; end
+
   # Raised when a robot's tool call loop exceeds the configured limit.
   #
   # @example
@@ -57,7 +77,17 @@ module RobotLab
 
   # Raised when a tool fails during execution, including inside a Ractor worker.
   #
+  # @param retryable [Boolean, nil] opt-in hint for RobotLab::Errors.retryable? —
+  #   set true at the raise site for transient failures worth retrying
+  #
   # @example
-  #   raise ToolError, "Tool 'MyTool' failed: division by zero"
-  class ToolError < Error; end
+  #   raise ToolError.new("Tool 'MyTool' failed: division by zero")
+  class ToolError < Error
+    attr_reader :retryable
+
+    def initialize(message = nil, retryable: nil)
+      @retryable = retryable
+      super(message)
+    end
+  end
 end

data/lib/robot_lab/errors.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Classification surface for "should this error be retried?" — so hosts
+  # (ActiveJob retry_on lists, robot_lab-to's takeover loop, custom retry
+  # wrappers) don't reimplement the same case statement against RobotLab's
+  # error hierarchy.
+  #
+  # - +InferenceError+ (transient LLM/API failures) is always retryable,
+  #   except its more specific subclass +ToolLoopError+ (a circuit breaker
+  #   tripped by a repeating tool-call pattern — retrying immediately would
+  #   just re-trigger the same loop).
+  # - +MCPError+ and +ToolError+ are opt-in: retryable only when raised
+  #   with +retryable: true+, since some instances are transient (a
+  #   connection drop, a timeout) and some are not (an explicit rejection
+  #   from the server or tool).
+  # - Everything else (+ConfigurationError+, +ToolNotFoundError+,
+  #   +DependencyError+, +RactorBoundaryError+, +BusError+, and any
+  #   non-RobotLab error) is never retryable.
+  module Errors
+    # @param error [Exception, nil]
+    # @return [Boolean] true when the host should retry the operation that raised +error+
+    def self.retryable?(error)
+      return false if error.nil? || error.is_a?(RobotLab::ToolLoopError)
+
+      case error
+      when RobotLab::MCPError, RobotLab::ToolError
+        error.respond_to?(:retryable) && error.retryable == true
+      when RobotLab::InferenceError
+        true
+      else
+        false
+      end
+    end
+
+    # Always-retryable error classes, for explicit ActiveJob-style
+    # +retry_on+ allow-lists. Excludes +MCPError+/+ToolError+ because
+    # their retryability is per-raise (via +retryable:+), not per-class.
+    #
+    # @return [Array<Class>]
+    def self.retryable_classes
+      [RobotLab::InferenceError].freeze
+    end
+  end
+end

data/lib/robot_lab/hook.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Base class for hook handlers.
+  #
+  # Subclasses implement class methods for each hook they handle.
+  # Unimplemented hooks are silently skipped; around hooks passthrough
+  # automatically so the chain never breaks.
+  #
+  # The namespace defaults to the snake_case form of the last segment of the
+  # class name (e.g. TokenLogger -> :token_logger). Override with
+  # `self.namespace = :custom` when needed.
+  #
+  # @example
+  #   class AuditHook < RobotLab::Hook
+  #     def self.before_run(ctx)
+  #       ctx.local.started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  #     end
+  #
+  #     def self.after_run(ctx)
+  #       elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - ctx.local.started_at
+  #       puts "[#{ctx.robot.name}] #{(elapsed * 1000).round(1)}ms"
+  #     end
+  #
+  #     def self.on_error(ctx)
+  #       puts "[#{ctx.robot.name}] ERROR: #{ctx.error.message}"
+  #     end
+  #   end
+  #
+  #   RobotLab.on(AuditHook)
+  #   robot.on(AuditHook)
+  #   network.on(AuditHook)
+  #
+  class Hook
+    @namespace = nil
+
+    class << self
+      attr_writer :namespace
+
+      # Returns the hook's namespace symbol, derived from the class name by
+      # default. Returns nil for the base Hook class itself.
+      #
+      # @return [Symbol, nil]
+      def namespace
+        return @namespace if @namespace
+        return nil if self == Hook
+
+        name.split('::').last
+            .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .downcase
+            .to_sym
+      end
+
+      # Dispatch a single hook to this handler.
+      #
+      # If the handler implements the method it is called. For around hooks that
+      # are not implemented the block is called directly (passthrough). Non-around
+      # hooks that are not implemented are silent no-ops.
+      #
+      # @param hook_name [Symbol] e.g. :before_run, :around_tool_call
+      # @param context [HookContext] the hook context object
+      # @yield for around hooks — the next link in the chain
+      def call(hook_name, context, &block)
+        if singleton_class.public_method_defined?(hook_name)
+          block ? public_send(hook_name, context, &block)
+                : public_send(hook_name, context)
+        elsif block
+          block.call
+        end
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@namespace, nil)
+      end
+    end
+  end
+end