pwn 0.5.739 → 0.5.741

data/lib/pwn/ai/agent/confirmation.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+require 'fileutils'
+require 'time'
+
+module PWN
+  module AI
+    module Agent
+      # Per-engagement ACK for exploit/destructive tool calls (PWN-AI-005 tiers).
+      module Confirmation
+        TIERS = %w[read_only active_scan exploit destructive].freeze
+        DEFAULTS = { 'read_only' => 'auto', 'active_scan' => 'auto', 'exploit' => 'prompt', 'destructive' => 'prompt' }.freeze
+        AUTONOMOUS = { 'read_only' => 'auto', 'active_scan' => 'auto', 'exploit' => 'auto', 'destructive' => 'auto' }.freeze
+
+        public_class_method def self.required_bins
+          []
+        end
+
+        # Classify a tool call into a PWN-AI-005 side-effect tier.
+        public_class_method def self.tier(opts = {})
+          name = opts[:name].to_s
+          args = opts[:args]
+          args = {} unless args.is_a?(Hash)
+          tagged = (args[:side_effect] || args['side_effect']).to_s
+          return tagged if TIERS.include?(tagged)
+          return 'exploit' if name.match?(/exploit|gdb_run_to_crash|fuzz_campaign/)
+          return 'active_scan' if name.match?(/nmap_scan|nuclei_scan|sbom_scan|http_proxy/)
+          return payload_tier(payload: args[:command] || args['command']) if name == 'shell'
+          return payload_tier(payload: args[:code] || args['code']) if name == 'pwn_eval'
+
+          'read_only'
+        end
+
+        # Return an ACK pause hash, or nil when the call may proceed.
+        public_class_method def self.gate(opts = {})
+          name = opts[:name].to_s
+          args = opts[:args]
+          args = {} unless args.is_a?(Hash)
+          klass = tier(name: name, args: args)
+          policy = load_policy(opts)
+          action = (policy[klass] || DEFAULTS[klass] || 'auto').to_s
+          return { success: false, error: "confirmation deny for #{klass}", code: 'ACK_DENY', tier: klass } if action == 'deny'
+          return nil unless action == 'prompt'
+
+          eng = engagement_id(opts.merge(args: args))
+          return nil if acked?(engagement_id: eng)
+
+          if truthy?(value: opts[:operator_ack] || args[:operator_ack] || args['operator_ack'])
+            persist_ack(engagement_id: eng)
+            return nil
+          end
+          {
+            success: false,
+            needs_ack: true,
+            code: 'ACK_REQUIRED',
+            tier: klass,
+            engagement_id: eng,
+            diff: intended_diff(name: name, args: args, tier: klass),
+            error: "operator ACK required for #{klass}-tier tool call"
+          }
+        end
+
+        public_class_method def self.authors
+          "AUTHOR(S):\n  0day Inc. <support@0dayinc.com>\n"
+        end
+
+        public_class_method def self.help
+          puts "USAGE:
+            # List host binaries this module expects to be installed.
+            #{self}.required_bins
+
+            # Classify a tool call into a PWN-AI-005 side-effect tier.
+            #{self}.tier(
+              name: 'required - registry tool name',
+              args: 'optional - Hash of tool arguments'
+            )
+
+            # Return an ACK pause hash, or nil when the call may proceed.
+            #{self}.gate(
+              name: 'required - registry tool name',
+              args: 'optional - Hash of tool arguments',
+              engagement_id: 'optional - engagement id used to cache the ACK',
+              operator_ack: 'optional - true records a one-time ACK for this engagement',
+              scope_path: 'optional - scope.yaml path; defaults to ~/.pwn/scope.yaml'
+            )
+
+            # Print the AUTHOR(S) string for this module.
+            #{self}.authors
+          "
+          constants.sort
+        end
+
+        private_class_method def self.payload_tier(opts = {})
+          kind = PWN::Plugins::AISandbox.classify(payload: opts[:payload].to_s)
+          case kind.to_s
+          when 'write' then 'destructive'
+          when 'network' then 'active_scan'
+          else 'read_only'
+          end
+        end
+
+        private_class_method def self.engagement_id(opts = {})
+          args = opts[:args]
+          args = {} unless args.is_a?(Hash)
+          value = (opts[:engagement_id] || args[:engagement_id] || args['engagement_id'] || 'default').to_s
+          value = 'default' if value.empty?
+          raise ArgumentError, 'engagement_id must be a simple identifier' unless value.match?(/\A[a-zA-Z0-9_-]+\z/)
+
+          value
+        end
+
+        private_class_method def self.load_policy(opts = {})
+          path = opts[:scope_path].to_s
+          path = File.join(Dir.home, '.pwn', 'scope.yaml') if path.empty?
+          return AUTONOMOUS unless File.file?(path)
+
+          doc = YAML.safe_load_file(path, permitted_classes: [], aliases: false) || {}
+          return AUTONOMOUS unless doc.is_a?(Hash)
+
+          conf = doc['confirmation'] || doc[:confirmation] || {}
+          return AUTONOMOUS unless conf.is_a?(Hash) && !conf.empty?
+
+          DEFAULTS.merge(conf.transform_keys(&:to_s))
+        rescue StandardError
+          AUTONOMOUS
+        end
+
+        private_class_method def self.ack_path(opts = {})
+          File.join(Dir.home, '.pwn', 'engagements', engagement_id(opts), 'acks.json')
+        end
+
+        private_class_method def self.acked?(opts = {})
+          path = ack_path(opts)
+          return false unless File.file?(path)
+
+          JSON.parse(File.read(path))['ack'] == true
+        rescue StandardError
+          false
+        end
+
+        private_class_method def self.persist_ack(opts = {})
+          path = ack_path(opts)
+          FileUtils.mkdir_p(File.dirname(path))
+          File.write(path, JSON.generate(ack: true, at: Time.now.utc.iso8601))
+          File.chmod(0o600, path)
+        end
+
+        private_class_method def self.truthy?(opts = {})
+          [true, 'true', 1, '1'].include?(opts[:value])
+        end
+
+        private_class_method def self.intended_diff(opts = {})
+          name = opts[:name]
+          tier = opts[:tier]
+          args = JSON.generate(opts[:args] || {})
+          "+ tool: #{name}\n+ tier: #{tier}\n+ args: #{args}"
+        end
+      end
+    end
+  end
+end

