robot_lab-ractor 0.2.1 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25de3bcf1d2904408d989619f14f2204b556d5cc7412683793d1e108c986192f
-  data.tar.gz: 412b11c1532be8674b9ec1767471d42909dd20e98cf2ca6661f143dbeccbe68f
+  metadata.gz: 7df9c3ab4660c44f064946a5a90f071df1ad03baa1b4cac8c3259156a35be70b
+  data.tar.gz: 0fb20202b60255f45be1b423d5fa5870730cfd4fbf3dbaee1ec601eb72a87f59
 SHA512:
-  metadata.gz: ce3e69d19db119d2f28e0c4b557826271f09169d8f5adaf811787f2ffba9bd637ace4aad2f5e8f525781d5c59c6e995bd851f26bac222a5e695d3ac7a6e08c1d
-  data.tar.gz: b3a6f73c02fd8e006dc71c1cea906adb1d47051c5c584d30b45ba374f9c43a036f0782a3f60a72fde5463cd78503cc7b0292a77ded5858b52d5ef9edbc693530
+  metadata.gz: '0418c60678b46d1c7b9e3a625f8e2c3b1ebf789a2f526daea6f05d5c8a9046a11e54217bea1dd8fd15a50bae6115ea634907e002adc96d7d06f736c626f05d20'
+  data.tar.gz: c8800eee270d7987d17658a97c7dce82074ce8db09b67d7a598d92c1e29b15138d07e242f4a5de86fe0a812cadbb10c0ce02736da6d80f60cea36f24b22b4779

data/.envrc

@@ -1 +1,3 @@
+source_up
 export RR=`pwd`
+export BUNDLE_GEMFILE=Gemfile

data/.loki

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+# robot_lab-ractor — CPU parallelism via Ractors.
+
+import_up "repo_dev.loki"
+
+class Tasks
+  @@gem_name ||= "robot_lab-ractor".freeze
+
+  header "robot_lab-ractor v#{gem_version} — CPU-parallel robot execution"
+end

data/.quality/reek_baseline.txt

@@ -0,0 +1,3 @@
+1	lib/robot_lab/ractor_boundary.rb
+3	lib/robot_lab/ractor_network_scheduler.rb
+1	lib/robot_lab/ractor_worker_pool.rb

data/.rubocop.yml

@@ -1,173 +1 @@
-AllCops:
-  NewCops: enable
-  SuggestExtensions: false
-  TargetRubyVersion: 4.0
-  Exclude:
-    - 'examples/**/*'
-    - 'vendor/**/*'
-    - 'dead_code/**/*'
-
-# ── Style: disabled cops ───────────────────────────────────────────────────
-Style/StringLiterals:
-  Enabled: false
-
-Style/StringLiteralsInInterpolation:
-  Enabled: false
-
-Style/Documentation:
-  Enabled: false
-
-# Ruby 4.0 freezes string literals by default
-Style/FrozenStringLiteralComment:
-  Enabled: false
-
-Style/IfUnlessModifier:
-  Enabled: false
-
-Style/RescueModifier:
-  Enabled: false
-
-Style/TrivialAccessors:
-  Enabled: false
-
-Style/MultilineTernaryOperator:
-  Enabled: false
-
-Style/SafeNavigation:
-  Enabled: false
-
-Style/EmptyClassDefinition:
-  Enabled: false
-
-Style/ClassAndModuleChildren:
-  Enabled: false
-
-Style/RescueStandardError:
-  Enabled: false
-
-Style/OneClassPerFile:
-  Enabled: false
-
-# Both % and format/sprintf are acceptable
-Style/FormatString:
-  Enabled: false
-
-# String concatenation and interpolation are both acceptable
-Style/StringConcatenation:
-  Enabled: false
-
-# ── Layout ─────────────────────────────────────────────────────────────────
-Layout/LineLength:
-  Max: 140
-
-Layout/ExtraSpacing:
-  Enabled: false
-
-Layout/HashAlignment:
-  Enabled: false
-
-Layout/FirstHashElementIndentation:
-  Enabled: false
-
-Layout/EmptyLineAfterGuardClause:
-  Enabled: false
-
-# ── Naming ─────────────────────────────────────────────────────────────────
-# Single-char params (c, e, n) are acceptable throughout
-Naming/MethodParameterName:
-  Enabled: false
-
-Naming/VariableNumber:
-  Exclude:
-    - 'test/**/*'
-
-Naming/RescuedExceptionsVariableName:
-  Enabled: false
-
-# set_results and similar explicit setters are clear and conventional
-Naming/AccessorMethodName:
-  Enabled: false
-
-
-# has_tool_calls? and similar are clear and conventional
-Naming/PredicatePrefix:
-  Enabled: false
-
-# Test helper methods don't need to follow predicate naming rules
-Naming/PredicateMethod:
-  Exclude:
-    - 'test/**/*'
-
-# ── Lint: relax noisy cops on intentional patterns ─────────────────────────
-# Library and framework methods commonly accept args for API/documentation purposes
-Lint/UnusedMethodArgument:
-  Enabled: false
-
-
-Lint/EmptyBlock:
-  Exclude:
-    - 'test/**/*'
-
-Lint/ConstantDefinitionInBlock:
-  Exclude:
-    - 'Rakefile'
-    - 'test/**/*'
-
-# ── Gemspec ────────────────────────────────────────────────────────────────
-Gemspec/DevelopmentDependencies:
-  EnforcedStyle: Gemfile
-
-Gemspec/RequiredRubyVersion:
-  Enabled: false
-
-Gemspec/OrderedDependencies:
-  Enabled: false
-
-# ── Metrics ────────────────────────────────────────────────────────────────
-# Framework-level code (routers, parsers, orchestrators) is inherently complex.
-# Flog is the primary complexity gate — these RuboCop thresholds catch only
-# egregious outliers without false-positiving every dispatch method.
-
-Metrics/MethodLength:
-  Max: 35
-  CountAsOne:
-    - heredoc
-    - array
-    - hash
-  Exclude:
-    - 'test/**/*'
-
-Metrics/AbcSize:
-  Max: 40
-  Exclude:
-    - 'test/**/*'
-
-Metrics/ClassLength:
-  Max: 600
-  Exclude:
-    - 'test/**/*'
-
-Metrics/ModuleLength:
-  Max: 200
-  Exclude:
-    - 'test/**/*'
-
-Metrics/CyclomaticComplexity:
-  Max: 20
-  Exclude:
-    - 'test/**/*'
-
-Metrics/PerceivedComplexity:
-  Max: 20
-  Exclude:
-    - 'test/**/*'
-
-# Long method signatures with keyword args are a Ruby framework idiom
-Metrics/ParameterLists:
-  Enabled: false
-
-Metrics/BlockLength:
-  Exclude:
-    - 'Rakefile'
-    - '*.gemspec'
-    - 'test/**/*'
+inherit_from: ../.rubocop-base.yml

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+### Added
+- `.loki` Asgard task file: `test`, `rubocop`, `rubocop_fix`, `flog`, `flay`, `quality`, `build`, `install`, `release`, and `console` tasks via the Asgard task runner
+- `flay_check` Rake task: structural code duplication gate (mass threshold 50); integrated into the `quality` Rake task
+- `flay` and `minitest-reporters` gems added to development dependencies
+- `test_output.txt`, `flay_output.txt`, `flog_output.txt`, and `rubocop_output.txt` added to `.gitignore`
+
+### Changed
+- `test/test_helper.rb`: test output redirected to `test_output.txt` via `$stdout` reassignment; `TerminalSummaryReporter` prints a single PASS/FAIL summary line to the terminal
+- `Rakefile`: `rubocop` and `rubocop_fix` tasks removed (now owned by Asgard); `flay_check` integrated into the `quality` gate
+
 ## [0.2.1] - 2026-05-19
 
 ### Added

