mistri 0.4.1 → 0.6.0

data/lib/mistri/sub_agent.rb

@@ -3,7 +3,7 @@
 module Mistri
   # Delegation with a clean context: a child agent runs on its own session
   # (the caller's store, linked in the caller's transcript), and only its
-  # final answer returns to the parent — exploration never fills the
+  # final answer returns to the parent; exploration never fills the
   # parent's window. Compaction rescues a full context after the fact;
   # spawning avoids filling it in the first place. A child session is its
   # own single-provider session, so delegating to a cheaper model is the
@@ -23,9 +23,10 @@ module Mistri
   #
   #   spawn = Mistri::SubAgent.spawner(provider:, tools: [fetch_page, search])
   #
-  # Children never receive a spawn tool: delegation is one level deep by
-  # construction. Parallel fan-out costs nothing — several spawn calls in
-  # one turn run concurrently on the executor pool.
+  # The open spawner never grants itself, preventing accidental recursion.
+  # Hosts may deliberately nest fixed specialists. Several spawn calls in
+  # one turn are scheduled concurrently; provider instances decide whether
+  # their network requests overlap.
   #
   # Child events forward into the parent's stream tagged with origin
   # ("researcher#ab12cd34"; nesting of named specialists joins with ">").
@@ -35,6 +36,8 @@ module Mistri
   # runtime is denied and reported in band. Gate the delegation itself
   # instead (needs_approval: on the definition or spawner).
   class SubAgent
+    require_relative "sub_agent/runtime"
+
     SPAWNER_DESCRIPTION =
       "Delegate a self-contained task to a focused child agent with a clean " \
       "context. The child starts blank: give it complete instructions and " \
@@ -45,11 +48,13 @@ module Mistri
     attr_reader :name, :description
 
     # schema: makes the specialist answer in validated JSON (task mode
-    # underneath) — fan-out children then return a uniform shape the parent
+    # underneath), so fan-out children return a uniform shape the parent
     # synthesizes instead of five styles of prose.
     def initialize(name:, description:, provider:, system: nil, tools: [], schema: nil,
                    **agent_options)
       SubAgent.forbid_gated!(tools)
+      @gate = agent_options.delete(:needs_approval) || false
+      ChildAgentOptions.validate!(agent_options)
       @name = name.to_s
       @description = description
       @provider = provider
@@ -57,12 +62,13 @@ module Mistri
       @tools = tools
       @schema = schema
       @agent_options = agent_options
-      @gate = agent_options.delete(:needs_approval) || false
     end
 
     # The delegate tool: each call runs a fresh child and answers with its
     # final text, plus {agent, session_id} on the ui channel so a host can
-    # link the child's transcript.
+    # link the child's transcript. The model may name each run, so two
+    # parallel researchers read as "Corgi" and "Beagle" in lanes and lists
+    # instead of "researcher" twice.
     def tool
       sub = self
       blurb = "#{@description} Runs as a focused sub-agent with a clean " \
@@ -71,56 +77,207 @@ module Mistri
                                 schema: lambda {
                                   string :task, "Complete instructions for the sub-agent",
                                          required: true
+                                  string :name, "A short name for this run, shown wherever " \
+                                                "its events appear (default: the tool's name)"
                                 }) do |args, context|
-        sub.run_child(args.fetch("task"), context)
+        sub.run_child(args.fetch("task"), context, name: args["name"])
       end
     end
 
-    def run_child(task, context)
-      SubAgent.run_child(label: @name, provider: @provider, system: @system,
-                         tools: @tools, task: task, context: context, schema: @schema,
-                         **@agent_options)
+    def run_child(task, context, name: nil)
+      SubAgent.run_child(label: SubAgent.sanitize_label(name, fallback: @name),
+                         provider: @provider, system: @system,
+                         tools: @tools, task: task, parent_context: context, schema: @schema,
+                         agent_options: @agent_options)
     end
 
     class << self