data/lib/pwn/ai/agent/dispatch.rb

@@ -4,6 +4,7 @@ require 'json'
 require 'digest'
 require 'json_schemer'
 require 'securerandom'
+require 'base64'
 require 'pwn/ai/agent/tool_guard'
 require 'pwn/ai/agent/manifest'
 
@@ -57,10 +58,12 @@ module PWN
           schema = { allOf: [schema, declaration['params']] } if declaration
           if raw.nil?
             required = Array(schema[:required] || schema['required']).map(&:to_s)
-            return JSON.generate(success: false, error: 'invalid_payload', code: 'SCHEMA_DENY') if required.any? { |key| !ToolGuard.present?(value: args[key.to_sym] || args[key]) }
+            missing = required.reject { |key| ToolGuard.present?(value: args[key.to_sym] || args[key]) }
+            return schema_denial(type: 'required', error: "Supply required fields: #{missing.join(', ')}") unless missing.empty?
           end
           type_schema = drop_required(node: schema)
-          return JSON.generate(success: false, error: 'invalid_payload', code: 'SCHEMA_DENY') unless args.is_a?(Hash) && JSONSchemer.schema(JSON.parse(JSON.generate(type_schema))).valid?(JSON.parse(JSON.generate(args)))
+          violation = JSONSchemer.schema(JSON.parse(JSON.generate(type_schema))).validate(JSON.parse(JSON.generate(args))).first
+          return schema_denial(violation.transform_keys(&:to_sym)) if violation
 
           blob = args.inspect
           if defined?(PWN::Plugins::Vault)
@@ -100,6 +103,15 @@ module PWN
               code: 'CAP_DENY'
             )
           end
+          ack = Confirmation.gate(
+            name: entry.name,
+            args: args,
+            engagement_id: opts[:engagement_id] || args[:engagement_id] || args['engagement_id'],
+            operator_ack: opts[:operator_ack] || args[:operator_ack] || args['operator_ack'],
+            scope_path: opts[:scope_path]
+          )
+          return JSON.generate(ack) if ack
+
           budget = prepare_budget(opts.merge(entry: entry, args: args))
           return JSON.generate(budget[:denial]) if budget && budget[:denial]
 