data/CLAUDE.md

@@ -0,0 +1,71 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Gem Does
+
+`robot_lab-ractor` enables CPU-parallel execution in RobotLab via Ruby Ractors. It provides a worker pool for CPU-bound tools and a dependency-aware network scheduler for running robot pipelines across Ractor workers.
+
+## Commands
+
+```bash
+bundle exec rake test        # Run full test suite
+ruby -Ilib:test test/<file>  # Run a single test file
+```
+
+## CRITICAL: Never define `module RobotLab::Ractor`
+
+`lib/robot_lab/ractor.rb` intentionally does **not** open `module RobotLab::Ractor`. Defining that module would shadow Ruby's built-in `Ractor` class for all code inside the `RobotLab` namespace, breaking `Ractor.new`, `Ractor.make_shareable`, etc. throughout the codebase. The version constant lives in `RobotLab::RactorPool::VERSION` to avoid this clash.
+
+## Architecture
+
+**`RactorWorkerPool`** (`ractor_worker_pool.rb`) — Pool of Ractor workers for CPU-bound, Ractor-safe tools. Submit a job from any thread; the result is returned synchronously via a per-job `RactorQueue`.
+
+```ruby
+pool = RactorWorkerPool.new(size: 4)      # :auto = Etc.nprocessors
+result = pool.submit("MyTool", { arg: "value" })
+pool.shutdown
+```
+
+Accessed globally via `RobotLab.ractor_pool` / `RobotLab.shutdown_ractor_pool`.
+
+**`RactorNetworkScheduler`** (`ractor_network_scheduler.rb`) — Schedules frozen `RobotSpec` payloads across Ractor workers in dependency order. Entry-point robots (`:none` deps) dispatch immediately; dependent robots dispatch once all named deps complete.
+
+```ruby
+scheduler = RactorNetworkScheduler.new(memory: shared_memory)
+results = scheduler.run_pipeline([
+  { spec: analyst_spec, depends_on: :none },
+  { spec: writer_spec,  depends_on: ["analyst"] }
+], message: "Analyse this")
+scheduler.shutdown
+```
+
+**`RactorBoundary`** (`ractor_boundary.rb`) — Utility for crossing Ractor boundaries. `freeze_deep(obj)` recursively freezes Hash/Array structures and calls `Ractor.make_shareable`. Raises `RactorBoundaryError` if the value cannot be made shareable (e.g. a live IO or Proc).
+
+**`RactorMemoryProxy`** (`ractor_memory_proxy.rb`) — Wraps a `Memory` instance via `Ractor::Wrapper` so Ractor workers can read and write shared state. Only `get`, `set`, and `keys` are proxied; closures and subscriptions are not Ractor-safe and must use the thread-side Memory directly.
+
+**Data Carriers** (`ractor_job.rb`) — Three frozen `Data.define` structs:
+- `RactorJob` — work item: `id`, `type`, `payload`, `reply_queue`
+- `RactorJobError` — serialised error: `message`, `backtrace`
+- `RobotSpec` — frozen robot descriptor: `name`, `template`, `system_prompt`, `config_hash`, `hook_classes`
+
+## Tool Requirements for Ractor Safety
+
+Tools submitted to `RactorWorkerPool` must:
+1. Be instantiated fresh per call (no shared mutable state)
+2. Accept only Ractor-shareable arguments (frozen strings, numbers, frozen hashes)
+3. Return a value that can be `Ractor.make_shareable` (frozen or deep-freezable)
+
+LLM calls via `ruby_llm` are NOT Ractor-safe — do not submit tools that call the LLM to the pool.
+
+## Key Constraints
+
+- Shutdown is via poison-pill (one `nil` per worker) — always call `shutdown` to avoid orphaned Ractors.
+- `RactorNetworkScheduler.process_job` and `RactorWorkerPool.process_job` must be class methods — Ractors cannot call instance methods on objects defined outside their scope.
+- `RobotSpec#hook_classes` must be an array of frozen class references, not instances.
+
+## Testing
+
+- Minitest with SimpleCov (branch coverage tracked, no minimum threshold enforced yet)
+- Tests use RobotLab stubs (the full `robot_lab` gem is NOT loaded in tests — see `test_helper.rb`)
+- Coverage baseline: ~55% line / ~32% branch

data/Rakefile

@@ -24,16 +24,6 @@ task :test_file, [:file] do |_t, args|
   ruby "test/#{args[:file]}"
 end
 
-desc 'Check code style with RuboCop'
-task :rubocop do
-  sh 'bundle exec rubocop'
-end
-
-desc 'Auto-correct RuboCop offenses'
-task :rubocop_fix do
-  sh 'bundle exec rubocop -a'
-end
-
 desc 'Check code complexity with Flog (warn >=20, fail >=50)'
 task :flog_check do
   require 'flog'
@@ -71,36 +61,62 @@ task :flog_check do
   end
 end
 
-desc 'Run all quality checks: tests (with coverage), RuboCop, and Flog'
-task :quality do
-  results = {}
+desc 'Check for structural code duplication with Flay (mass >= 50)'
+task :flay_check do
+  require 'flay'
 
