phronomy 0.9.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e84ccabf84c48e16cdb968c1f7b69f2348b24a70e477aa39bbbe1244d34edfc
-  data.tar.gz: f31dc2d1c4ed4bb7717e88278f1ced3debd0177f1f7a8042b170421a5d8e7493
+  metadata.gz: e73d1b49c4638232021afad5cc807466c4bb7b2cfcfe60446930288e868a3db9
+  data.tar.gz: 624e783c532fc2ea009db99a7bda4a1308f06019bc0e776a78d206b70031b352
 SHA512:
-  metadata.gz: 1c1ab4d05c27930b84abbad09f5c59027f9bfcddf9a89aa485608afdcd22ba50fcf971c2185a815206edfc37b29abb0fa99b7f80a8fa3f436c1d6a97b5ad38e4
-  data.tar.gz: 04016a561705ff24c4a6b9f8bb3d6918c303071f7bf97d94d70313b95f796ae561fee29fad9e7e620928655bf7e2007751cfa217bd973d83d2ad4d26d9754e3e
+  metadata.gz: 0ce003a8f0b0c85cd29a744b86ee89ad7414c511ea46c1ad446227824100174b6bfae76de8a4caa32428a50f77606af8006c17ae307eb514692a92829331570c
+  data.tar.gz: 10a3e965b58c730d5ba21eefc3c7151725a26e6accc24dbde04dd91546aa6c65bea801faae0fe5ef1908995a78c259159712c0f8dffe3f19938fa64b14988c16

data/CHANGELOG.md