@@ -111,6 +123,7 @@ module PWN
             raise
           end
           telemetry = finish_budget(budget: budget, result: result, elapsed: Process.clock_gettime(Process::CLOCK_MONOTONIC) - started)
+          result = Result.page(value: result, entry: entry, session_id: opts[:session_id])
           result = ToolGuard.quarantine_output(text: result) if defined?(ToolGuard) && result.is_a?(String) && ToolGuard.respond_to?(:quarantine_output)
           note_taint(text: result)
           if defined?(PWN::Plugins::Vault) && result.is_a?(String)
@@ -169,13 +182,32 @@ module PWN
           nil
         end
 
+        private_class_method def self.schema_denial(opts = {})
+          pointer = opts[:data_pointer].to_s
+          message = opts[:error].to_s
+          data = opts[:data]
+          # Schema failures identify a JSON field, not a span of command bytes.
+          # Do not echo whole argument objects (which may contain credentials).
+          token = data.to_s unless data.nil? || data.is_a?(Hash) || data.is_a?(Array)
+          denial = ToolGuard.invalid_payload(
+            code: 'SCHEMA_DENY', rule_id: "schema.#{opts[:type]}",
+            match: token, hint: message,
+            remedy: "Correct #{pointer.empty? ? 'the tool arguments' : pointer}: #{message}. Resubmit arguments matching the advertised JSON schema."
+          )
+          JSON.generate(denial.merge(success: false, data_pointer: pointer))
+        end
+
         # Caller owns task lifecycle. Fallback is thread-local, never process-global.
         private_class_method def self.prepare_budget(opts = {})
           entry = opts[:entry]
+          args = opts[:args]
+          if entry.name == 'shell' && (args[:background] == true || (!args.key?(:timeout) && ToolGuard.auto_job?(payload: args[:command].to_s)))
+            args[:background] = true
+            return nil
+          end
           schema = JSON.parse(JSON.generate(entry.schema))
           return nil unless schema.dig('parameters', 'properties', 'timeout')
 
-          args = opts[:args]
           ledger = opts[:budget_ledger] || (Thread.current[:pwn_dispatch_budget] ||= {})
           chains = ledger[:chains] ||= {}
           key = opts[:budget_key] || entry.name
@@ -496,7 +528,10 @@ module PWN
           args = opts[:args]
           args = JSON.parse(args, symbolize_names: true) if args.is_a?(String) && args.strip.start_with?('{')
           case args
-          when Hash then args.values.join(' ')
+          when Hash
+            return Base64.strict_decode64((args[:data] || args['data']).to_s) if (args[:encoding] || args['encoding']).to_s == 'base64'
+
+            args.values.join(' ')
           else args.to_s
           end
         rescue StandardError
@@ -573,8 +608,11 @@ module PWN
               budget_key: 'optional - trusted approach identifier; defaults to tool name',
               scope_policy: 'optional - trusted policy Hash',
               scope_path: 'optional - trusted scope file path',
+              session_id: 'optional - session directory for oversized result artifacts',
               audit_path: 'optional - trusted audit JSONL path',
-              approval_callback: 'optional - trusted callback for prompt risk gates'
+              approval_callback: 'optional - trusted callback for prompt risk gates',
+              engagement_id: 'optional - engagement id used to cache exploit/destructive ACK',
+              operator_ack: 'optional - true records a one-time ACK for this engagement'
             )
 
             # Run repair name and return its result

data/lib/pwn/ai/agent/loop.rb

@@ -67,7 +67,7 @@ module PWN
         public_class_method def self.evidence_satisfied?(opts = {})
           messages = Array(opts[:messages] || opts[:trace])
           text = opts[:text].to_s
-          return false if TurnFinalizer.output_paths(request: opts[:request]).any? && completion_unmet(request: opts[:request], messages: messages).any?
+          return false if TurnFinalizer.required_artifacts(request: opts[:request]).any? && completion_unmet(request: opts[:request], messages: messages).any?
 
           if defined?(TurnFinalizer) && TurnFinalizer.respond_to?(:arbitrate)
             row = TurnFinalizer.arbitrate(request: opts[:request].to_s, messages: messages, paths: [])