-  puts "\n#{'=' * 60}"
-  puts 'Quality Gate: Tests + Coverage'
-  puts '=' * 60
-  results[:tests] = system('bundle exec rake test') ? :pass : :fail
+  mass_threshold = 50
 
-  puts "\n#{'=' * 60}"
-  puts 'Quality Gate: RuboCop'
-  puts '=' * 60
-  results[:rubocop] = system('bundle exec rubocop') ? :pass : :fail
+  flay = Flay.new({ mass: mass_threshold, diff: false, verbose: false, summary: false, timeout: 60 })
+  flay.process(*Dir.glob('lib/**/*.rb'))
+  flay.analyze
 
-  puts "\n#{'=' * 60}"
-  puts 'Quality Gate: Flog Complexity'
-  puts '=' * 60
-  results[:flog] = system('bundle exec rake flog_check') ? :pass : :fail
+  if flay.hashes.empty?
+    puts "\nFlay: no structural duplication detected (mass >= #{mass_threshold})"
+  else
+    puts "\nFlay found structural duplication (mass >= #{mass_threshold}):"
+    flay.report
+    abort "\nFlay quality gate failed: #{flay.hashes.length} pattern(s) detected"
+  end
+end
+
+desc 'Run all quality checks: tests (with coverage), RuboCop, Flog, and Flay'
+task :quality do
+  gates = [
+    ['Tests + Coverage', 'bundle exec rake test'],
+    ['RuboCop',          'bundle exec rubocop'],
+    ['Flog Complexity',  'bundle exec rake flog_check'],
+    ['Flay Duplication', 'bundle exec rake flay_check']
+  ]
+
+  results = gates.map do |label, command|
+    puts "\n#{'=' * 60}"
+    puts "Quality Gate: #{label}"
+    puts '=' * 60
+    [label, system(command) ? :pass : :fail]
+  end
+
+  green = ->(s) { "\e[32m#{s}\e[0m" }
+  red   = ->(s) { "\e[31m#{s}\e[0m" }
+  width = results.map { |label, _| label.length }.max
 
   puts "\n#{'=' * 60}"
-  puts 'Quality Summary'
+  puts 'Quality Gate Summary'
   puts '=' * 60
-  results.each do |gate, status|
-    icon = status == :pass ? 'PASS' : 'FAIL'
-    puts "  [#{icon}] #{gate}"
+  results.each do |label, status|
+    badge = status == :pass ? green.call('PASS') : red.call('FAIL')
+    puts "  [#{badge}] #{label.ljust(width)}"
   end
+  puts '-' * 60
+
+  passed = results.count { |_, s| s == :pass }
+  failed = results.count { |_, s| s == :fail }
+  tally  = "#{passed} passed, #{failed} failed"
+  puts "  #{failed.zero? ? green.call(tally) : red.call(tally)}"
   puts '=' * 60
 
-  abort "\nQuality gate failed" if results.values.any?(:fail)
-  puts "\nAll quality gates passed."
+  abort "\n#{red.call('Quality gate failed.')}" unless failed.zero?
+  puts "\n#{green.call('All quality gates passed.')}"
 end
 
 namespace :docs do

data/docs/guides/ractor-parallelism.md

@@ -229,6 +229,71 @@ Values written via `set` are automatically deep-frozen before crossing the bound
 
 ---
 