-      # The open spawn tool over a pool of tools the host allows children to
-      # use. The model may name the worker (a display label riding origins
-      # and the transcript link) and grant a tool subset by name; models: is
-      # the host's allowlist of child model ids — without one, no model
-      # choice is offered at all, so a hallucinated id can never construct a
-      # provider or land children on an expensive model.
-      def spawner(provider:, tools: [], models: [], needs_approval: false, **agent_options)
-        forbid_gated!(tools)
-        if tools.any? { |tool| tool.name == "spawn_agent" }
-          raise ConfigurationError, "the spawn tool never goes in its own pool"
-        end
+      # The open spawn tool: the model names each worker, grants it a tool
+      # subset from the host's pool, and may pick a type, a model, and a
+      # mode. All policy lives on Spawner; this is the front door.
+      def spawner(provider:, **)
+        Spawner.new(provider: provider, **).tool
+      end
 
-        schema = spawner_schema(tools, models, default_model(provider))
-        Tool.define("spawn_agent", SPAWNER_DESCRIPTION,
-                    needs_approval: needs_approval, schema: schema) do |args, context|
-          run_child(label: child_label(args["name"]),
-                    provider: child_provider(provider, args["model"], models),
-                    system: args.fetch("instructions"),
-                    tools: pick(tools, args["tools"]),
-                    task: args.fetch("task"), context: context, **agent_options)
-        end
+      # The whole kit in one call: the spawn tool plus the management
+      # console, so a host hands its agent everything workers need.
+      def pack(provider:, console: {}, **spawner_options)
+        [spawner(provider: provider, **spawner_options), *Console.tools(**console)]
+      end
+
+      # A worker's display name, made safe for origins: the label rides
+      # them as "label#id" and nesting joins with ">", so those separators
+      # squeeze to hyphens along with whitespace. Blank falls back.
+      def sanitize_label(text, fallback:)
+        label = text.to_s.gsub(/[#>\s]+/, "-").squeeze("-")[0, 32]
+        label = label.delete_prefix("-").delete_suffix("-")
+        label.empty? ? fallback : label
       end
 
-      def run_child(label:, provider:, system:, tools:, task:, context:, schema: nil,
-                    **agent_options)
-        store = context.session ? context.session.store : Stores::Memory.new
+      def run_child(label:, provider:, system:, tools:, task:, parent_context:, schema: nil,
+                    agent_options: {})
+        ChildAgentOptions.validate!(agent_options)
+        store = parent_context.session ? parent_context.session.store : Stores::Memory.new
         child = Session.new(store: store)
-        context.session&.append("subagent", "name" => label, "session_id" => child.id)
-        agent = Agent.new(provider: provider, session: child, system: system,
-                          tools: tools, **agent_options)
-        origin = "#{label}##{child.id[0, 8]}"
-        emit = ->(event) { forward(event, origin, context) }
-        result = if schema
-                   agent.task(task, schema: schema, signal: context.signal, &emit)
+        parent_context.session&.append("subagent", "name" => label, "session_id" => child.id)
+        # An inline child runs on a signal derived from the parent's: the
+        # parent's abort cascades down through the handle, while stopping
+        # the child alone leaves the parent running.
+        signal, cascade = if parent_context.signal
+                            parent_context.signal.derive
+                          else
+                            [AbortSignal.new, nil]
+                          end
+        result = begin
+          execute_child(child: child, label: label, provider: provider, system: system,
+                        tools: tools, task: task, schema: schema, signal: signal,
+                        emit: parent_context.emit, agent_options: agent_options)
+        rescue StandardError => e
+          unless child.entries.any? { |entry| entry["type"] == Child::TERMINAL }
+            child.append(Child::TERMINAL,
+                         "status" => "failed", "error" => "#{e.class}: #{e.message}")
+          end
+          raise
+        ensure
+          parent_context.signal&.remove_callback(cascade) if cascade
+        end
+        outcome = answer(result, label, child)
+        child.append(Child::TERMINAL, terminal(result))
+        outcome
+      end
+
+      # The host job's way back in: a runtime factory turns the durable spec
+      # into live dependencies inside the worker. The compatible direct
+      # provider/system/tools form remains for hosts that already reconstruct
+      # those values in their job. Either form is checked against the spec
+      # before execution. The child then runs exactly like an inline child,
+      # streams origin-tagged events, and reports back to its parent.
+      #
+      # The child lease is duplicate suppression, not an exactly-once claim:
+      # a refused delivery leaves the current holder alone. A terminal means
+      # a queued cancellation or finished retry and returns nil. The runner
+      # retains an acquired lease through terminal persistence and reporting,
+      # suppressing ordinary redelivery while that lease remains live.
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- ordered dispatch transitions are the safety contract
+      def run_dispatched(spec, store:, emit: nil, runtime_factory: nil,
+                         provider: UNSET_RUNTIME_FIELD, system: UNSET_RUNTIME_FIELD,
+                         tools: UNSET_RUNTIME_FIELD, schema: UNSET_RUNTIME_FIELD,
+                         retry_factory_errors: true, **agent_options)
+        runtime = nil
+        resolved = nil
+        authorized = false
+        terminalize = false
+        factory_failed = false
+        retryable_exit = false
+        primary_error = nil
+        delivery_owned = false
+        spec = RuntimeContract.own_spec(spec)
+        RuntimeContract.validate_identity!(spec)
+        child = Session.new(store: store, id: spec.fetch("session_id"))
+        spec = RuntimeContract.bind_spec(child.entries, spec)
+        authorized = true
+        direct = { provider: provider, system: system, tools: tools, schema: schema,
+                   agent_options: agent_options.empty? ? UNSET_RUNTIME_FIELD : agent_options }
+        RuntimeContract.validate_resolution!(factory: runtime_factory, direct: direct)
+        signal = AbortSignal.new
+        terminalize = true
+        delivery_owned = true
+        lease = Locks.hold(Child.lease_key(child.id),
+                           stop_key: Child.stop_key(child.id), signal: signal)
+        if Mistri.locks && lease.nil?
+          delivery_owned = false
+          return nil
+        end
+
+        if Child.new(name: spec.fetch("name"), session_id: child.id, store: store).finished?
+          return nil
+        end
+
+        child.append(Child::STARTED, {})
+        RuntimeContract.validate_spec!(spec)
+        signal.abort!("stopped by user") if Mistri.locks&.flag?(Child.stop_key(child.id))
+        unless signal.aborted?
+          runtime = RuntimeContract.resolve(spec, factory: runtime_factory, direct: direct) do
+            factory_failed = true
+          end
+          resolved = RuntimeContract.validate_runtime!(runtime, spec)
+          signal.abort!("stopped by user") if Mistri.locks&.flag?(Child.stop_key(child.id))
+        end
+        result = if signal.aborted?
+                   Result.new(message: nil, status: :aborted)
                  else
-                   agent.run(task, signal: context.signal, &emit)
+                   execute_child(child: child, label: spec.fetch("name"),
+                                 provider: resolved.provider, system: resolved.system,
+                                 tools: resolved.tools, task: spec.fetch("task"),
+                                 schema: resolved.schema, signal: signal, emit: emit,
+                                 lease: lease, started: true,
+                                 agent_options: resolved.agent_options)
                  end
-        answer(result, label, child)
+        deny_pending(result, child)
+        child.append(Child::TERMINAL, terminal(result))
+        result
+      rescue StandardError => e
+        primary_error = e
+        # Completion is a contract even when the runner dies in the
+        # preamble: without this, a raise before the started entry (a lock
+        # backend down, say) would leave the child reading :queued forever,
+        # with nothing to report and nothing for a retry to heal.
+        stopped = factory_failed && child_stop_requested?(child, signal)
+        retryable = factory_failed && retry_factory_errors && !stopped
+        retryable_exit = retryable
+        if child && terminalize && !retryable &&
+           !Child.new(name: spec.fetch("name"), session_id: child.id, store: store).finished?
+          terminal = if stopped
+                       { "status" => "stopped" }
+                     else
+                       { "status" => "failed", "error" => "#{e.class}: #{e.message}" }
+                     end
+          child.append(Child::TERMINAL, terminal)
+        end
+        raise
+      ensure
+        cleanup_error = RuntimeContract.cleanup(runtime)
+        begin
+          report_back(spec, store, emit) if child && authorized && delivery_owned
+        ensure
+          begin
+            Mistri.locks&.clear_flag(Child.stop_key(child.id)) if child && lease && !retryable_exit
+          ensure
+            lease&.release
+          end
+        end
+        raise cleanup_error if cleanup_error && primary_error.nil?
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+      # A child cannot wait for a human, whichever door it entered by: any
+      # calls parked for approval are denied AND settled with the denial as
+      # their tool result, so no approval request stays open on a finished
+      # child and its transcript replays without repair.
+      def deny_pending(result, child)
+        return unless result.awaiting_approval?
+
+        result.pending.each do |call|
+          child.deny(call.id, note: "sub-agents cannot pause for human approval")
+          child.append_message(Message.tool(
+                                 content: "Denied: sub-agents cannot pause for human approval.",
+                                 tool_call_id: call.id, tool_name: call.name, tool_error: true
+                               ))
+        end
+      end
+
+      # Every child ends by writing its own terminal entry: completion is a
+      # contract, and status stays readable from the store forever.
+      def terminal(result)
+        case result.status
+        when :completed then { "status" => "done", "report" => result.text.to_s }
+        when :aborted then { "status" => "stopped" }
+        when :awaiting_approval
+          { "status" => "failed",
+            "error" => "needed human approval, which sub-agents cannot wait for" }
+        else
+          { "status" => "failed", "error" => (result.error_message || result.status).to_s }
+        end
       end
 
       def forbid_gated!(tools)
@@ -134,11 +291,36 @@ module Mistri
 
       private
 
-      def forward(event, origin, context)
-        return unless context.emit
+      def child_stop_requested?(child, signal)
+        return false unless child
+
+        signal&.aborted? || Mistri.locks&.flag?(Child.stop_key(child.id))
+      end
+
+      # A lease-backed runner reports before releasing the child lease. The
+      # report joins the parent's inbox (a typed entry that folds at its next
+      # turn boundary, exactly like a steer) and a :subagent_report event
+      # closes the child's lane in whatever UI watched the spawn. A child
+      # that never ran has nothing to say, and the parent session drops a
+      # sequential duplicate delivery. Without locks, the host must serialize.
+      def report_back(spec, store, emit)
+        facade = Child.new(name: spec.fetch("name"), session_id: spec.fetch("session_id"),
+                           store: store)
+        return unless facade.finished?
 
-        tagged = event.origin ? "#{origin}>#{event.origin}" : origin
-        context.emit.call(event.with(origin: tagged))
+        status = facade.status
+        text = status == :failed ? facade.error : facade.report
+        delivered = if (parent_id = spec["parent_session_id"])
+                      Session.new(store: store, id: parent_id)
+                             .deliver_report(name: facade.name, session_id: facade.session_id,
+                                             status: status.to_s, text: text)
+                    else
+                      true
+                    end
+        return unless delivered
+
+        emit&.call(Event.new(type: :subagent_report, agent: facade.name,
+                             session_id: facade.session_id, status: status, content: text))
       end
 
       # The parent always gets an in-band answer it can react to. A child
@@ -150,68 +332,19 @@ module Mistri
         when :completed
           ToolResult.new(content: result.text.to_s, ui: link)
         when :awaiting_approval
-          result.pending.each do |call|
-            child.deny(call.id, note: "sub-agents cannot pause for human approval")
-          end
+          deny_pending(result, child)
           ToolResult.new(content: "The #{label} sub-agent stopped: it needed human " \
-                                  "approval, which sub-agents cannot wait for.", ui: link)
+                                  "approval, which sub-agents cannot wait for.", ui: link,
+                         error: true)
         when :aborted
-          ToolResult.new(content: "[the #{label} sub-agent was aborted]", ui: link)
+          ToolResult.new(content: "[the #{label} sub-agent was stopped]", ui: link, error: true)
         else
           reason = result.error_message || result.status
-          ToolResult.new(content: "The #{label} sub-agent failed: #{reason}", ui: link)
-        end
-      end
-
-      def pick(pool, names)
-        return pool if names.nil? || names.empty?
-
-        by_name = pool.to_h { |tool| [tool.name, tool] }
-        names.map do |name|
-          by_name.fetch(name) do
-            raise ArgumentError,
-                  "unknown tool #{name.inspect}; available: #{by_name.keys.join(", ")}"
-          end
+          ToolResult.new(content: "The #{label} sub-agent failed: #{reason}", ui: link,
+                         error: true)
         end
       end
 
-      def spawner_schema(pool, models, default)
-        tool_names = pool.map(&:name)
-        fallback = default ? " (default: #{default})" : ""
-        lambda do
-          string :name, "A short name for this worker, shown wherever its events appear"
-          string :task, "The child's complete task", required: true
-          string :instructions, "The child's system prompt", required: true
-          if tool_names.any?
-            array :tools, "Subset of tools to grant (default: all)",
-                  items: { type: "string", enum: tool_names }
-          end
-          string :model, "Model for the child#{fallback}", enum: models if models.any?
-        end
-      end
-
-      def default_model(provider)
-        provider.model if provider.respond_to?(:model)
-      end
-
-      # The label rides origins as "label#id" and joins nesting with ">",
-      # so those separators squeeze to hyphens along with whitespace.
-      def child_label(raw)
-        label = raw.to_s.gsub(/[#>\s]+/, "-").squeeze("-")[0, 32]
-        label = label.delete_prefix("-").delete_suffix("-")
-        label.empty? ? "spawn" : label
-      end
-
-      def child_provider(default, requested, models)
-        return default if requested.nil? || requested.to_s.empty?
-        unless models.include?(requested)
-          raise ArgumentError,
-                "model #{requested.inspect} is not allowed; available: #{models.join(", ")}"
-        end
-
-        Mistri.provider(requested)
-      end
-
       # A predicate gate cannot be judged statically; the runtime denial in
       # answer covers it.
       def statically_gated?(tool)
@@ -222,3 +355,5 @@ module Mistri
     end
   end
 end
+
+require_relative "sub_agent/execution"

data/lib/mistri/task_output.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  # The text side of task mode: how a schema is asked for, how the answer
+  # parses, and how a violation is sent back for a fix. Pure functions over
+  # strings and schemas; Agent#task owns the loop that drives them.
+  module TaskOutput
+    # Distinguishable from a parsed nil: JSON "null" is a valid value.
+    PARSE_FAILED = Object.new.freeze
+    OUTPUT_TOO_LARGE = Object.new.freeze
+    OUTPUT_TOO_COMPLEX = Object.new.freeze
+
+    module_function
+
+    def prompt(input, schema)
+      plan = plan_for(schema)
+      "#{input}\n\nAnswer with ONLY a JSON value matching this schema:\n" \
+        "#{JSON.generate(plan.schema)}"
+    end
+
+    def parse(text)
+      body = text.to_s
+      return OUTPUT_TOO_LARGE if body.bytesize > ToolArguments::MAX_BYTES
+
+      body = body.strip
+      body = body[/\A```(?:json)?\s*(.*?)```\z/m, 1] || body
+      value, error = ToolArguments.parse_json(body)
+      return OUTPUT_TOO_LARGE if error == "too_large"
+      return OUTPUT_TOO_COMPLEX if %w[too_deep too_many_nodes number_too_large].include?(error)
+      return PARSE_FAILED if error
+
+      value
+    end
+
+    def errors(value, schema)
+      return ["the answer exceeds the output byte limit"] if value.equal?(OUTPUT_TOO_LARGE)
+      return ["the answer exceeds the output complexity limit"] if value.equal?(OUTPUT_TOO_COMPLEX)
+      return ["the answer is not valid JSON"] if value.equal?(PARSE_FAILED)
+
+      plan_for(schema).violations(value)
+    end
+
+    def fix_prompt(errors)
+      lines = errors.map { |error| "- #{error}" }.join("\n")
+      "Your answer did not satisfy the required output schema. Problems:\n" \
+        "#{lines}\nReply with ONLY the corrected JSON."
+    end
+
+    def plan_for(schema)
+      return schema if schema.respond_to?(:schema) && schema.respond_to?(:violations)
+
+      Schema.task_plan(schema)
+    end
+    private_class_method :plan_for
+  end
+end

data/lib/mistri/tool.rb

@@ -4,49 +4,81 @@ require "json"
 
 module Mistri
   # A tool the agent can call: a name, a description, a JSON Schema for its
-  # arguments, and a handler. The handler receives the parsed arguments hash
-  # (string keys, exactly as the model sent them) and returns a String, a Hash
-  # (serialized as JSON), or content blocks, so a tool can hand back images as
-  # naturally as text.
+  # arguments, and a handler. Model calls reach the handler as canonical
+  # argument hashes, optionally normalized by the tool before policy sees
+  # them. Trusted direct calls keep ordinary Ruby Hash semantics.
   class Tool
     # A no-argument tool still needs a valid object schema; providers reject a
     # bare empty hash.
-    EMPTY_SCHEMA = { type: "object", properties: {} }.freeze
+    EMPTY_SCHEMA = {
+      type: "object", properties: {}.freeze, required: [].freeze,
+      additionalProperties: false
+    }.freeze
 
     attr_reader :name, :description, :input_schema, :timeout
 
-    # Define a tool. Give the argument shape as a raw JSON Schema hash via
-    # input_schema:, or build it in Ruby with a schema: block.
+    # Define a tool. Give the argument shape as a JSON Schema value via
+    # input_schema:, or build it in Ruby with a schema: block. The result is
+    # canonicalized and owned once so provider and local semantics cannot drift.
     #
     #   Tool.define("get_weather", "Weather for a city",
     #               schema: -> { string :city, "City name", required: true }) do |args|
     #     Weather.for(args["city"])
     #   end
     def self.define(name, description, input_schema: nil, schema: nil, **, &handler)
-      input_schema ||= schema ? Schema.build(&schema) : EMPTY_SCHEMA
+      raise ArgumentError, "choose input_schema or schema, not both" if schema && !input_schema.nil?
+
+      input_schema = schema ? Schema.build(&schema) : EMPTY_SCHEMA if input_schema.nil?
       new(name: name, description: description, input_schema: input_schema, **, &handler)
     end
 
     def initialize(name:, description:, input_schema: EMPTY_SCHEMA, eager_input_streaming: false,
-                   needs_approval: false, timeout: nil, &handler)
+                   needs_approval: false, ends_turn: false, timeout: nil,
+                   argument_normalizer: nil, argument_validator: nil,
+                   complete_argument_validator: nil, &handler)
       raise ArgumentError, "tool #{name.inspect} needs a handler block" unless handler
+      unless argument_normalizer.nil? || argument_normalizer.respond_to?(:call)
+        raise ArgumentError, "argument_normalizer must be callable"
+      end
+      unless argument_validator.nil? || argument_validator.respond_to?(:call)
+        raise ArgumentError, "argument_validator must be callable"
+      end
+      unless complete_argument_validator.nil? || complete_argument_validator.respond_to?(:call)
+        raise ArgumentError, "complete_argument_validator must be callable"
+      end
+      if argument_validator && complete_argument_validator
+        raise ArgumentError,
+              "choose argument_validator or complete_argument_validator, not both"
+      end
 
       @name = name.to_s
       @description = description
-      @input_schema = input_schema
+      @schema_validator = Schema.tool_validator(
+        input_schema, complete: !complete_argument_validator.nil?
+      )
+      @input_schema = @schema_validator.schema
       @eager_input_streaming = eager_input_streaming
       @needs_approval = needs_approval
+      @ends_turn = ends_turn
       @timeout = timeout
+      @argument_normalizer = argument_normalizer
+      @argument_validator = argument_validator
+      @complete_argument_validator = complete_argument_validator
       @handler = handler
     end
 
-    # A handler may return a ToolResult to speak on two channels; its ui
-    # payload is canonicalized through JSON here so the live event and a
-    # reloaded session read the identical shape.
+    # A handler may return a ToolResult to add host-only UI or declare a
+    # model-readable failure. Its ui payload is canonicalized through JSON
+    # here so the live event and a reloaded session read the identical shape.
     #
     # Handlers receive (arguments, context). A proc that declares one
     # parameter ignores the context invisibly; a lambda opts in by arity.
+    # Direct calls are trusted host invocations: they apply the compatibility
+    # normalizer, but do not canonicalize or validate as model calls do. The
+    # executor marks arguments the Agent already prepared so subclasses keep
+    # the historical #call extension point without running normalization twice.
     def call(arguments, context = ToolContext.new)
+      arguments = normalize_arguments(arguments || {}) unless prepared_context?(context)
       result = invoke(arguments || {}, context)
       return serialize_result(result) unless result.is_a?(ToolResult)
 
@@ -54,6 +86,31 @@ module Mistri
                   ui: result.ui && JSON.parse(JSON.generate(result.ui)))
     end
 
+    # Normalization is an explicit per-tool migration boundary, never a
+    # global coercion policy. Agent calls this once before policy; direct
+    # trusted invocations get the same compatibility behavior through #call.
+    def normalize_arguments(arguments)
+      return arguments unless @argument_normalizer
+
+      normalized = @argument_normalizer.call(arguments)
+      raise ArgumentError, "argument_normalizer must return a Hash" unless normalized.is_a?(Hash)
+
+      normalized
+    end
+
+    # Core validation is always authoritative for its portable subset. A
+    # supplemental validator adds domain rules; an explicitly complete one
+    # additionally owns schema interactions core cannot represent.
+    def argument_violations(arguments)
+      validate_arguments(arguments, owned: false)
+    end
+
+    # Agent has already moved the value through ToolCall's ownership boundary,
+    # so its hot path can avoid copying the same immutable JSON twice.
+    def prepared_argument_violations(arguments)
+      validate_arguments(arguments, owned: true)
+    end
+
     # Whether this call should pause for a human. true/false, or a callable
     # given the parsed arguments so a tool can gate only the risky calls
     # (needs_approval: ->(args) { args["amount"].to_i > 100 }).
@@ -61,6 +118,14 @@ module Mistri
       @needs_approval.respond_to?(:call) ? @needs_approval.call(arguments) : @needs_approval
     end
 
+    # A tool that is the last word of its turn: once it executes, the loop
+    # ends the run instead of prompting the model again. This is how a tool
+    # like ask_user hands the floor to a human structurally, with no prompt
+    # discipline required; the answer arrives as the next run's input.
+    def ends_turn?
+      @ends_turn
+    end
+
     # The provider-facing definition; every serializer accepts this shape.
     def spec
       definition = { name: @name, description: @description, input_schema: @input_schema }
@@ -70,6 +135,30 @@ module Mistri
 
     private
 
+    def prepared_context?(context)
+      context.respond_to?(:arguments_prepared?) && context.arguments_prepared?
+    end
+
+    def validate_arguments(arguments, owned:)
+      unless owned
+        arguments, error = ToolArguments.canonicalize(arguments)
+        return ["$ validation limit exceeded"] if ToolArguments.resource_error?(error)
+        return ["$ must be valid JSON"] if error
+      end
+
+      errors = @schema_validator.violations(arguments, owned: true)
+      custom_validator = @complete_argument_validator || @argument_validator
+      return errors if errors.any? || !custom_validator
+
+      custom = custom_validator.call(arguments, @input_schema)
+      unless custom.is_a?(Array) && custom.all?(String)
+        name = @complete_argument_validator ? "complete_argument_validator" : "argument_validator"
+        raise TypeError, "#{name} must return an Array of Strings"
+      end
+
+      custom
+    end
+
     def invoke(arguments, context)
       if @handler.lambda? && @handler.arity.between?(0, 1)
         @handler.arity.zero? ? @handler.call : @handler.call(arguments)