@@ -783,7 +783,7 @@ module PWN
         end
 
         private_class_method def self.declared_contract(opts = {})
-          literals = TurnFinalizer.output_paths(request: opts[:request])
+          literals = TurnFinalizer.required_artifacts(request: opts[:request])
           cached = Thread.current[:pwn_loop_deliverables]
           contract = if cached.is_a?(Array) || cached.is_a?(Hash)
                        normalize_contract(raw: cached)
@@ -908,7 +908,7 @@ module PWN
         end
 
         private_class_method def self.may_finalize?(opts = {})
-          paths = TurnFinalizer.output_paths(request: opts[:request])
+          paths = TurnFinalizer.required_artifacts(request: opts[:request])
           if paths.any?
             artifact = TurnFinalizer.arbitrate(request: opts[:request], paths: paths, messages: opts[:messages])
             unless artifact[:complete]
@@ -1177,7 +1177,7 @@ module PWN
               shape = :timeout
             end
             m = Mistakes.record(tool: name, error: err, args: opts[:args], session_id: opts[:session_id], source: :tool, cause: cause, shape: shape)
-            m = Mistakes.extinguish!(signature: m[:signature], args: opts[:args], shape: sem[:shape]) || m if m && defined?(Mistakes) && Mistakes.respond_to?(:extinguish!)
+            m = Mistakes.extinguish!(signature: m[:signature], args: opts[:args], shape: sem[:shape]) || m if m && defined?(Mistakes) && Mistakes.respond_to?(:extinguish!) && !retryable_execution_failure?(raw: raw)
           end
           { ok: sem[:semantic_ok], err: sem[:err], mistake: m, benign: sem[:benign] }
         rescue StandardError
@@ -1330,6 +1330,33 @@ module PWN
           counts[sig]
         end
 
+        # Only trusted structured execution outcomes grant the retry exemption.
+        # Checkpoint/policy/budget denials are not failed command executions.
+        private_class_method def self.retryable_execution_failure?(opts = {})
+          raw = opts[:raw]
+          data = raw.is_a?(Hash) ? raw : JSON.parse(raw.to_s)
+          return false unless data.is_a?(Hash)
+
+          data = data.transform_keys(&:to_s)
+          return false if data['checkpoint'] || data['denied'] || data['code'] || %w[retry_required budget_exhausted].include?(data['error'])
+
+          result = data['result'].is_a?(Hash) ? data['result'].transform_keys(&:to_s) : {}
+          [data, result].any? do |row|
+            row['timed_out'] == true || row['error'].to_s.match?(/\A(?:Timeout::Error:|timeout\b)/i) ||
+              %w[exit exit_code exit_status].any? { |key| row[key].to_s.match?(/\A-?\d+\z/) && !row[key].to_i.zero? }
+          end
+        rescue JSON::ParserError
+          false
+        end
+
+        private_class_method def self.note_payload_result!(opts = {})
+          return unless retryable_execution_failure?(raw: opts[:raw])
+
+          sig = payload_sig(opts)
+          Thread.current[:pwn_same_payload]&.delete(sig)
+          Thread.current[:pwn_extinguished]&.delete(sig)
+        end
+
         private_class_method def self.read_like?(opts = {})
           name = opts[:name].to_s
           return true if name.match?(/_(read|get|list|status|recall|tail)\z/)
@@ -1365,6 +1392,7 @@ module PWN
           hint   = opts[:hint].to_s
           thresh = defined?(Mistakes) ? Mistakes::REPEAT_THRESHOLD : 3
           result = "#{result}\n#{hint}" unless hint.empty?
+          return result if retryable_execution_failure?(raw: opts[:raw] || opts[:result])
           return result if count < thresh
 
           if defined?(Mistakes) && Mistakes.respond_to?(:extinguish!)
@@ -2832,6 +2860,7 @@ module PWN
         # )
 
         public_class_method def self.run(opts = {})
+          prior_artifact_contract = Thread.current[:pwn_artifact_contract]
           request = opts[:request].to_s
           session_id = opts[:session_id]
           on_tool = opts[:on_tool]