+## Hooks in Ractor Workers
+
+`RactorNetworkScheduler` carries a robot's registered `RobotLab::Hook` handler
+classes across the Ractor boundary so the full hook pipeline still fires
+inside each worker.
+
+When the scheduler builds a `RobotSpec`, it collects handler classes from all
+three registration levels and stores them in the frozen `hook_classes` field:
+
+```ruby
+def ractor_hook_classes_for(robot)
+  [RobotLab.hooks, @hooks, robot.hooks]
+    .flat_map { |r| r.registrations.map(&:handler_class) }
+    .uniq.freeze
+end
+```
+
+| Registration level | Collected by |
+|---|---|
+| `RobotLab.on(Hook)` | `RobotLab.hooks` (global) |
+| `network.on(Hook)` | `@hooks` (network) |
+| `robot.on(Hook)` | `robot.hooks` (robot) |
+
+Inside each worker, the scheduler re-registers the handlers on the freshly
+built robot before running it:
+
+```ruby
+spec.hook_classes.each { |handler| robot.on(handler) }
+robot.run(message)   # full hook pipeline fires here
+```
+
+This works because a Hook handler is a Ruby **class**, and classes are
+Ractor-shareable constants — they cross the boundary without any
+serialization.
+
+### Writing a Ractor-Safe Hook
+
+A hook handler that may run inside a Ractor worker must follow the same
+statelessness rules as a Ractor-safe tool:
+
+- **No class-level state.** `@ivars` set on the class object live in the main
+  Ractor; non-main Ractors cannot read or write them, even when the values
+  themselves would be shareable.
+- **Accumulate events on the context, not the class.** Push results into
+  `ctx.local` (a plain object local to that Ractor's run) and return them as
+  part of the worker's result tuple so the main thread can aggregate them
+  after `Ractor#value`.
+- **Avoid `$stdout.puts` for anything you need interleaved with main-thread
+  output.** Output from non-main Ractors is buffered per-Ractor and only
+  flushes at Ractor exit. `Kernel#warn` is silently dropped. Reading the
+  `STDOUT` constant raises `IsolationError`. `$stderr.puts` and a
+  `File.open(frozen_path, "a")` opened fresh inside the worker are both safe.
+- **`on_error` fires inside the failing Ractor**, before the error propagates
+  back to the main thread. Surface whatever you need via the return tuple —
+  the main thread only learns of the failure when it calls `worker.value`.
+
+`examples/03_ractor_hooks.rb` walks through all of this with two example
+handlers (`TraceHook`, `PerfHook`) plus `RobotLab::Xyzzy` — a fully
+Ractor-safe tracer covering all five hook families (`run`, `llm_generation`,
+`tool_call`, `network_run`, `task`) — run directly against the hook mechanic
+without touching `ruby_llm` (which has class-level Proc callbacks that
+prevent construction inside Ractors today).
+
+---
+
 ## The Frozen-Data Contract
 
 Everything that crosses a Ractor boundary must be Ractor-shareable: frozen strings, frozen hashes, frozen arrays, `Data.define` structs, and integers/symbols/nil.
@@ -356,6 +421,16 @@ at_exit { RobotLab.shutdown_ractor_pool }
 
 ---
 
+## Runnable Examples
+
+- `examples/01_ractor_tools.rb` — CPU-bound tools routed through `RactorWorkerPool`
+- `examples/02_ractor_network.rb` — a robot network run via `RactorNetworkScheduler`
+- `examples/03_ractor_hooks.rb` — the hook system firing inside Ractor workers (no LLM API key required)
+
+```bash
+bundle exec ruby examples/03_ractor_hooks.rb
+```
+
 ## Next Steps
 
 - [Using Tools](using-tools.md) — Tool definitions and configuration

data/docs/index.md

@@ -60,6 +60,12 @@ pool = RobotLab.ractor_pool
 RobotLab.shutdown_ractor_pool
 ```
 
+## Examples
+
+- `examples/01_ractor_tools.rb` — CPU-bound tools through `RactorWorkerPool`
+- `examples/02_ractor_network.rb` — a robot network run via `RactorNetworkScheduler`
+- `examples/03_ractor_hooks.rb` — the hook system firing inside Ractor workers (no LLM API key required)
+
 ## Links
 
 - [Ractor Parallelism Guide](guides/ractor-parallelism.md)

data/examples/{29_ractor_tools.rb → 01_ractor_tools.rb}

@@ -26,8 +26,7 @@
 #   SHA-256 rounds (~320 ms on modern hardware) so the 4-6× speedup is
 #   clearly visible on a 6-core machine.
 
-require "robot_lab"
-require "robot_lab/ractor"
+require_relative "common"
 require "digest"
 
 # Always shut down the pool when the process exits.
@@ -114,12 +113,7 @@ end
 # Demo
 # =============================================================================
 
-puts "=" * 62
-puts "Example 29: Ractor-Safe CPU Tools"
-puts "=" * 62
-puts
-
-DIVIDER = ("─" * 54).freeze
+banner("Ractor-Safe CPU Tools")
 
 SAMPLE_TEXTS = [
   "Ruby makes programmer happiness a first-class concern in language design.",
@@ -130,10 +124,7 @@ SAMPLE_TEXTS = [
   "Simplicity is the ultimate sophistication in software architecture."
 ].freeze
 
-# ── 1. ractor_safe? flags ─────────────────────────────────────
-
-puts "1.  ractor_safe? flags"
-puts "    #{DIVIDER}"
+section("1.  ractor_safe? flags")
 
 {
   "WordStatsTool"     => WordStatsTool,
@@ -146,10 +137,7 @@ puts "    #{DIVIDER}"
 end
 puts
 
-# ── 2. RactorBoundary.freeze_deep ─────────────────────────────
-
-puts "2.  RactorBoundary.freeze_deep"
-puts "    #{DIVIDER}"
+section("2.  RactorBoundary.freeze_deep")
 
 nested = { tags: ["ruby", "ractor"], meta: { version: 2 } }
 frozen = RobotLab::RactorBoundary.freeze_deep(nested)
@@ -170,11 +158,8 @@ rescue RobotLab::RactorBoundaryError => e
 end
 puts
 
-# ── 3. Single pool submissions ─────────────────────────────────
-
 pool = RobotLab.ractor_pool
-puts "3.  Worker pool  (#{pool.size} Ractors — one per CPU core)"
-puts "    #{DIVIDER}"
+section("3.  Worker pool  (#{pool.size} Ractors — one per CPU core)")
 
 sample = SAMPLE_TEXTS.first
 
@@ -185,10 +170,7 @@ r = pool.submit("ReadabilityTool", { text: sample })
 puts "    ReadabilityTool: words_per_sentence=#{r[:words_per_sentence]}  long_word_pct=#{r[:long_word_pct]}%"
 puts
 
-# ── 4. ToolError propagation ───────────────────────────────────
-
-puts "4.  ToolError propagation"
-puts "    #{DIVIDER}"
+section("4.  ToolError propagation")
 puts "    Submitting nil as :text (WordStatsTool will call nil.scan — NoMethodError)"
 puts
 
@@ -200,10 +182,7 @@ rescue RobotLab::ToolError => e
 end
 puts
 
-# ── 5. Parallel batch vs sequential ───────────────────────────
-
-puts "5.  Parallel batch — #{SAMPLE_TEXTS.length} jobs, each doing #{HeavyDigestTool::ROUNDS.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1_').reverse} SHA-256 rounds"
-puts "    #{DIVIDER}"
+section("5.  Parallel batch — #{SAMPLE_TEXTS.length} jobs, #{HeavyDigestTool::ROUNDS.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1_').reverse} SHA-256 rounds each")
 
 # Parallel: one Thread per job, all submitted simultaneously.
 t0       = Process.clock_gettime(Process::CLOCK_MONOTONIC)
@@ -230,13 +209,8 @@ puts
 puts "    First result (truncated digest): #{parallel_results.first}"
 puts
 
-# ── 6. Shutdown ────────────────────────────────────────────────
-
-puts "6.  Shutdown"
-puts "    #{DIVIDER}"
+section("6.  Shutdown")
 RobotLab.shutdown_ractor_pool
 puts "    Pool shut down cleanly (poison-pill × #{pool.size} workers)."
 puts
-puts "=" * 62
-puts "Example 29 complete."
-puts "=" * 62
+hr

data/examples/{30_ractor_network.rb → 02_ractor_network.rb}

@@ -30,15 +30,9 @@
 #   bundle exec ruby examples/30_ractor_network.rb              # Parts 1 & 2
 #   ANTHROPIC_API_KEY=key ruby examples/30_ractor_network.rb    # Parts 1, 2 & 3
 
-require "robot_lab"
-require "robot_lab/ractor"
+require_relative "common"
 
-puts "=" * 62
-puts "Example 30: Ractor Network Scheduler"
-puts "=" * 62
-puts
-
-DIVIDER = ("─" * 54).freeze
+banner("Ractor Network Scheduler")
 
 # =============================================================================
 # Part 1: Simulated scheduler — dependency waves and timing
@@ -72,8 +66,7 @@ LATENCIES = {
 #
 #   Speedup    ≈ 1.7×
 
-puts "── Part 1: Simulated parallel run (no API key) ───────────"
-puts
+section("Part 1: Simulated parallel run (no API key)")
 
 # SimulatedScheduler overrides execute_spec so that instead of
 # constructing a real Robot and calling the LLM, it just sleeps for
@@ -139,8 +132,7 @@ puts
 # Part 2: Network.new(parallel_mode: :ractor) API
 # =============================================================================
 
-puts "── Part 2: Network.new(parallel_mode: :ractor) ───────────"
-puts
+section("Part 2: Network.new(parallel_mode: :ractor)")
 
 # When parallel_mode: :ractor is set on a Network, network.run(message:)
 # routes through RactorNetworkScheduler instead of SimpleFlow::Pipeline.
@@ -196,19 +188,16 @@ puts
 # =============================================================================
 
 unless ENV["ANTHROPIC_API_KEY"]
-  puts "── Part 3: Live LLM run ──────────────────────────────────"
+  section("Part 3: Live LLM run")
   puts "   Set ANTHROPIC_API_KEY to run the real pipeline."
   puts "   Expected behavior: headline_finder, background_brief, and"
   puts "   fact_checker run in parallel; report_writer follows."
   puts
-  puts "=" * 62
-  puts "Example 30 complete."
-  puts "=" * 62
+  hr
   exit 0
 end
 
-puts "── Part 3: Live LLM run (ANTHROPIC_API_KEY detected) ─────"
-puts
+section("Part 3: Live LLM run (ANTHROPIC_API_KEY detected)")
 
 puts "  Running 4-robot research pipeline on:"
 puts "  \"#{topic}\""
@@ -250,6 +239,4 @@ rescue RobotLab::Error => e
 end
 
 puts
-puts "=" * 62
-puts "Example 30 complete."
-puts "=" * 62
+hr

data/examples/03_ractor_hooks.rb

@@ -0,0 +1,399 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 31: Hook System in Ractor Context
+#
+# Demonstrates that RobotLab::Hook handler classes fire correctly inside
+# Ractor workers. Handler classes are Ruby constants, so they cross Ractor
+# boundaries natively and their class methods run in whichever Ractor calls them.
+#
+# The demo bypasses RobotLab::Robot and ruby_llm entirely (ruby_llm has class-
+# level Proc callbacks that prevent construction inside Ractors today). Instead
+# it calls TraceHook / PerfHook directly with a minimal mock context, isolating
+# the hook mechanic from the LLM layer.
+#
+# Concepts covered:
+#   - Handler classes are Ractor-shareable (they are Ruby constants)
+#   - Hook class methods fire inside named Ractor workers
+#   - Hooks must be stateless in Ractor context — no class-level @ivars
+#   - Events accumulate in ctx.local (Ractor-local object); returned in result tuple
+#   - Timing aggregated on main thread from Ractor return values
+#   - on_error fires inside the failing Ractor; events surface via return tuple
+#   - RobotSpec.hook_classes: how registries feed handler classes to workers
+#   - Xyzzy covers all five hook families; fully Ractor-safe (no class-level state)
+#
+# I/O note (Ruby 4.x):
+#   $stdout.puts from non-main Ractors is buffered per-Ractor and flushes at
+#   Ractor exit — not interleaved with main-thread output. Kernel#warn is
+#   silently dropped. The STDOUT constant raises IsolationError.
+#   Correct pattern: accumulate events in ctx.local, return via result tuple.
+#
+# Usage (no LLM API key required):
+#   bundle exec ruby examples/03_ractor_hooks.rb
+
+require_relative "common"
+require_relative "../../robot_lab/examples/xyzzy"
+
+# ---------------------------------------------------------------------------
+# Minimal context objects — all top-level constants so Ractors can reach them
+# ---------------------------------------------------------------------------
+DemoRobot   = Data.define(:name)
+DemoReply   = Data.define(:reply)
+DemoNetwork = Data.define(:name)   # used by network-run hook contexts (§5)
+
+# Lean context for network_run hooks — carries a network, not a robot.
+class DemoNetCtx
+  attr_reader   :network
+  attr_accessor :request, :local
+
+  def initialize(name:, request: nil)
+    @network = DemoNetwork.new(name: name.freeze)
+    @request = request
+    @local   = nil
+  end
+end
+
+# Lean context for task hooks — carries a task name string.
+class DemoTaskCtx
+  attr_reader   :task
+  attr_accessor :request, :local
+
+  def initialize(task:, request: nil)
+    @task    = task.freeze
+    @request = request
+    @local   = nil
+  end
+end
+
+# Lean stand-in for RobotLab's RunHookContext.
+# TraceHook and PerfHook only need: robot.name, response&.reply, error.message
+class DemoCtx
+  attr_reader   :robot, :request
+  attr_accessor :response, :error, :local
+
+  def initialize(name:, request: nil)
+    @robot    = DemoRobot.new(name: name.freeze)
+    @request  = request
+    @response = nil
+    @error    = nil
+    @local    = []   # accumulates hook event strings for this Ractor's run
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Hook handler classes — stateless by design
+#
+# Key Ractor rules:
+#   - A hook class IS a Ruby constant and IS Ractor-shareable.
+#   - But class-level instance variables (@events, @mutex, …) live in the
+#     class object in the main Ractor. Non-main Ractors cannot read or write
+#     them — IsolationError even if the values would be shareable.
+#   - $stdout.puts from non-main Ractors is buffered per-Ractor, flushing at
+#     Ractor exit. Output does not interleave with the main thread.
+#
+# Correct pattern: push events into ctx.local (a Ractor-local Array created
+# inside the worker). The caller returns ctx.local as part of its result tuple
+# so the main thread can aggregate and display the events.
+# ---------------------------------------------------------------------------
+
+# TraceHook records every lifecycle phase in ctx.local.
+# Stateless: no class-level storage — safe to call from any Ractor.
+class TraceHook < RobotLab::Hook
+  self.namespace = :trace
+
+  class << self
+    def before_run(ctx)
+      ctx.local << "[trace] before_run  robot=#{ctx.robot.name.ljust(14)} ractor=#{worker_label}"
+    end
+
+    def after_run(ctx)
+      reply = ctx.response&.reply.to_s[0, 44]
+      ctx.local << "[trace] after_run   robot=#{ctx.robot.name.ljust(14)} ractor=#{worker_label}  #{reply.inspect}"
+    end
+
+    def on_error(ctx)
+      ctx.local << "[trace] on_error    robot=#{ctx.robot.name.ljust(14)} ractor=#{worker_label}  #{ctx.error.message[0, 48].inspect}"
+    end
+
+    private
+
+    def worker_label
+      r = Ractor.current
+      r == Ractor.main ? "main" : (r.name || "ractor")
+    end
+  end
+end
+
+# PerfHook times each around_run call and stores the result in ctx.local.
+# Returns [block_result, elapsed_ms] so the caller can include timing in
+# the Ractor return tuple without any shared state.
+class PerfHook < RobotLab::Hook
+  self.namespace = :perf
+
+  class << self
+    def around_run(ctx, &block)
+      t0     = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      result = block.call
+      ms     = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1_000).round(2)
+      ctx.local << "[perf]  around_run  robot=#{ctx.robot.name.ljust(14)} ractor=#{worker_label}  #{ms}ms"
+      [result, ms]
+    end
+
+    private
+
+    def worker_label
+      r = Ractor.current
+      r == Ractor.main ? "main" : (r.name || "ractor")
+    end
+  end
+end
+
+# ===========================================================================
+banner("Hook System in Ractor Context")
+
+# ---------------------------------------------------------------------------
+# 1. Shareability: handler classes are Ruby constants
+# ---------------------------------------------------------------------------
+section("1. Handler classes are Ractor-shareable")
+
+[TraceHook, PerfHook, RobotLab::Xyzzy].each do |klass|
+  puts "  Ractor.shareable?(#{klass.name})  =>  #{Ractor.shareable?(klass)}"
+end
+
+probe = RobotLab::RobotSpec.new(
+  name: "probe", template: nil, system_prompt: "probe".freeze,
+  config_hash: {}.freeze, hook_classes: [TraceHook, PerfHook, RobotLab::Xyzzy].freeze
+)
+puts "  Ractor.shareable?(RobotSpec with hook_classes)  =>  #{Ractor.shareable?(probe)}"
+puts
+puts "  All three are Ruby constants — Ractor-shareable by definition."
+puts "  TraceHook / PerfHook are fully stateless: safe to call inside Ractors."
+puts "  Xyzzy is also fully Ractor-safe: LOG_PATH is a frozen constant;"
+puts "  each call opens its own File handle and uses PP.pp — no class-level state."
+
+# ---------------------------------------------------------------------------
+# 2. Hook methods fire inside named Ractor workers — concurrent execution
+# ---------------------------------------------------------------------------
+section("2. Hooks firing inside named Ractor workers")
+puts "   Three Ractors run concurrently. Each receives [TraceHook, PerfHook, Xyzzy]"
+puts "   via its hook_classes argument."
+puts "   TraceHook / PerfHook: events accumulate in ctx.local, returned in tuple."
+puts "   Xyzzy: writes to $stdout + appends to LOG_PATH — both from inside the"
+puts "   Ractor. [xyzzy] lines flush at Ractor exit, appearing after Ractor work."
+puts "   Wall time ≈ max(latencies), not their sum — evidence of concurrency."
+puts
+
+DEMO_ROBOTS = [
+  { name: "researcher",   latency: 0.18 },
+  { name: "analyst",      latency: 0.12 },
+  { name: "fact_checker", latency: 0.15 }
+].freeze
+
+hooks = [TraceHook, PerfHook, RobotLab::Xyzzy].freeze
+
+t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+workers = DEMO_ROBOTS.map do |entry|
+  rname   = entry[:name].freeze
+  latency = entry[:latency]
+
+  Ractor.new(rname, latency, hooks, name: rname) do |name, lat, hook_classes|
+    ctx = DemoCtx.new(name: name, request: "AI governance frameworks")
+
+    # before_run — all handlers that implement it
+    hook_classes.each do |h|
+      h.before_run(ctx) if h.singleton_class.public_method_defined?(:before_run)
+    end
+
+    # around_run — PerfHook wraps and times the simulated work.
+    # Returns [result, elapsed_ms]; timing surfaces via the Ractor tuple.
+    work_result, ms = PerfHook.around_run(ctx) do
+      sleep lat
+      "#{name}: #{(lat * 1_000).round}ms of simulated processing".freeze
+    end
+
+    ctx.response = DemoReply.new(reply: work_result)
+
+    # after_run — all handlers that implement it
+    hook_classes.each do |h|
+      h.after_run(ctx) if h.singleton_class.public_method_defined?(:after_run)
+    end
+
+    [name, work_result, ms, ctx.local.freeze].freeze
+  end
+end
+
+results = workers.map(&:value)
+wall_ms  = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1_000).round(0)
+seq_ms   = DEMO_ROBOTS.sum { |e| e[:latency] * 1_000 }.round(0)
+
+# Flatten results for display
+hook_events = results.flat_map { |_, _, _, evts| evts }
+timings     = results.to_h { |name, _, ms, _| [name, ms] }
+
+puts "  Hook events (returned via Ractor result tuples):"
+hook_events.each { |ev| puts "    #{ev}" }
+puts
+puts "  Wall time: #{wall_ms}ms  vs  sequential equivalent: #{seq_ms}ms"
+puts "  Speedup:   #{(seq_ms.to_f / wall_ms).round(1)}×  (#{DEMO_ROBOTS.size} Ractors running concurrently)"
+puts
+puts "  Results:"
+results.each { |name, val, _ms, _| puts "    #{name.ljust(14)}  #{val.inspect}" }
+puts
+puts "  Timings (aggregated from return tuples on main thread):"
+timings.each { |name, ms| puts "    #{name.ljust(14)}  #{ms}ms" }
+
+# ---------------------------------------------------------------------------
+# 3. on_error fires inside the failing Ractor before the error propagates
+# ---------------------------------------------------------------------------
+section("3. on_error fires inside a Ractor worker")
+puts "   Two Ractors run simultaneously. The failing one raises, calls"
+puts "   on_error inside the Ractor, collects the event in ctx.local,"
+puts "   then returns {error: ..., events: [...]} so the main thread"
+puts "   can verify that on_error fired inside the worker."
+puts "   (In production the error re-raises as Ractor::RemoteError;"
+puts "   events are surfaced here via the return tuple for display.)"
+puts
+
+error_workers = [
+  Ractor.new("healthy_robot".freeze, [TraceHook, RobotLab::Xyzzy].freeze, name: "healthy_robot") do |name, hook_classes|
+    ctx = DemoCtx.new(name: name, request: "run")
+    hook_classes.each { |h| h.before_run(ctx) }
+    sleep 0.05
+    ctx.response = DemoReply.new(reply: "#{name}: ok".freeze)
+    hook_classes.each { |h| h.after_run(ctx) }
+    { status: :ok, name: name, result: "ok", events: ctx.local.freeze }.freeze
+  end,
+
+  Ractor.new("failing_robot".freeze, [TraceHook, RobotLab::Xyzzy].freeze, name: "failing_robot") do |name, hook_classes|
+    ctx = DemoCtx.new(name: name, request: "run")
+    hook_classes.each { |h| h.before_run(ctx) }
+    begin
+      raise RuntimeError, "deliberate failure inside Ractor (#{name})"
+    rescue RuntimeError => e
+      ctx.error = e
+      hook_classes.each do |h|
+        h.on_error(ctx) if h.singleton_class.public_method_defined?(:on_error)
+      end
+    end
+    # on_error ran inside this Ractor; return events so main thread can see them
+    { status: :error, name: name, error: ctx.error.message, events: ctx.local.freeze }.freeze
+  end
+]
+
+error_workers.each do |worker|
+  r = worker.value
+  if r[:status] == :ok
+    puts "  #{r[:name]}: #{r[:result]}"
+    puts "  Events (healthy path):"
+    r[:events].each { |ev| puts "    #{ev}" }
+  else
+    puts "  #{r[:name]}: FAILED — #{r[:error]}"
+    puts "  Events (on_error fired inside the Ractor before returning to main):"
+    r[:events].each { |ev| puts "    #{ev}" }
+  end
+end
+
+puts
+puts "  The on_error event above was recorded inside the failing Ractor."
+puts "  The main thread only learns of the failure when it calls worker.value."
+
+# ---------------------------------------------------------------------------
+# 4. How hook_classes flows from registries to Ractor workers
+# ---------------------------------------------------------------------------
+section("4. Hook delivery via RobotSpec.hook_classes")
+puts "  When Network#run_with_ractor_scheduler builds each RobotSpec:"
+puts
+puts "    def ractor_hook_classes_for(robot)"
+puts "      [RobotLab.hooks, @hooks, robot.hooks]"
+puts "        .flat_map { |r| r.registrations.map(&:handler_class) }"
+puts "        .uniq.freeze"
+puts "    end"
+puts
+puts "  The resulting frozen Array of Class objects is stored in"
+puts "  RobotSpec.hook_classes. Inside each Ractor worker:"
+puts
+puts "    spec.hook_classes.each { |handler| robot.on(handler) }"
+puts "    robot.run(message)   # full hook pipeline fires here"
+puts
+puts "  Because Classes are Ruby constants, they survive the Ractor boundary"
+puts "  without any serialization. The hook pipeline inside the worker is"
+puts "  identical to what would fire on the main thread — as seen in §2 & §3."
+puts
+puts "  Registration level  →  collected by"
+puts "    RobotLab.on(Hook)   →  RobotLab.hooks  (global)"
+puts "    network.on(Hook)    →  @hooks           (network)"
+puts "    robot.on(Hook)      →  robot.hooks      (robot)"
+puts
+puts "  Stateless hook design rules:"
+puts "    ✓  Accumulate events in ctx.local — returned in Ractor result tuple"
+puts "    ✓  Return timing / metrics via result tuple — aggregated on main thread"
+puts "    ✓  $stderr.puts from Ractors — immediate output (unbuffered)"
+puts "    ✓  File.open(frozen_path, 'a') inside Ractor — Ractor-local handle, safe"
+puts "    ✓  PP.pp / JSON.generate inside Ractors — stdlib, fully Ractor-safe"
+puts "    ✗  Class-level @ivars — inaccessible from non-main Ractors"
+puts "    ✗  Class variables (@@var) — inaccessible from non-main Ractors"
+puts "    ✗  $stdout.puts from Ractors — buffered per-Ractor, not interleaved"
+puts "    ✗  Kernel#warn from Ractors — silently dropped (Ruby 4.x)"
+puts "    ✗  STDOUT constant — IsolationError from non-main Ractors"
+
+# ---------------------------------------------------------------------------
+# 5. Xyzzy: all hook families exercised from the main thread
+# ---------------------------------------------------------------------------
+section("5. Xyzzy: all five hook families exercised")
+puts "   Xyzzy is registered globally (RobotLab.on) and covers every hook"
+puts "   family. It is fully Ractor-safe: LOG_PATH is a frozen constant,"
+puts "   each call opens its own File handle and formats with PP.pp."
+puts "   stdout: one [xyzzy] tagline per call  |  log: full context snapshot"
+puts "   Log file: #{RobotLab::Xyzzy::LOG_PATH}"
+puts
+
+# ── run family ──
+puts "  [run family]"
+run_ctx = DemoCtx.new(name: "xyzzy_bot", request: "demonstrate hooks")
+RobotLab::Xyzzy.before_run(run_ctx)
+RobotLab::Xyzzy.around_run(run_ctx) do
+  run_ctx.response = DemoReply.new(reply: "xyzzy_bot: ok".freeze)
+end
+RobotLab::Xyzzy.after_run(run_ctx)
+run_ctx.error = RuntimeError.new("simulated run error")
+RobotLab::Xyzzy.on_error(run_ctx)
+puts
+
+# ── llm_generation family ──
+puts "  [llm_generation family]"
+llm_ctx = DemoCtx.new(name: "xyzzy_bot", request: "generate text")
+RobotLab::Xyzzy.before_llm_generation(llm_ctx)
+RobotLab::Xyzzy.around_llm_generation(llm_ctx) { nil }
+RobotLab::Xyzzy.after_llm_generation(llm_ctx)
+puts
+
+# ── tool_call family ──
+puts "  [tool_call family]"
+tool_ctx = DemoCtx.new(name: "xyzzy_bot", request: "call word_stats")
+RobotLab::Xyzzy.before_tool_call(tool_ctx)
+RobotLab::Xyzzy.around_tool_call(tool_ctx) { nil }
+RobotLab::Xyzzy.after_tool_call(tool_ctx)
+puts
+
+# ── network_run family ──
+puts "  [network_run family]"
+net_ctx = DemoNetCtx.new(name: "research_pipeline", request: "run pipeline")
+RobotLab::Xyzzy.before_network_run(net_ctx)
+RobotLab::Xyzzy.around_network_run(net_ctx) { nil }
+RobotLab::Xyzzy.after_network_run(net_ctx)
+puts
+
+# ── task family ──
+puts "  [task family]"
+task_ctx = DemoTaskCtx.new(task: "headline_finder", request: "run task")
+RobotLab::Xyzzy.before_task(task_ctx)
+RobotLab::Xyzzy.around_task(task_ctx) { nil }
+RobotLab::Xyzzy.after_task(task_ctx)
+
+puts
+puts "  Context snapshots (with robot/network/task/error details)"
+puts "  written to: #{RobotLab::Xyzzy::LOG_PATH}"
+
+puts
+hr

data/examples/common.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "logger"
+
+$LOAD_PATH.unshift File.expand_path("../../robot_lab/lib", __dir__)
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "robot_lab"
+require "robot_lab/ractor"
+
+# Unbuffered stdout so Ractor-generated output interleaves correctly with
+# main-thread headers when viewed in a terminal or redirected to a pipe.
+$stdout.sync = true
+
+# Fallback for when direnv has not activated examples/.envrc
+ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "prompts")
+
+RubyLLM.configure do |c|
+  c.logger                 = Logger.new(File::NULL)
+  c.default_model          = "claude-haiku-4-5-20251001"
+  c.anthropic_api_key      = ENV["ANTHROPIC_API_KEY"]
+  c.openai_api_key         = ENV["OPENAI_API_KEY"]
+  c.openai_organization_id = ENV["OPENAI_ORGANIZATION_ID"]
+  c.openai_project_id      = ENV["OPENAI_PROJECT_ID"]
+end
+
+RobotLab.configure do |c|
+  c.logger = Logger.new(File::NULL)
+end
+
+# ── Output Helpers ─────────────────────────────────────────────────────────────
+
+module ExOut
+  WIDTH = 62
+  RESET = "\e[0m"
+  BOLD  = "\e[1m"
+  DIM   = "\e[2m"
+  CYAN  = "\e[36m"
+end
+
+# Prints a bold top-level banner. Extracts the example number from $0
+# automatically so callers only supply the title.
+def banner(title)
+  num   = File.basename($0, ".rb")[/^\d+/]&.to_i
+  label = num ? "Example #{num}: #{title}" : title
+  puts "#{ExOut::BOLD}#{"=" * ExOut::WIDTH}#{ExOut::RESET}"
+  puts "#{ExOut::BOLD} #{label}#{ExOut::RESET}"
+  puts "#{ExOut::BOLD}#{"=" * ExOut::WIDTH}#{ExOut::RESET}"
+  puts
+end
+
+# Prints a named section divider.
+def section(title)
+  puts
+  tail = "─" * [ExOut::WIDTH - title.length - 4, 2].max
+  puts "#{ExOut::BOLD}#{ExOut::CYAN}── #{title} #{tail}#{ExOut::RESET}"
+  puts
+end
+
+# Prints a plain horizontal rule.
+def hr
+  puts "#{ExOut::DIM}#{"─" * ExOut::WIDTH}#{ExOut::RESET}"
+end
+
+# Prints a Rouge-highlighted Ruby snippet with a framed border.
+def show_code(ruby_string, label: "ruby")
+  require "rouge"
+  w      = ExOut::WIDTH - 2
+  border = "#{ExOut::DIM}  #{"─" * w}#{ExOut::RESET}"
+  output = Rouge::Formatters::Terminal256.new
+             .format(Rouge::Lexers::Ruby.new.lex(ruby_string))
+  output += "\n" unless output.end_with?("\n")
+  puts
+  puts "#{ExOut::DIM}  #{label}#{ExOut::RESET}"
+  puts border
+  output.each_line { |l| print "  #{l}" }
+  puts border
+  puts
+end

data/examples/xyzzy.rb

@@ -0,0 +1,88 @@
+# 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.
+#
+# stdout : one tagline per hook call  →  [xyzzy] HH:MM:SS.mmm hook_name
+# logfile: full context snapshot for each call (set via Xyzzy.logger=)
+#
+# Usage (from any example that requires common):
+#   require_relative "xyzzy"
+
+require "logger"
+
+module RobotLab
+  class Xyzzy < Hook
+    self.namespace = :xyzzy
+
+    class << self
+      attr_writer :logger
+
+      def logger
+        @logger ||= Logger.new($stdout)
+      end
+
+      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')
+        puts "  [xyzzy] #{ts} #{hook_name}"
+        logger.info("#{ts} #{hook_name} #{context_snapshot(ctx)}")
+      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/ractor/version.rb

@@ -4,6 +4,6 @@ module RobotLab
   # RactorPool (not Ractor) avoids shadowing Ruby's built-in Ractor class
   # for all code within the RobotLab namespace.
   module RactorPool
-    VERSION = '0.2.1'
+    VERSION = '0.2.6'
   end
 end

data/lib/robot_lab/ractor_job.rb

@@ -33,5 +33,9 @@ module RobotLab
   #     system_prompt: nil,
   #     config_hash:   { model: "claude-sonnet-4" }.freeze
   #   )
-  RobotSpec = Data.define(:name, :template, :system_prompt, :config_hash)
+  RobotSpec = Data.define(:name, :template, :system_prompt, :config_hash, :hook_classes) do
+    def initialize(name:, template:, system_prompt:, config_hash:, hook_classes: [].freeze)
+      super
+    end
+  end
 end

data/lib/robot_lab/ractor_network_scheduler.rb

@@ -92,6 +92,7 @@ module RobotLab
         system_prompt: spec.system_prompt,
         config: config
       )
+      spec.hook_classes.each { |handler| robot.on(handler) }
       robot.run(message).last_text_content.to_s.freeze
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: robot_lab-ractor
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.6
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -64,8 +64,11 @@ extra_rdoc_files: []
 files:
 - ".envrc"
 - ".github/workflows/deploy-github-pages.yml"
+- ".loki"
+- ".quality/reek_baseline.txt"
 - ".rubocop.yml"
 - CHANGELOG.md
+- CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -73,8 +76,11 @@ files:
 - docs/index.md
 - docs/superpowers/plans/2026-04-14-ractor-integration.md
 - docs/superpowers/specs/2026-04-14-ractor-integration-design.md
-- examples/29_ractor_tools.rb
-- examples/30_ractor_network.rb
+- examples/01_ractor_tools.rb
+- examples/02_ractor_network.rb
+- examples/03_ractor_hooks.rb
+- examples/common.rb
+- examples/xyzzy.rb
 - lib/robot_lab/ractor.rb
 - lib/robot_lab/ractor/version.rb
 - lib/robot_lab/ractor_boundary.rb
@@ -105,7 +111,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.11
+rubygems_version: 4.0.17
 specification_version: 4
 summary: Ractor-based parallel tool execution for RobotLab agents
 test_files: []