@@ -9,12 +9,90 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
----
+### Added
+
+- **`Phronomy::Filter::Base` — unified value filter interface** (#389):
+  A single abstract base class `Filter::Base` with one method `call(value, **context)`
+  covers all three agent boundaries — user input, LLM output, and tool return values.
+  Subclasses return the (possibly transformed) value to continue, or call `block!` /
+  `raise Phronomy::FilterBlockError` to reject.  The same filter instance can be
+  registered at multiple sites.  Guardrails registered via `add_input_guardrail` /
+  `add_output_guardrail` are automatically included at the front of the filter chain.
+
+  ```ruby
+  class PiiMaskFilter < Phronomy::Filter::Base
+    def call(value, **_context)
+      value.to_s.gsub(/\b\d{2,4}-\d{2,4}-\d{4}\b/, "[PHONE]")
+    end
+  end
+
+  f = PiiMaskFilter.new
+  agent.add_input_filter(f)
+  agent.add_output_filter(f)
+  agent.add_tool_result_filter(CustomerDataTool, f)
+  ```
+
+  Class-level DSL counterparts: `input_filter`, `output_filter`, `tool_result_filter`.
+  The `tools(Hash)` DSL also accepts a `:result_filter` key for per-tool scoping.
 
-## [0.9.1] - 2026-06-06
+- **`Guardrail::Base#call` — Filter::Base-compatible interface**:
+  `Guardrail::Base` now implements `call(value, **_context)`, which calls `check(value)`
+  and returns the value unchanged (or raises `GuardrailError`).  Existing guardrail
+  subclasses require no changes.
+
+### Changed
+
+- **Guardrail execution unified into the filter chain**:
+  Guardrails registered via `add_input_guardrail` / `add_output_guardrail` now run
+  as the first entries in `run_input_filters!` / `run_output_filters!`.  The separate
+  `run_input_guardrails!` / `run_output_guardrails!` call sites in `invoke_once`,
+  `_stream_impl`, and `Suspendable#resume` have been removed.  Behaviour is unchanged
+  — guardrails still run before any filters and `GuardrailError` still propagates.
+
+
+
+## [0.10.0] - 2026-06-08
 
 ### Added
 
+- **`Task#map` — transform a Task's completed value** (#384):
+  `task.map { |result| ctx.merge(answer: result[:output]) }` returns a new `Task`
+  whose completed value is the block's return value. Primary use-case: wire
+  `Agent::Base#invoke_async` into a Workflow entry action so the agent result
+  reaches `WorkflowContext` through the standard `:action_completed` path without
+  requiring any changes to `FSMSession`. If the source task fails or is cancelled,
+  the mapped task propagates the error without calling the block.
+
+### Removed
+
+- **`Agent::Base#run_as_child` removed** (#384):
+  Introduced when agents had their own FSM (`Agent::FSM`). After `Agent::FSM` was
+  removed in v0.9.0, the `:child_completed` event payload was silently discarded by
+  `FSMSession`, so `ctx.answer` was never populated. Migrate to
+  `invoke_async + Task#map`:
+
+  ```ruby
+  # Before (removed)
+  entry :translate, ->(ctx) { TranslationAgent.new.run_as_child(ctx.query, ctx: ctx) }
+  transition from: :translate, on: :child_completed, to: :done
+
+  # After (recommended)
+  entry :translate, ->(ctx) {
+    TranslationAgent.new.invoke_async(ctx.query).map { |r| ctx.merge(answer: r[:output]) }
+  }
+  transition from: :translate, to: :done
+  ```
+
+### Added
+
+- **`Task#map` — transform a Task's completed value** (post-v0.9.0):
+  `task.map { |result| ctx.merge(answer: result[:output]) }` returns a new `Task`
+  whose completed value is the block's return value.  The primary use-case is
+  connecting `Agent::Base#invoke_async` to a Workflow entry action so the agent
+  result populates the `WorkflowContext` through the standard `:action_completed`
+  path.  If the source task fails or is cancelled, the mapped task propagates the
+  error without calling the block.
+
 - **`Phronomy::Diagnostics` and `SchedulerReentrancyError`** (#278, #279):
   `Phronomy::Diagnostics` exposes a snapshot of current scheduler state
   (`pending_count`, `active_tasks`, `pool_utilization`, etc.) for debugging and
@@ -233,6 +311,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added (post-v0.9.0)
 
+- **`Agent::Base#run_as_child` removed** (post-v0.9.0):
+  `run_as_child` was introduced when agents had their own FSM.  After `Agent::FSM`
+  was removed, the `:child_completed` event payload was silently discarded by
+  `FSMSession`, meaning `ctx.answer` was never populated.  The method has been
+  removed.  Use `invoke_async + Task#map` instead:
+
+  ```ruby
+  # Before (deprecated)
+  entry :translate, ->(ctx) { TranslationAgent.new.run_as_child(ctx.query, ctx: ctx) }
+  transition from: :translate, on: :child_completed, to: :done
+
+  # After (recommended)
+  entry :translate, ->(ctx) {
+    TranslationAgent.new.invoke_async(ctx.query).map { |r| ctx.merge(answer: r[:output]) }
+  }
+  transition from: :translate, to: :done
+  ```
+
 - **`Phronomy::Agent::CheckpointStore` — idempotency store for HITL resume** (post-v0.9.0):
   New in-memory store tracks consumed checkpoint IDs. Calling `Agent::Base#resume` twice
   with the same checkpoint raises `Phronomy::CheckpointAlreadyResumedError` instead of

data/README.md

@@ -7,7 +7,7 @@
 > We apologise for the instability this may cause.
 
 **Phronomy** is a Ruby AI agent framework inspired by open-source AI agent frameworks.  
-It provides composable building blocks — Workflows, Agents, Tools, Guardrails, and Tracing — all powered by [RubyLLM](https://github.com/crmne/ruby_llm) for LLM abstraction.
+It provides composable building blocks — Workflows, Agents, Tools, Filters, and Tracing — all powered by [RubyLLM](https://github.com/crmne/ruby_llm) for LLM abstraction.
 
 ## Features
 
@@ -31,8 +31,8 @@ It provides composable building blocks — Workflows, Agents, Tools, Guardrails,
 | **Agent** — ReAct-style tool-calling agents with guardrails and conversation history | Stable |
 | **Before-Completion Hook** — Three-tier LLM parameter injection | Stable |
 | **Context Management** — Token budget calculation, estimation, and pruning; `Agent::Base` protected hooks: `build_context` (overridable), `trim_messages`, `trim_to_budget`, `compact_messages`, `budget_exceeded?`, `drop_messages_over` | Stable |
-| **Guardrails** — Input/output validation with custom `InputGuardrail`/`OutputGuardrail` | Beta |
-| **`PromptInjectionGuardrail`** — Built-in `InputGuardrail` subclass that detects prompt-injection patterns; usable standalone or as part of a guardrail chain | Beta |
+| **Filters** — Input/output transformation and blocking via `Filter::Base`; call `block!(reason)` to reject and raise `FilterBlockError` | Beta |
+| **`PromptInjectionFilter`** — Built-in `Filter::Base` subclass that detects prompt-injection patterns; usable standalone or as part of a filter chain | Beta |
 | **`Agent::Context::Capability::Base.redact_params` / `.max_result_size`** — Class-level DSL: `redact_params` masks parameter values in log/trace output; `max_result_size` truncates oversized tool results before they reach the LLM | Beta |
 | **Output Parser** — JSON and Struct-mapped parsers for structured LLM responses | Stable |
 | **Eval Framework** — Dataset-driven evaluation with multiple scorer types | Beta |
@@ -54,8 +54,9 @@ It provides composable building blocks — Workflows, Agents, Tools, Guardrails,
 | Feature | Stability |
 |---|---|
 | **Workflow EventLoop Mode** — Opt-in event-driven execution: `Phronomy.configure { \|c\| c.event_loop = true }` | Experimental |
-| **Agent EventLoop Mode** — `Agent#invoke` (non-blocking via EventLoop), `Agent#run_as_child` (child-FSM pattern for Workflow integration), parallel tool dispatch via `ParallelToolChat` | Experimental |
+| **Agent EventLoop Mode** — `Agent#invoke` (non-blocking via EventLoop), `Agent#invoke_async` + `Task#map` (child-agent pattern for Workflow integration), parallel tool dispatch via `ParallelToolChat` | Experimental |
 | **`invoke_async` / `call_async`** — `Agent::Base#invoke_async` and `Workflow#invoke_async` return a `Task`; `Agent::Context::Capability::Base#call_async` similarly; compatible with EventLoop and standalone contexts | Experimental |
+| **`Task#map`** — transforms a `Task`'s completed value via a block; returns a new `Task` whose value is the block's return value; if the source task fails or is cancelled the mapped task propagates the error without calling the block; primary use-case: `invoke_async.map { \|r\| ctx.merge(answer: r[:output]) }` to wire agent results into a `WorkflowContext` | Experimental |
 | **CancellationToken** — Cooperative cancellation via `cancel!`/`cancelled?`/`raise_if_cancelled!`; `timeout_after(seconds)` for monotonic-clock deadlines; optional `deadline:` (wall-clock) for backward compatibility; passed as `config: { cancellation_token: token }` to agents and `dispatch_parallel`; injected into `tool.execute` when the method declares a `cancellation_token:` keyword | Experimental |
 | **`dispatch_parallel` / `fan_out` `force_kill:` option** — `force_kill: false` (default) leaves timed-out workers running and raises `TimeoutError` immediately; `force_kill: true` restores the old `Thread#kill` behaviour with a `logger.warn` | Beta |
 | **`execution_mode` DSL on `Agent::Context::Capability::Base`** — Declares how a tool's `execute` should be dispatched: `:cooperative` (same scheduler thread), `:blocking_io` (default; offloaded to `BlockingAdapterPool`), `:cpu_bound`, `:external_process` | Experimental |
@@ -77,6 +78,7 @@ It provides composable building blocks — Workflows, Agents, Tools, Guardrails,
 | **Agent::SharedState** — Shared state pattern: peer agents collaborate via a shared KnowledgeStore; `member` DSL with per-agent instructions and `coordination` team protocol | Experimental |
 | **`ScopePolicy`** — Configurable policy callable that maps (tool, scope, agent) to `:allow`/`:approve`/`:reject`; default policy auto-routes high-risk scopes through the approval gate | Experimental |
 | **HITL Checkpoint/Resume** — `Agent::Base#invoke` returns `{ suspended: true, checkpoint: Checkpoint }` when an approval-required tool is encountered without a synchronous handler; `Agent::Base#resume(checkpoint, approved:)` resumes execution; `Agent::Base.resume(checkpoint, approved:)` (class-level) resolves the agent class automatically; `Checkpoint#to_h` / `Checkpoint.from_h` for serialization; `Agent::Base#checkpoint_store=` for custom idempotency backends; `CheckpointAlreadyResumedError` raised on duplicate resume | Experimental |
+| **`Filter::Base` — unified value filter interface** — `Phronomy::Filter::Base` with a single abstract method `call(value, **context)`; apply to user input (`add_input_filter` / `input_filter` DSL), final LLM output (`add_output_filter` / `output_filter` DSL), or individual tool return values (`add_tool_result_filter(tool_class?, filter)` / `tool_result_filter` DSL); filters transform values and return the result, or raise `Phronomy::FilterBlockError` to reject; filter chains are composable; the same filter instance can be reused across all three sites | Beta |
 
 > **Public API boundary**: The tables above are the complete list of classes, modules, and features
 > intended for gem consumers. Every entry has an associated stability label.
@@ -199,20 +201,18 @@ final = app.send_event(state: state, event: :approve)
 puts "Approved: #{final.approved}"  # => true
 ```
 
-In EventLoop mode (`c.event_loop = true`), `Agent#run_as_child` spawns a child agent
-asynchronously. When the child succeeds, `:child_completed` is dispatched with the result
-`{ output:, messages:, usage: }` as its payload; when it fails, `:child_failed` is
-dispatched. Always declare both transitions to avoid a stuck workflow:
+In EventLoop mode (`c.event_loop = true`), use `invoke_async + Task#map` to run an agent
+asynchronously inside a Workflow entry action.  The mapped Task returns a `WorkflowContext`,
+which `FSMSession` picks up via the standard `:action_completed` path:
 
 ```ruby
-# EventLoop mode: workflow that runs an agent as a child FSM.
-# The result { output:, messages:, usage: } arrives as the :child_completed event
-# payload — write it back to the context in the target state's entry action.
-entry :run_agent, ->(ctx) {
-  MyAgent.new.run_as_child(ctx.query, ctx: ctx)
+# EventLoop mode: workflow that runs an agent and captures the result.
+entry :translate, ->(ctx) {
+  TranslationAgent.new.invoke_async(ctx.query).map do |result|
+    ctx.merge(answer: result[:output])   # returns WorkflowContext
+  end
 }
-transition from: :run_agent, on: :child_completed, to: :done
-transition from: :run_agent, on: :child_failed,    to: :handle_error
+transition from: :translate, to: :done   # no on: needed
 ```
 
 ### Multi-Agent — Agent-as-Tool pattern
@@ -253,30 +253,31 @@ result = OrchestratorAgent.new.invoke("Write a blog post about Ruby 3.4 features
 puts result[:output]
 ```
 
-### Guardrails — Input/output validation
+### Filters — Input/output transformation and blocking
 
-Call `fail!(reason)` inside `check` to reject — it raises `Phronomy::GuardrailError`.
-When a guardrail rejects, `invoke` raises instead of returning an output.
+Filters sit between user input and the LLM (input filters) or between the LLM response and the caller (output filters).
+A filter may **transform** the value (return the modified value) or **block** it (call `block!(reason)`, which raises `Phronomy::FilterBlockError`).
 
 ```ruby
-class NoSensitiveDataGuardrail < Phronomy::Guardrail::InputGuardrail
-  def check(input)
-    fail!("Credit card numbers are not allowed") if input.match?(/\d{4}-\d{4}-\d{4}-\d{4}/)
+class NoCreditCardFilter < Phronomy::Filter::Base
+  def call(value, **_context)
+    block!("Credit card numbers are not allowed") if value.match?(/\d{4}-\d{4}-\d{4}-\d{4}/)
+    value
   end
 end
 
 agent = ResearchAgent.new
-agent.add_input_guardrail(NoSensitiveDataGuardrail.new)
+agent.add_input_filter(NoCreditCardFilter.new)
 
 begin
   agent.invoke("Charge 4111-1111-1111-1111")
-rescue Phronomy::GuardrailError => e
+rescue Phronomy::FilterBlockError => e
   puts e.message   # => "Credit card numbers are not allowed"
 end
 ```
 
-> **Note:** Phronomy includes `PromptInjectionGuardrail`, a built-in pattern-based
-> input guardrail that detects common injection patterns (see the feature table above).
+> **Note:** Phronomy includes `PromptInjectionFilter`, a built-in pattern-based
+> input filter that detects common injection patterns (see the feature table above).
 > PII scanning and content classification are **not** provided by the framework;
 > that logic must be implemented by the application. Reference implementations for
 > common patterns are available in `phronomy-examples` (example 06).
@@ -852,11 +853,11 @@ span attributes by default (`trace_pii: false`). To include full content in trac
 Phronomy configuration. Evaluate whether your tracing backend (OTLP collector, Jaeger,
 Honeycomb, etc.) meets your data-retention and privacy requirements.
 
-**Prompt injection** — Phronomy provides `PromptInjectionGuardrail`, a built-in
-pattern-based input guardrail that detects common injection patterns (ignore/override
+**Prompt injection** — Phronomy provides `PromptInjectionFilter`, a built-in
+pattern-based input filter that detects common injection patterns (ignore/override
 instructions, role-switching phrases, etc.). It is a useful starting point, not a
 comprehensive defence; applications processing untrusted input should layer additional
-custom guardrails as needed (see the Guardrails section above).
+custom filters as needed (see the Filters section above).
 
 **Tool and MCP security** — Tools can perform real-world side effects (database
 writes, API calls, file deletion). Treat tool execution as a privileged operation:

data/lib/phronomy/agent/base.rb

@@ -3,7 +3,7 @@
 require "securerandom"
 require_relative "checkpoint_store"
 require_relative "concerns/retryable"
-require_relative "concerns/guardrailable"
+require_relative "concerns/filterable"
 require_relative "concerns/before_completion"
 require_relative "concerns/suspendable"
 require_relative "concerns/error_translation"
@@ -34,7 +34,7 @@ module Phronomy
     class Base
       include Phronomy::Runnable
       include Concerns::Retryable
-      include Concerns::Guardrailable
+      include Concerns::Filterable
       include Concerns::BeforeCompletion
       include Concerns::Suspendable
       include Concerns::ErrorTranslation
@@ -418,7 +418,7 @@ module Phronomy
 
       # Invokes the agent with the given input and returns a result Hash.
       # Applies the retry policy configured via {.retry_policy} when transient
-      # errors occur. {Phronomy::GuardrailError} is never retried.
+      # errors occur. {Phronomy::FilterBlockError} is never retried.
       #
       # @param input     [String, Hash] the user message; a Hash may supply
       #   +:message+, +:query+, or +:user+ as the text key, plus any template
@@ -439,7 +439,7 @@ module Phronomy
       # @return [Hash] +{ output: String, messages: Array, usage: Phronomy::TokenUsage }+,
       #   or +{ output: nil, suspended: true, checkpoint: Phronomy::Agent::Checkpoint,
       #   messages: Array }+ when the invocation was suspended awaiting tool approval.
-      # @raise [Phronomy::GuardrailError] when an input or output guardrail rejects the value
+      # @raise [Phronomy::FilterBlockError] when an input or output filter rejects the value
       # @example Normal invocation
       #   result = MyAgent.new.invoke("What is Ruby?")
       #   puts result[:output]
@@ -532,56 +532,6 @@ module Phronomy
         end
       end
 
-      # Registers this agent as a child {AgentFSM} inside the given Workflow context.
-      #
-      # Use this method from a Workflow entry action (running on the EventLoop thread)
-      # instead of {#invoke}, which would raise a deadlock error because +invoke+ blocks
-      # on a +Thread::Queue+ when EventLoop mode is active.
-      #
-      # The agent runs asynchronously in a background IO thread.  When it finishes, the
-      # parent {FSMSession} receives a +:child_completed+ event whose payload is the
-      # result hash +{ output:, messages:, usage: }+.  Declare an +on: :child_completed+
-      # transition in your Workflow to advance to the next state.
-      #
-      # The result is delivered exclusively as the +:child_completed+ event payload.
-      # The parent Workflow task is the sole owner of the parent +WorkflowContext+ and
-      # applies the result after receiving the event — no background thread writes to
-      # the parent context directly.
-      #
-      # @example
-      #   entry :run_agent, ->(ctx) { MyAgent.new.run_as_child(ctx.query, ctx: ctx) }
-      #   transition from: :run_agent, on: :child_completed, to: :process_result
-      #
-      # @param input     [String, Hash]  user input passed to the agent
-      # @param ctx       [Object]        a WorkflowContext that responds to +#thread_id+
-      # @param messages  [Array]         prior conversation history
-      # @param config    [Hash]          invocation config (forwarded to +_invoke_impl+)
-      # @return [nil]  the caller must not wait on any return value;
-      #                the result arrives as a +:child_completed+ event
-      # @raise [Phronomy::Error] when EventLoop mode is not enabled
-      # @api public
-      def run_as_child(input, ctx:, messages: [], config: {})
-        unless Phronomy.configuration.event_loop
-          raise Phronomy::Error,
-            "run_as_child requires EventLoop mode. " \
-            "Enable with: Phronomy.configure { |c| c.event_loop = true }"
-        end
-
-        parent_id = ctx.thread_id
-        thread_id = "#{parent_id}_agent_#{SecureRandom.uuid}"
-        Phronomy::Runtime.instance.spawn(name: "agent-child:#{thread_id}") do
-          result = _invoke_impl(input, messages: messages, thread_id: thread_id, config: config)
-          Phronomy::EventLoop.instance.post(
-            Phronomy::Event.new(type: :child_completed, target_id: parent_id, payload: result)
-          )
-        rescue => e
-          Phronomy::EventLoop.instance.post(
-            Phronomy::Event.new(type: :child_failed, target_id: parent_id, payload: e)
-          )
-        end
-        nil
-      end
-
       # Streaming version of #invoke. Yields {Phronomy::Agent::StreamEvent} objects
       # as they are produced by the underlying LLM.
       #
@@ -653,7 +603,7 @@ module Phronomy
       # Streaming implementation for #stream.
       def _stream_impl(input, messages: [], thread_id: nil, config: {}, &block)
         trace("agent.invoke", input: input, **_build_caller_meta(config)) do |_span|
-          run_input_guardrails!(input)
+          input = run_input_filters!(input)
 
           chat = build_chat
           user_message = extract_message(input)
@@ -684,7 +634,7 @@ module Phronomy
           run_before_completion_hooks!(chat, config)
 
           output, usage = _drain_stream(chat, user_message, config, &block)
-          run_output_guardrails!(output)
+          output = run_output_filters!(output)
 
           result = {output: output, messages: chat.messages, usage: usage}
           block.call(StreamEvent.new(type: :done, payload: result))
@@ -863,7 +813,7 @@ module Phronomy
       # wrap it in a retry loop without duplicating the LLM interaction logic.
       def invoke_once(input, messages: [], thread_id: nil, config: {})
         trace("agent.invoke", input: input, **_build_caller_meta(config)) do |_span|
-          run_input_guardrails!(input)
+          input = run_input_filters!(input)
 
           user_message = extract_message(input)
           chat = build_chat
@@ -885,7 +835,8 @@ module Phronomy
           )
           next [result, usage] if result[:suspended]
 
-          run_output_guardrails!(result[:output])
+          filtered_output = run_output_filters!(result[:output])
+          result = result.merge(output: filtered_output) unless filtered_output.equal?(result[:output])
           [result, usage]
         end
       end
@@ -1126,21 +1077,34 @@ module Phronomy
         end
 
         # Step 3: wrap with approval gate when handler is registered.
-        return resolved unless resolved.requires_approval && @approval_handler
+        if resolved.requires_approval && @approval_handler
+          handler = @approval_handler
+          # Capture the effective tool name before building the anonymous subclass.
+          # Class-level instance variables (@tool_name) are not inherited through
+          # subclassing, so the wrapper must set it explicitly.
+          effective_name = resolved.new.name
+          resolved = Class.new(resolved) do
+            tool_name effective_name
+            define_method(:call) do |args|
+              if handler.call(name, args)
+                super(args)
+              else
+                "Tool execution denied."
+              end
+            end
+          end
+        end
 
-        handler = @approval_handler
-        # Capture the effective tool name before building the anonymous subclass.
-        # Class-level instance variables (@tool_name) are not inherited through
-        # subclassing, so the wrapper must set it explicitly.
-        effective_name = resolved.new.name
+        # Step 4: wrap with tool result filters when registered.
+        result_filters = _tool_result_filters_for(tool_class)
+        return resolved if result_filters.empty?
+
+        effective_name4 = resolved.new.name
         Class.new(resolved) do
-          tool_name effective_name
+          tool_name effective_name4
           define_method(:call) do |args|
-            if handler.call(name, args)
-              super(args)
-            else
-              "Tool execution denied."
-            end
+            result = super(args)
+            result_filters.inject(result) { |val, f| f.call(val, tool_name: name, args: args) }
           end
         end
       end

data/lib/phronomy/agent/concerns/filterable.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Concerns
+      # Adds input, output, and tool-result filter support to an agent.
+      #
+      # Filters transform (or block) values at three call sites:
+      #   - *input*       — the raw user input string, before the LLM is called
+      #   - *output*      — the final LLM output string, before it is returned
+      #   - *tool result* — the return value of each tool call
+      #
+      # Each filter in the chain receives the value returned by the previous one.
+      # A {Phronomy::FilterBlockError} raised inside any filter propagates to the
+      # caller.
+      #
+      # @api private
+      module Filterable
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        # Class-level DSL mixed into the including agent class.
+        module ClassMethods
+          # Registers a filter applied to every invocation's user input.
+          # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+          # when a class is given it is instantiated with +.new+.
+          # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+          # @return [void]
+          # @api public
+          def input_filter(filter)
+            @_class_input_filters ||= []
+            @_class_input_filters << _resolve_filter(filter)
+          end
+
+          # Registers a filter applied to every invocation's final LLM output.
+          # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+          # when a class is given it is instantiated with +.new+.
+          # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+          # @return [void]
+          # @api public
+          def output_filter(filter)
+            @_class_output_filters ||= []
+            @_class_output_filters << _resolve_filter(filter)
+          end
+
+          # Registers a filter applied to every tool result for all tools.
+          # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+          # when a class is given it is instantiated with +.new+.
+          # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+          # @return [void]
+          # @api public
+          def tool_result_filter(filter)
+            @_class_tool_result_filters ||= []
+            @_class_tool_result_filters << _resolve_filter(filter)
+          end
+
+          # @return [Array<Phronomy::Filter::Base>]
+          # @api private
+          def _class_input_filters
+            @_class_input_filters || []
+          end
+
+          # @return [Array<Phronomy::Filter::Base>]
+          # @api private
+          def _class_output_filters
+            @_class_output_filters || []
+          end
+
+          # @return [Array<Phronomy::Filter::Base>]
+          # @api private
+          def _class_tool_result_filters
+            @_class_tool_result_filters || []
+          end
+
+          private
+
+          # Coerce +filter+ to an instance: if a Class is passed, call +.new+;
+          # otherwise return the object as-is.
+          # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+          # @return [Phronomy::Filter::Base]
+          # @api private
+          def _resolve_filter(filter)
+            filter.is_a?(Class) ? filter.new : filter
+          end
+        end
+
+        # Registers an input filter on this instance.
+        # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+        # when a class is given it is instantiated with +.new+.
+        # Runs in addition to any class-level input filters.
+        # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+        # @return [self]
+        # @api public
+        def add_input_filter(filter)
+          @_instance_input_filters ||= []
+          @_instance_input_filters << _resolve_filter(filter)
+          self
+        end
+
+        # Registers an output filter on this instance.
+        # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+        # when a class is given it is instantiated with +.new+.
+        # Runs in addition to any class-level output filters.
+        # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+        # @return [self]
+        # @api public
+        def add_output_filter(filter)
+          @_instance_output_filters ||= []
+          @_instance_output_filters << _resolve_filter(filter)
+          self
+        end
+
+        # Registers a tool result filter on this instance.
+        #
+        # When called with two arguments, the filter is scoped to the given tool
+        # class only.  When called with one argument, it applies to all tools.
+        # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+        # when a class is given it is instantiated with +.new+.
+        #
+        # @overload add_tool_result_filter(filter)
+        #   @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>] applied to every tool
+        # @overload add_tool_result_filter(tool_class, filter)
+        #   @param tool_class [Class] scope the filter to this tool
+        #   @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+        # @return [self]
+        # @api public
+        def add_tool_result_filter(tool_class_or_filter, filter = nil)
+          if filter.nil?
+            # Single-argument form: apply to all tools.
+            @_instance_tool_result_filters ||= []
+            @_instance_tool_result_filters << _resolve_filter(tool_class_or_filter)
+          else
+            # Two-argument form: scoped to one tool class.
+            @_scoped_tool_result_filters ||= {}
+            (@_scoped_tool_result_filters[tool_class_or_filter] ||= []) << _resolve_filter(filter)
+          end
+          self
+        end
+
+        private
+
+        # Run input filters (class-level then instance-level).
+        # @param input [String, Hash] the raw user input
+        # @return [String, Hash] the (possibly transformed) input
+        # @api private
+        def run_input_filters!(input)
+          class_filters = self.class._class_input_filters
+          inst_filters = @_instance_input_filters || []
+          (class_filters + inst_filters).inject(input) { |val, f| f.call(val) }
+        end
+
+        # Run output filters (class-level then instance-level).
+        # @param output [String] the LLM output
+        # @return [String] the (possibly transformed) output
+        # @api private
+        def run_output_filters!(output)
+          class_filters = self.class._class_output_filters
+          inst_filters = @_instance_output_filters || []
+          (class_filters + inst_filters).inject(output) { |val, f| f.call(val) }
+        end
+
+        # Collect all tool-result filters (global + scoped) for a given tool class.
+        # @param tool_class [Class]
+        # @return [Array<Phronomy::Filter::Base>]
+        # @api private
+        def _tool_result_filters_for(tool_class)
+          global = self.class._class_tool_result_filters + (@_instance_tool_result_filters || [])
+          scoped = (@_scoped_tool_result_filters || {})[tool_class] || []
+          global + scoped
+        end
+
+        # Coerce +filter+ to an instance: if a Class is passed, call +.new+;
+        # otherwise return the object as-is.
+        # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+        # @return [Phronomy::Filter::Base]
+        # @api private
+        def _resolve_filter(filter)
+          filter.is_a?(Class) ? filter.new : filter
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/concerns/retryable.rb

@@ -6,7 +6,7 @@ module Phronomy
       # Adds configurable retry behaviour to an agent.
       #
       # Included in {Phronomy::Agent::Base}. The retry loop wraps the full
-      # #invoke_once call; {Phronomy::GuardrailError} is never retried.
+      # #invoke_once call; {Phronomy::FilterBlockError} is never retried.
       # @api private
       module Retryable
         def self.included(base)
@@ -16,7 +16,7 @@ module Phronomy
         # Class-level DSL methods mixed into the including agent class.
         module ClassMethods
           # Configures a retry policy that wraps the full #invoke call.
-          # GuardrailError is never retried regardless of this setting.
+          # FilterBlockError is never retried regardless of this setting.
           #
           # @param times [Integer] maximum retry attempts (default: 0)
           # @param wait  [Symbol, Numeric] :exponential, :linear, or a fixed Float
@@ -60,7 +60,7 @@ module Phronomy
           attempt = 0
           begin
             invoke_once(input, messages: messages, thread_id: thread_id, config: config)
-          rescue Phronomy::GuardrailError
+          rescue Phronomy::FilterBlockError
             raise
           rescue Phronomy::CancellationError
             raise # Never retry after cancellation.

data/lib/phronomy/agent/concerns/suspendable.rb

@@ -80,7 +80,7 @@ module Phronomy
         # @return [Hash] +{ output: String, suspended: false, messages: Array, usage: Phronomy::TokenUsage }+
         #   or +{ output: nil, suspended: true, checkpoint: Phronomy::Agent::Checkpoint, messages: Array }+
         #   when a second approval-required tool is encountered during continuation
-        # @raise [Phronomy::GuardrailError] when an output guardrail rejects the value
+        # @raise [Phronomy::FilterBlockError] when an output filter rejects the value
         # @raise [Phronomy::CheckpointAlreadyResumedError] when the checkpoint has already been consumed
         # @api private
         def resume(checkpoint, approved:, config: {})
@@ -143,7 +143,7 @@ module Phronomy
           output = response.content
           usage = Phronomy::TokenUsage.from_tokens(response.tokens)
 
-          run_output_guardrails!(output)
+          output = run_output_filters!(output)
 
           {output: output, suspended: false, messages: chat.messages, usage: usage}
         end

data/lib/phronomy/agent/context/capability/base.rb

@@ -92,7 +92,7 @@ module Phronomy
             public
 
             # Sets the access scope for this tool (metadata; enforcement is the responsibility of
-            # the Workflow/Guardrail layer).
+            # the Workflow/Filter layer).
             # @param value [Symbol] e.g. :read_only, :write, :admin
             # @api public
             # mutant:disable - neutral failure: unparser round-trip produces different source
@@ -218,7 +218,7 @@ module Phronomy
             # retried up to +times+ times with the specified wait strategy.
             # Multiple policies can be registered and are evaluated in order.
             #
-            # GuardrailError is never retried regardless of this configuration.
+            # FilterBlockError is never retried regardless of this configuration.
             #
             # @param exception_classes [Array<Class>] exception classes to retry on
             # @param times  [Integer] maximum retry attempts (default: 1)

data/lib/phronomy/filter/base.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Filter
+    # Abstract base class for value filters.
+    #
+    # A filter may either transform a value (return the new value) or block it
+    # (raise {Phronomy::FilterBlockError}).  The same filter instance can be
+    # registered at multiple call sites — input, output, and tool result.
+    #
+    # @example PII masking filter
+    #   class PiiMaskFilter < Phronomy::Filter::Base
+    #     def call(value, **_context)
+    #       value.to_s
+    #            .gsub(/\b\d{2,4}-\d{2,4}-\d{4}\b/, "[PHONE]")
+    #            .gsub(/\b(?:\d{4}[- ]?){3}\d{4}\b/, "[CARD]")
+    #     end
+    #   end
+    #
+    # @example Blocking filter
+    #   class NoBadWordFilter < Phronomy::Filter::Base
+    #     def call(value, **_context)
+    #       block!("Forbidden content detected") if value.to_s.include?("badword")
+    #       value
+    #     end
+    #   end
+    #
+    # @api public
+    class Base
+      # Process +value+ and return the (possibly transformed) result.
+      #
+      # The +context+ keyword arguments vary by call site:
+      #   - Tool result: +{ tool_name: String, args: Hash }+
+      #   - Input / output: +(empty)+
+      #
+      # @param value   [Object] the value being filtered
+      # @param context [Hash]   optional call-site metadata
+      # @return [Object] the transformed value (or the original if unchanged)
+      # @raise [Phronomy::FilterBlockError] to reject the value
+      # @api public
+      def call(value, **_context)
+        raise NotImplementedError, "#{self.class}#call is not implemented"
+      end
+
+      protected
+
+      # Reject the value with a human-readable reason.
+      # @param reason [String]
+      # @raise [Phronomy::FilterBlockError]
+      # @api public
+      def block!(reason)
+        raise Phronomy::FilterBlockError.new(reason, filter: self)
+      end
+    end
+  end
+end

data/lib/phronomy/{guardrail/prompt_injection_guardrail.rb → filter/prompt_injection_filter.rb}

@@ -1,28 +1,31 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Guardrail
+  module Filter
     # Detects potential prompt injection attempts in the agent input.
     #
     # Prompt injection is an attack where an adversary embeds LLM instructions
     # inside data sources (e.g. RAG chunks, tool results, user input) to override
     # the agent's intended behaviour.
     #
-    # This guardrail scans the input string for common injection patterns and
-    # calls {#fail!} when a match is found.  It is intended to be registered as
-    # an input guardrail on agents that consume untrusted external content.
+    # This filter scans the input string for common injection patterns and
+    # calls {#block!} when a match is found.  It is intended to be registered as
+    # an input filter on agents that consume untrusted external content.
     #
     # @example
     #   class MyAgent < Phronomy::Agent::Base
     #     model "gpt-4o"
-    #     input_guardrails Phronomy::Guardrail::PromptInjectionGuardrail.new
+    #     input_filter Phronomy::Filter::PromptInjectionFilter
     #   end
     #
     # @example Custom patterns
-    #   guard = Phronomy::Guardrail::PromptInjectionGuardrail.new(
+    #   filter = Phronomy::Filter::PromptInjectionFilter.new(
     #     extra_patterns: [/exfiltrate/i]
     #   )
-    class PromptInjectionGuardrail < InputGuardrail
+    #   agent.add_input_filter(filter)
+    #
+    # @api public
+    class PromptInjectionFilter < Base
       # Common prompt injection / jailbreak patterns.
       DEFAULT_PATTERNS = [
         /ignore\s+(previous|prior|all)\s+instructions?/i,
@@ -38,20 +41,24 @@ module Phronomy
       ].freeze
 
       # @param extra_patterns [Array<Regexp>] additional patterns to scan for
-      # @api private
+      # @api public
       def initialize(extra_patterns: [])
         super()
         @patterns = DEFAULT_PATTERNS + extra_patterns
       end
 
       # Scans the input string for injection patterns.
-      # @param input [String, Hash]
-      # @api private
-      def check(input)
-        text = input.is_a?(Hash) ? input.values.join(" ") : input.to_s
+      # @param value [String, Hash]
+      # @param context [Hash]
+      # @return [String, Hash] the original value when no injection is detected
+      # @raise [Phronomy::FilterBlockError] when a pattern matches
+      # @api public
+      def call(value, **_context)
+        text = value.is_a?(Hash) ? value.values.join(" ") : value.to_s
         @patterns.each do |pattern|
-          fail!("Potential prompt injection detected") if text.match?(pattern)
+          block!("Potential prompt injection detected") if text.match?(pattern)
         end
+        value
       end
     end
   end

data/lib/phronomy/filter.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Convenience require for Filter sub-classes.
+require_relative "filter/base"
+require_relative "filter/prompt_injection_filter"

data/lib/phronomy/generator_verifier.rb

@@ -66,8 +66,7 @@ module Phronomy
     # @!attribute [r] trusted
     #   @return [Boolean] true when confidence >= threshold
     Result = Struct.new(
-      :output, :confidence, :citations, :iterations, :review_notes, :trusted,
-      keyword_init: true
+      :output, :confidence, :citations, :iterations, :review_notes, :trusted
     ) do
       # @return [Boolean] true when confidence >= threshold
       alias_method :trusted?, :trusted

data/lib/phronomy/multi_agent/team_coordinator.rb

@@ -47,8 +47,7 @@ module Phronomy
         :index,    # Integer — 0-based worker index
         :agent,    # Agent::Base instance
         :messages, # Array  — accumulated conversation history
-        :status,   # Symbol — :idle | :available | :done
-        keyword_init: true
+        :status    # Symbol — :idle | :available | :done
       ) do
         # Returns true when this worker is ready to accept the next task.
         def available? = [:idle, :available].include?(status)

data/lib/phronomy/task/mapped_backend.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module Phronomy
+  class Task
+    # Backend for Tasks created by {Task#map}.
+    #
+    # A mapped task's lifecycle is driven entirely by the +on_complete+
+    # callback of its source task — it never spawns a thread of its own.
+    # +MappedBackend+ transitions the owning task to +:running+ immediately
+    # on initialization so that +FSMSession+ treats it as an in-progress
+    # async action.  Completion (or failure) is triggered externally via
+    # {Task#transition!} from the +on_complete+ callback registered by
+    # {Task#map}.
+    #
+    # +await+ and +join+ block until {#unblock} is called, which {Task#map}
+    # arranges by registering a second +on_complete+ callback on the *mapped*
+    # task itself after the transform callback has been registered.
+    #
+    # @api private
+    class MappedBackend < Backend
+      def initialize(task:, &)
+        super
+        @done_queue = Queue.new
+        task.transition!(:running)
+      end
+
+      # Unblocks +await+ / +join+.  Called by {Task#map} after the mapped task
+      # reaches a terminal state.
+      # @api private
+      def unblock(value, error)
+        @done_queue.push([value, error])
+      end
+
+      # Blocks until the mapped task reaches a terminal state.
+      # @return [Object] the mapped value
+      # @raise [Exception] if the source task or the map block raised an error
+      # @api private
+      def await
+        value, error = @done_queue.pop
+        raise error if error
+
+        value
+      end
+
+      # Returns +false+ — a mapped task has no independent thread to kill.
+      # @return [Boolean]
+      # @api private
+      def alive?
+        false
+      end
+
+      # No-op — mapped tasks carry no independent thread to cancel.
+      # @return [self]
+      # @api private
+      def cancel!
+        self
+      end
+
+      # Blocks until the mapped task completes, with an optional timeout.
+      # @param limit [Numeric, nil]
+      # @return [Object, nil] +nil+ on timeout
+      # @api private
+      def join(limit = nil)
+        if limit.nil?
+          await
+        else
+          begin
+            Timeout.timeout(limit) { await }
+          rescue Timeout::Error
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/task.rb

@@ -4,6 +4,7 @@ require_relative "task/backend"
 require_relative "task/thread_backend"
 require_relative "task/immediate_backend"
 require_relative "task/fiber_backend"
+require_relative "task/mapped_backend"
 
 module Phronomy
   # A single unit of concurrent work.
@@ -195,6 +196,58 @@ module Phronomy
       self
     end
 
+    # Returns a new {Task} whose completed value is the result of applying
+    # +block+ to this task's completed value.
+    #
+    # If this task fails or is cancelled, the mapped task also fails/is
+    # cancelled with the same error.  The block is never called in error cases.
+    #
+    # The primary use-case is transforming an agent result into a
+    # {WorkflowContext} so that a Workflow entry action can return a Task
+    # whose value is picked up by {Workflow::FSMSession} via the existing
+    # +:action_completed+ path:
+    #
+    # @example Returning agent output into a Workflow state field
+    #   entry :translate, ->(ctx) {
+    #     TranslationAgent.new.invoke_async(ctx.query).map do |result|
+    #       ctx.merge(answer: result[:output])   # returns WorkflowContext
+    #     end
+    #   }
+    #
+    # @yield  [value] the completed value of this task
+    # @yieldreturn [Object] the value for the mapped task
+    # @return [Task] a new task that completes when this task does
+    # @api public
+    def map(&block)
+      # MappedBackend drives the task lifecycle entirely via on_complete;
+      # it never spawns a thread of its own.
+      mapped = self.class.spawn(
+        name: "#{@name}-mapped",
+        parent: @parent,
+        backend_class: MappedBackend
+      ) {}
+
+      on_complete do |value, error|
+        mapped_value = nil
+        mapped_error = error
+        unless error
+          begin
+            mapped_value = block.call(value)
+          rescue => e
+            mapped_error = e
+          end
+        end
+        if mapped_error
+          mapped.transition!(:failed, error: mapped_error)
+        else
+          mapped.transition!(:completed, value: mapped_value)
+        end
+        # Unblock mapped.await / mapped.join after the terminal transition.
+        mapped.backend.unblock(mapped_value, mapped_error)
+      end
+      mapped
+    end
+
     # Returns +true+ once the task has finished (success, error, or cancellation).
     # @return [Boolean]
     # @api private

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.9.1"
+  VERSION = "0.11.0"
 end

data/lib/phronomy.rb

@@ -87,12 +87,15 @@ module Phronomy
     end
   end
 
-  class GuardrailError < Error
-    attr_reader :guardrail
+  # Raised by a {Phronomy::Filter::Base} subclass when the filter rejects a
+  # value without transforming it (blocking the pipeline).
+  # @api public
+  class FilterBlockError < Error
+    attr_reader :filter
 
-    def initialize(message, guardrail: nil)
+    def initialize(message, filter: nil)
       super(message)
-      @guardrail = guardrail
+      @filter = filter
     end
   end
 
@@ -123,7 +126,8 @@ module Phronomy
   # Raised when a {Phronomy::WorkflowContext} field is mutated from a thread
   # that does not own the context (i.e. not the EventLoop dispatch thread).
   # Only raised in EventLoop mode.  Use +context.merge(...)+ to produce a new
-  # context, or deliver updates as +:child_completed+ event payloads.
+  # context, or deliver updates as +:action_completed+ event payloads
+  # via {Agent::Base#invoke_async} + {Task#map}.
   class WorkflowContextOwnershipError < Error; end
 
   class << self

data/scripts/api_snapshot.rb

@@ -32,8 +32,8 @@ PUBLIC_API_ENTRIES = [
   # Beta
   Phronomy::MultiAgent::Orchestrator,
   Phronomy::MultiAgent::TeamCoordinator,
-  Phronomy::Guardrail::InputGuardrail,
-  Phronomy::Guardrail::OutputGuardrail,
+  Phronomy::Filter::Base,
+  Phronomy::Filter::PromptInjectionFilter,
   Phronomy::VectorStore::Base,
   Phronomy::VectorStore::InMemory,
   Phronomy::VectorStore::Embeddings::Base,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.11.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-05 00:00:00.000000000 Z
+date: 2026-06-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -64,9 +64,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.6'
-description: Phronomy provides composable building blocks — Agents, Workflows, Tools,
-  Guardrails, and Tracing — for building AI agents in Ruby. Powered by RubyLLM for
-  LLM abstraction.
+description: Phronomy is a Ruby AI agent framework that provides composable building
+  blocks — Agents, Workflows, Tools, Filters, and Tracing — for building AI agents
+  in Ruby. Powered by RubyLLM for LLM abstraction.
 email:
 - raizo.tcs@gmail.com
 executables: []
@@ -109,7 +109,7 @@ files:
 - lib/phronomy/agent/checkpoint_store.rb
 - lib/phronomy/agent/concerns/before_completion.rb
 - lib/phronomy/agent/concerns/error_translation.rb
-- lib/phronomy/agent/concerns/guardrailable.rb
+- lib/phronomy/agent/concerns/filterable.rb
 - lib/phronomy/agent/concerns/retryable.rb
 - lib/phronomy/agent/concerns/suspendable.rb
 - lib/phronomy/agent/context/capability/base.rb
@@ -147,12 +147,10 @@ files:
 - lib/phronomy/eval/scorer/llm_judge.rb
 - lib/phronomy/event.rb
 - lib/phronomy/event_loop.rb
+- lib/phronomy/filter.rb
+- lib/phronomy/filter/base.rb
+- lib/phronomy/filter/prompt_injection_filter.rb
 - lib/phronomy/generator_verifier.rb
-- lib/phronomy/guardrail.rb
-- lib/phronomy/guardrail/base.rb
-- lib/phronomy/guardrail/input_guardrail.rb
-- lib/phronomy/guardrail/output_guardrail.rb
-- lib/phronomy/guardrail/prompt_injection_guardrail.rb
 - lib/phronomy/invocation_context.rb
 - lib/phronomy/knowledge_source.rb
 - lib/phronomy/llm_adapter.rb
@@ -189,6 +187,7 @@ files:
 - lib/phronomy/task/backend.rb
 - lib/phronomy/task/fiber_backend.rb
 - lib/phronomy/task/immediate_backend.rb
+- lib/phronomy/task/mapped_backend.rb
 - lib/phronomy/task/thread_backend.rb
 - lib/phronomy/task_group.rb
 - lib/phronomy/testing.rb

data/lib/phronomy/agent/concerns/guardrailable.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Concerns
-      # Adds input and output guardrail support to an agent.
-      #
-      # Included in {Phronomy::Agent::Base}. Guardrails are run on the raw
-      # input string before the LLM is called, and on the raw output string
-      # before the result is returned to the caller.
-      # @api private
-      module Guardrailable
-        # Attach a guardrail that validates input before every #invoke call.
-        # @param guardrail [Phronomy::Guardrail::InputGuardrail]
-        # @return [self]
-        # @api private
-        def add_input_guardrail(guardrail)
-          @input_guardrails ||= []
-          @input_guardrails << guardrail
-          self
-        end
-
-        # Attach a guardrail that validates output before it is returned.
-        # @param guardrail [Phronomy::Guardrail::OutputGuardrail]
-        # @return [self]
-        # @api private
-        def add_output_guardrail(guardrail)
-          @output_guardrails ||= []
-          @output_guardrails << guardrail
-          self
-        end
-
-        private
-
-        def run_input_guardrails!(input)
-          (@input_guardrails || []).each { |g| g.run!(input) }
-        end
-
-        def run_output_guardrails!(output)
-          (@output_guardrails || []).each { |g| g.run!(output) }
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/guardrail/base.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Guardrail
-    # Abstract base class for all guardrails.
-    #
-    # Subclasses override #check to validate input or output.
-    # Call #fail! inside #check to reject with a reason.
-    #
-    # @example
-    #   class NoPIIGuardrail < Phronomy::Guardrail::InputGuardrail
-    #     def check(input)
-    #       fail!("PII detected") if input.to_s.match?(/\d{3}-\d{2}-\d{4}/)
-    #     end
-    #   end
-    class Base
-      # Validate the value. Subclasses must implement this method.
-      # @param value [Object] the input or output being checked
-      # @raise [Phronomy::GuardrailError] if the guardrail rejects the value
-      # @api public
-      def check(value)
-        raise NotImplementedError, "#{self.class}#check is not implemented"
-      end
-
-      # Run the check, raising GuardrailError on failure.
-      # @param value [Object]
-      # @return [Object] the original value (unchanged) when the check passes
-      # @api public
-      def run!(value)
-        check(value)
-        value
-      end
-
-      protected
-
-      # Call inside #check to reject the value.
-      # @param reason [String] human-readable rejection reason
-      # @raise [Phronomy::GuardrailError]
-      # @api public
-      def fail!(reason)
-        raise Phronomy::GuardrailError.new(reason, guardrail: self)
-      end
-    end
-  end
-end

data/lib/phronomy/guardrail/input_guardrail.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Guardrail
-    # Guardrail applied to agent/chain input before it reaches the LLM.
-    #
-    # @example
-    #   class NoCreditCardGuardrail < Phronomy::Guardrail::InputGuardrail
-    #     def check(input)
-    #       fail!("Credit card numbers are not allowed") if input.to_s.match?(/\d{4}[- ]\d{4}[- ]\d{4}[- ]\d{4}/)
-    #     end
-    #   end
-    #
-    #   agent = MyAgent.new
-    #   agent.add_input_guardrail(NoCreditCardGuardrail.new)
-    class InputGuardrail < Base
-    end
-  end
-end

data/lib/phronomy/guardrail/output_guardrail.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Guardrail
-    # Guardrail applied to agent/chain output before it is returned to the caller.
-    #
-    # @example
-    #   class NoSecretsGuardrail < Phronomy::Guardrail::OutputGuardrail
-    #     def check(output)
-    #       fail!("Response contains a secret key") if output.to_s.match?(/sk-[A-Za-z0-9]{32,}/)
-    #     end
-    #   end
-    #
-    #   agent = MyAgent.new
-    #   agent.add_output_guardrail(NoSecretsGuardrail.new)
-    class OutputGuardrail < Base
-    end
-  end
-end

data/lib/phronomy/guardrail.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-# Convenience require for Guardrail sub-classes.
-# Zeitwerk auto-loads individual files; this is only needed for explicit requires.
-require_relative "guardrail/base"
-require_relative "guardrail/input_guardrail"
-require_relative "guardrail/output_guardrail"