@@ -2869,6 +2898,8 @@ module PWN
             OpenGoal.begin!(request: request, session_id: session_id)
           end
           Thread.current[:pwn_request_intent] = intent
+          TurnFinalizer.commit_artifacts!(request: request, inherit: nested)
+          required_artifacts = TurnFinalizer.required_artifacts(request: request)
           Thread.current[:pwn_extinguished] = {}
           Thread.current[:pwn_same_payload] = Hash.new(0)
           Thread.current[:pwn_loop_t0] = Time.now unless nested
@@ -2880,9 +2911,10 @@ module PWN
           expose_current_session(session_id: session_id)
           Mistakes.check_user_correction(request: request, session_id: session_id) if defined?(Mistakes)
 
-          cheap = opts[:force_tools] != true && %i[greeting howto recall].include?(intent)
+          allow_text_only = required_artifacts.empty? && opts[:force_tools] != true
+          cheap = allow_text_only && %i[greeting howto recall].include?(intent)
 
-          if intent == :greeting && opts[:force_tools] != true
+          if allow_text_only && intent == :greeting
             debug_progress(msg: 'path=greeting', debug: opts[:debug])
             quiet_debug_tui!(debug: opts[:debug], reason: 'greeting')
             txt = answer_greeting(
@@ -3242,7 +3274,7 @@ module PWN
               argv_s = args.is_a?(String) ? args.to_s : args.inspect
               debug_progress(msg: "tool #{name} start:\n#{argv_s}", keep_newlines: true, cap: 0, tee: nil)
               sig = payload_sig(name: name, args: args)
-              declared_paths = TurnFinalizer.output_paths(request: request)
+              declared_paths = required_artifacts
               arg_paths = tool_arg_paths(args: args)
               watch_paths = (declared_paths + arg_paths).uniq
               before_host = TurnFinalizer.artifact_snapshot(paths: watch_paths)
@@ -3254,9 +3286,10 @@ module PWN
                 raw = if same_n >= 3
                         checkpoint_result(name: name, args: args)
                       else
-                        Dispatch.call(tool_call: tc)
+                        Dispatch.call(tool_call: tc, session_id: session_id)
                       end
               end
+              note_payload_result!(name: name, args: args, raw: raw)
               tools_called += 1
               if opts[:verification_contract]
                 after_artifacts = Verification.snapshot(opts[:verification_contract])
@@ -3265,7 +3298,7 @@ module PWN
               end
               tele    = record_metrics(name: name, action_id: tc[:id], trusted_context: Policy.current_episode&.dig(:trusted_context) || trusted_context,
                                        started: started, raw: raw, args: args, session_id: session_id, engine: engine, ts_state: ts_state)
-              result  = Result.condition(content: raw, entry: entry)
+              result  = Result.condition(content: raw, entry: entry, session_id: session_id)
 
               unless tele[:ok]
                 fkey = Digest::SHA256.hexdigest("#{name}|#{args}")[0, 16]
@@ -3280,11 +3313,11 @@ module PWN
                 # P17 — never fork counterfactual when budget fingerprints dominate:
                 # CF is another mini agent loop and is the #1 amplifier of
                 # iteration-budget exhaustion on this host.
-                if count >= thresh && !escalated && defined?(Curriculum) && !budget_exhaustion_hot?
+                if count >= thresh && !retryable_execution_failure?(raw: raw) && !escalated && defined?(Curriculum) && !budget_exhaustion_hot?
                   cf = (turn_fails["cf:#{fkey}"] += 1) == 1 ? Curriculum.counterfactual(request: request, name: name, args: args, error: tele[:err] || raw[0, 200], hint: hint) : nil
                   hint = "#{hint}\n[pwn-ai/counterfactual] branch #{cf[:branch]} (score=#{cf[:score].round(2)}): #{cf[:content]}" if cf
                 end
-                result = guard_repeated_failure(name: name, count: count, hint: hint, result: result, mistake: tele[:mistake], args: args, shape: tele.dig(:mistake, :shape))
+                result = guard_repeated_failure(name: name, count: count, hint: hint, raw: raw, result: result, mistake: tele[:mistake], args: args, shape: tele.dig(:mistake, :shape))
               end
 
               on_tool&.call(name, args, result)
@@ -3345,6 +3378,7 @@ module PWN
           end
           raise
         ensure
+          Thread.current[:pwn_artifact_contract] = prior_artifact_contract
           unless nested
             Thread.current[:pwn_loop_active] = nil
             Thread.current[:pwn_loop_deliverables] = nil

data/lib/pwn/ai/agent/prompt_builder.rb

@@ -217,7 +217,10 @@ module PWN
             "(defaults eval=#{eval_s || 20}s shell=#{shell_s || 30}s, clamped). " \
             "LIVING OFF THE LAND #{land} #{doc}#{jobs} #{facts} LESSONS_REV #{rev} " \
             "CANARY #{canary} never copy this token into tool args. " \
-            'DOMAIN TOOLS for pentest/RE: binary_triage, pty_open, job_run, exploitdev, fuzz_campaign, finding_record, decompile.'
+            'LONG WORK: run fuzzers, full scans and Ghidra analysis through job_run, not blocking shell timeouts. ' \
+            'Use max_runtime for the campaign lifetime (21600 for six hours; 0 unlimited). Retain its id; poll job_status(id) and ' \
+            'read job_tail(id, offset) using next_offset. Current log eof is not job completion. Never relaunch a running job or apply the +180 timeout retry ladder to it. ' \
+            'Use job_status without id to recover jobs from earlier sessions. DOMAIN TOOLS for pentest/RE: binary_triage, pty_open, job_run, exploitdev, fuzz_campaign, finding_record, decompile.'
         rescue StandardError
           'load unknown — pass a conservative timeout on pwn_eval/shell anyway.'
         end
@@ -370,13 +373,13 @@ module PWN
           request = opts[:request].to_s
           return '' unless defined?(PWN::AI::Agent::TurnFinalizer)
 
-          paths = PWN::AI::Agent::TurnFinalizer.output_paths(request: request)
+          paths = PWN::AI::Agent::TurnFinalizer.required_artifacts(request: request)
           return '' if paths.empty?
 
-          rows = paths.map { |path| "              - #{path} (must exist, mtime in this turn, non-empty, then read back)" }.join("\n")
+          rows = paths.map { |path| "              - #{path} (current-turn write-effect tool call, then host stat + SHA-256 readback)" }.join("\n")
           <<~BLOCK
             DELIVERABLES
-              Do not finalize until every path below exists with a fresh mtime and non-trivial size:
+              Required artifacts are precommitted. Do not finalize until every path below has a verified current-turn write, fresh mtime, non-trivial size, and stat + SHA-256 readback:
             #{rows}
 
           BLOCK

data/lib/pwn/ai/agent/registry.rb

@@ -43,7 +43,8 @@ module PWN
 
         CORE_TOOLS = %w[memory_recall session_recall skills_recall pwn_eval shell
                         mistakes_record mistakes_resolve learning_note_outcome
-                        memory_remember skills_update].freeze
+                        memory_remember skills_update artifact_read artifact_grep
+                        job_run job_status job_tail job_result job_kill].freeze
 
         # Schema order = CORE_TOOLS. Current session is injected (RECENT TURNS).
         # Then memory / prior sessions / skills, then pwn_eval before shell.

data/lib/pwn/ai/agent/result.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
+require 'json'
+require 'base64'
+
 module PWN
   module AI
     module Agent
       # Conditioning applied to every tool result before it re-enters the
-      # conversation as a role:'tool' message: hard size cap + credential
+      # conversation as a role:'tool' message: lossless paging + credential
       # redaction. Keeps the context window bounded and avoids leaking
       # PWN::Env credentials back into the model.
       module Result
@@ -36,13 +39,66 @@ module PWN
 
         public_class_method def self.condition(opts = {})
           content = opts[:content].to_s
-          entry   = opts[:entry]
-          cap     = entry ? entry.max_chars : default_max
-
-          content = "#{content[0, cap]}…[truncated #{opts[:content].to_s.length - cap} chars]" if content.length > cap
+          content = JSON.generate(spill_summary(content: content, session_id: opts[:session_id])) if content.bytesize > token_limit(entry: opts[:entry]) || !content.dup.force_encoding('UTF-8').valid_encoding?
           redact(content: content)
         end
 
+        # Preserve the original handler result before redaction/quarantine.
+        public_class_method def self.page(opts = {})
+          value = opts[:value]
+          safe_value = value.is_a?(String) ? value : transport_value(value: value)
+          content = value.is_a?(String) ? value : JSON.generate(safe_value)
+          return safe_value if content.bytesize <= token_limit(entry: opts[:entry]) && content.dup.force_encoding('UTF-8').valid_encoding?
+
+          summary = spill_summary(content: content, session_id: opts[:session_id])
+          summary[:serialization] = value.is_a?(String) ? 'raw' : 'json (binary strings use encoding/base64 wrappers)'
+          if value.is_a?(Hash)
+            %w[success ok exit exit_code exit_status timed_out error code].each do |key|
+              next unless value.key?(key.to_sym) || value.key?(key)
+
+              field = value.key?(key.to_sym) ? value[key.to_sym] : value[key]
+              summary[key.to_sym] = field if [true, false, nil].include?(field) || field.is_a?(Numeric) || (field.is_a?(String) && field.bytesize <= 128)
+            end
+          end
+          summary
+        end
+
+        # A byte is a conservative token upper bound; never assume four bytes
+        # per token for arbitrary strings/hex/binary dumps. No tokenizer needed.
+        public_class_method def self.token_limit(opts = {})
+          configured = PWN::Env.dig(:ai, :agent, :artifact_max_tokens).to_i if defined?(PWN::Env)
+          limit = configured.to_i.positive? ? configured : default_max / 4
+          cap = opts[:entry]&.max_chars.to_i
+          limit = [limit, cap].min if cap.positive?
+          [limit, 1024].max
+        end
+
+        # Reserve room for JSON escaping, metadata, and the dispatch envelope.
+        public_class_method def self.page_length
+          ((token_limit - 768) / 8).clamp(32, 2048)
+        end
+
+        private_class_method def self.spill_summary(opts = {})
+          content = opts[:content]
+          artifact = PWN::Plugins::ArtifactRegistry.spill(bytes: content, session_id: opts[:session_id] || Thread.current[:pwn_session_id] || 'default')
+          {
+            artifact: artifact,
+            summary: 'Full result saved without truncation. Use artifact_read(handle, offset, length) or artifact_grep(handle, regex); offsets are bytes.',
+            preview: redact(content: content.byteslice(0, 32).to_s.dup.force_encoding('UTF-8').scrub)
+          }
+        end
+
+        private_class_method def self.transport_value(opts = {})
+          value = opts[:value]
+          case value
+          when Hash then value.transform_values { |v| transport_value(value: v) }
+          when Array then value.map { |v| transport_value(value: v) }
+          when String
+            value.dup.force_encoding('UTF-8').valid_encoding? ? value.dup.force_encoding('UTF-8') : { encoding: 'base64', body: Base64.strict_encode64(value) }
+          else value
+          end
+        end
+
         # Engine-aware default: ollama keeps history inside a tight num_ctx;
         # a 24k tool dump on every call eats the window before useful work.
         # Override via PWN::Env[:ai][:ollama][:result_max].
@@ -109,9 +165,23 @@ module PWN
             # Run condition and return its result
             #{self}.condition(
               content: 'required - String returned by Dispatch.call',
-              entry: 'optional - Registry::Entry (used for max_chars; nil → DEFAULT_MAX)'
+              entry: 'optional - Registry::Entry (used for max_chars; nil → DEFAULT_MAX)',
+              session_id: 'optional - session directory used for lossless spilled results'
             )
 
+            # Preserve oversized handler results before redaction or quarantine.
+            #{self}.page(
+              value: 'required - original tool handler result to condition',
+              entry: 'optional - registry entry with an inline size cap',
+              session_id: 'optional - session directory for the saved result'
+            )
+
+            # Conservative byte-based token bound, configurable through ai.agent.artifact_max_tokens.
+            #{self}.token_limit(entry: 'optional - registry entry imposing a smaller cap')
+
+            # Maximum page bytes with space reserved for response metadata.
+            #{self}.page_length
+
             # Engine-aware default: ollama keeps history inside a tight num_ctx;
             #{self}.default_max