pwn 0.5.719 → 0.5.721

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

@@ -99,9 +99,32 @@ module PWN
             bump(bucket: e, success: success, duration: duration, error: error)
           end
           save(metrics: metrics)
+          append_jsonl(opts.merge(name: name, success: success, duration: duration, error: error, engine: engine))
           t
         end
 
+        public_class_method def self.append_jsonl(opts = {})
+          path = File.join(Dir.home, '.pwn', 'logs', 'tool_metrics.jsonl')
+          FileUtils.mkdir_p(File.dirname(path))
+          row = {
+            ts: Time.now.utc.iso8601,
+            session: Thread.current[:pwn_session_id],
+            tool: opts[:name],
+            latency_ms: (opts[:duration].to_f * 1000).round,
+            timeout_used: opts[:timeout],
+            outcome: opts[:success] ? 'ok' : 'err',
+            error_class: opts[:error].to_s.split(':').first,
+            bytes_out: opts[:bytes_out].to_i
+          }
+          File.open(path, 'a') do |f|
+            f.flock(File::LOCK_EX)
+            f.puts(JSON.generate(row))
+          end
+          row
+        rescue StandardError
+          nil
+        end
+
         # Supported Method Parameters::
         # rows = PWN::AI::Agent::Metrics.summary(
         #   limit: 'optional - cap number of tools returned (default 25)',
@@ -664,11 +687,22 @@ module PWN
             #{self}.record(
               name: 'required - tool name that was dispatched',
               success: 'required - Boolean, did the handler complete without error',
-              duration: 'optional - Float seconds the dispatch took',
+              duration: 'optional - Float seconds the dispatch took (wall time)',
               error: 'optional - String error message when success is false',
               engine: 'optional - Symbol/String AI engine that chose this tool (segments telemetry)'
             )
 
+            # Append one JSONL telemetry row under ~/.pwn/logs/tool_metrics.jsonl.
+            #{self}.append_jsonl(
+              name: 'required - tool name',
+              success: 'optional - Boolean outcome',
+              duration: 'optional - Float seconds the dispatch took (wall time)',
+              error: 'optional - error string',
+              engine: 'optional - engine name',
+              timeout: 'optional - timeout used',
+              bytes_out: 'optional - output byte count'
+            )
+
             # Run summary and return its result
             #{self}.summary(
               limit: 'optional - cap number of tools returned (default 25)',

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

@@ -113,6 +113,7 @@ module PWN
         # )
 
         public_class_method def self.definitions(opts = {})
+          eager_load!
           enabled = opts[:enabled]
           enabled = enabled.map(&:to_s) if enabled
           pool = @entries.values.select { |e| (enabled.nil? || enabled.include?(e.toolset)) && safe_check(entry: e) }
@@ -296,6 +297,10 @@ module PWN
         # )
 
         public_class_method def self.discover(opts = {})
+          eager_load!(opts)
+        end
+
+        public_class_method def self.eager_load!(opts = {})
           force = opts[:force] ||= false
           return @entries.keys if @discovered && !force
 
@@ -311,6 +316,19 @@ module PWN
           @entries.keys
         end
 
+        public_class_method def self.selftest(opts = {})
+          _dry = opts[:dry_run]
+          eager_load!
+          tools_dir = File.join(__dir__, 'tools')
+          files = Dir[File.join(tools_dir, '*.rb')]
+          rows = @entries.map do |name, e|
+            schema = e.schema.is_a?(Hash)
+            required = Array(e.schema&.dig(:parameters, :required) || e.schema&.dig('parameters', 'required'))
+            { name: name, schema_valid: schema, handler: !e.handler.nil?, required: required }
+          end
+          { tools: rows, files: files.length, registered: @entries.length, ok: rows.length >= files.length }
+        end
+
         private_class_method def self.safe_check(opts = {})
           entry = opts[:entry]
           entry.check.call
@@ -428,6 +446,16 @@ module PWN
               force: 'optional - re-require tool files even if already discovered (default false)'
             )
 
+            # Eager-load every tools/*.rb so Registry.definitions works in a cold REPL.
+            #{self}.eager_load!(
+              force: 'optional - re-require tool files even if already discovered (default false)'
+            )
+
+            # Schema/handler contract check for every registered tool.
+            #{self}.selftest(
+              dry_run: 'optional - reserved dry-run flag'
+            )
+
             # Print the AUTHOR(S) string for this module.
             #{self}.authors
           "

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

@@ -177,22 +177,37 @@ module PWN
             v[:confidence] = [v[:confidence].to_f, ground[:confidence].to_f].max if ground[:confidence]
           end
 
-          v[:success] = promote_to_success?(
-            orm: v[:source].to_s != 'heuristic' && v[:score].to_f >= 0.6,
-            verify: if ground.nil?
-                      nil
-                    else
-                      ground[:verdict] == :confirmed
-                    end,
-            critic: opts.key?(:critic_pass) ? opts[:critic_pass] : nil
-          )
+          pass = final.match?(/\bPASS\b/) && !(defined?(Learning) && final.match?(Learning::FAILURE_FINAL_RX))
+          v[:judge_score] = v[:score].to_f
+          vv = opts[:verifier_verdict]
+          vv = :pass if vv.nil? && (opts[:verifier_pass] == true || pass || (ground && ground[:verdict] == :confirmed))
+          vv = vv.to_s.to_sym if vv
+          v[:verifier_verdict] = vv
+          v[:verdict_class] = taxonomy_class(opts.merge(score: v[:score], verifier_verdict: vv, request: request, final: final))
+          v[:remediation_hint] = taxonomy_hint(verdict_class: v[:verdict_class])
+          prec = verifier_precedence?
+          if prec && vv == :pass
+            v[:success] = true
+          else
+            v[:success] = promote_to_success?(
+              orm: v[:source].to_s != 'heuristic' && v[:score].to_f >= 0.6,
+              verify: if ground.nil?
+                        nil
+                      else
+                        ground[:verdict] == :confirmed
+                      end,
+              critic: opts.key?(:critic_pass) ? opts[:critic_pass] : nil
+            )
+          end
           v[:needs_spot_check] = v[:success] && v[:score].to_f >= 0.85 && (rand < 0.05)
           v[:engine] = eng
-          pass = final.match?(/\bPASS\b/) && !(defined?(Learning) && final.match?(Learning::FAILURE_FINAL_RX))
           v[:task_class] = request.match?(/analy[sz]e|summar|strength|weakness|fitness/i) ? 'analysis' : 'operational'
           if pass
-            v[:score] = [v[:score].to_f, 0.7].max
-            v[:score] = [v[:score].to_f, 0.70].min
+            score = v[:score].to_f
+            v[:score] = [score, 0.6].max
+            v[:success] = true if prec
+            v[:verifier_verdict] ||= :pass
+            v[:verdict] = :solved
           end
           v[:score_components] ||= {
             judge: v[:score].to_f,
@@ -201,7 +216,16 @@ module PWN
             weights: { overlap: pass ? 0.0 : 0.15 }
           }
           v[:score_components][:weights][:overlap] = 0.0 if pass
-          Learning.note_outcome(task: request[0, 80], success: v[:score].to_f >= 0.6, score: v[:score], details: v[:score_components].to_json) if commit && defined?(Learning) && opts[:persist_components]
+          if commit && defined?(Learning) && opts[:persist_components]
+            Learning.note_outcome(
+              task: request[0, 80],
+              success: v[:success],
+              score: v[:score],
+              details: v[:score_components].to_json,
+              verifier_verdict: v[:verifier_verdict],
+              verdict_class: v[:verdict_class]
+            )
+          end
           # W3 — write Brier on every judged turn so overconfidence can
           # throttle max_iters/critic even when plan_first never fired.
           if commit
@@ -1076,7 +1100,7 @@ module PWN
         CHEAP_ORM_TEMP    = 0.1
         CHEAP_ORM_TRACE_N = 12
         ORM_SAMPLE_WEIGHT = 1.0
-        HEURISTIC_SAMPLE_WEIGHT = 0.25
+        HEURISTIC_SAMPLE_WEIGHT = 0.45
         ERROR_SAMPLE_WEIGHT = 0.15
         ENGINE_CHAT_MODS = {
           openai: 'PWN::AI::OpenAI',
@@ -1254,6 +1278,45 @@ module PWN
           false
         end
 
+        private_class_method def self.verifier_precedence?(opts = {})
+          return true unless opts.is_a?(Hash)
+          return true unless defined?(PWN::Env)
+
+          v = PWN::Env.dig(:ai, :reward, :verifier_precedence)
+          v != false
+        rescue StandardError
+          true
+        end
+
+        private_class_method def self.taxonomy_class(opts = {})
+          given = (opts[:verdict_class] || opts['verdict_class']).to_s
+          return given unless given.empty?
+
+          vv = opts[:verifier_verdict]
+          score = opts[:score].to_f
+          final = opts[:final].to_s
+          request = opts[:request].to_s
+          return 'unverified_claim' if vv == :pass && score < 0.6
+          return 'missing_artifact' if request.match?(%r{/(?:tmp|home|opt|var)/}) && !final.match?(%r{/(?:tmp|home|opt|var)/})
+          return 'wrong_path' if request.include?('/tmp/') && final.include?('/tmp/') && request.split.none? { |tok| tok.start_with?('/') && final.include?(tok) }
+          return 'scope_miss' if final.match?(/out of scope|SCOPE_DENY/i)
+          return 'partial_coverage' if score.between?(0.3, 0.59)
+          return 'style_only' if score >= 0.6 && Array(opts[:trace]).empty?
+
+          'unverified_claim'
+        end
+
+        private_class_method def self.taxonomy_hint(opts = {})
+          {
+            'missing_artifact' => 'Write the requested path then read it back.',
+            'wrong_path' => 'Use the absolute path named in the original request.',
+            'unverified_claim' => 'Add a verifier PASS (file readback, exit 0, or hash match).',
+            'scope_miss' => 'Stay inside the active engagement scope.',
+            'partial_coverage' => 'Finish remaining request clauses before claiming done.',
+            'style_only' => 'Produce a host-visible artifact, not prose restyling.'
+          }[opts[:verdict_class].to_s] || 'Produce evidence that matches the original request.'
+        end
+
         private_class_method def self.cheap_orm_timeout
           n = agent_flag(key: :reward_llm_timeout, default: CHEAP_ORM_TIMEOUT).to_i
           n = CHEAP_ORM_TIMEOUT if n < 2
@@ -1770,7 +1833,9 @@ module PWN
               critic_pass: 'optional - critic pass value consumed by #judge',
               predicted: 'optional - predicted value consumed by #judge',
               proxy_ok: 'optional - proxy ok value consumed by #judge',
-              persist_components: 'optional - write score_components into the learning ledger'
+              persist_components: 'optional - write score_components into the learning ledger',
+              verifier_verdict: 'optional - :pass when a deterministic verifier already succeeded',
+              verifier_pass: 'optional - true as a boolean alias for verifier_verdict :pass'
             )
 
             # Run promote to success and return its result

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

@@ -438,6 +438,34 @@ module PWN
           "FACTS #{rows.map { |r| "#{r[:kind]}=#{r[:value]}" }.join(' ')}"
         end
 
+        public_class_method def self.claim(opts = {})
+          eng = (opts[:engagement_id] || 'default').to_s
+          unit = opts[:unit].to_s
+          raise 'ERROR: unit is required' if unit.empty?
+
+          ttl = (opts[:ttl] || 300).to_i
+          agent = (opts[:agent_id] || 'anon').to_s
+          dir = File.join(Dir.home, '.pwn', 'swarm', eng)
+          FileUtils.mkdir_p(dir)
+          path = File.join(dir, "#{unit.gsub(/[^A-Za-z0-9._:-]/, '_')}.claim")
+          now = Time.now.to_i
+          File.open(path, File::RDWR | File::CREAT, 0o644) do |f|
+            f.flock(File::LOCK_EX)
+            existing = begin
+              JSON.parse(f.read, symbolize_names: true)
+            rescue StandardError
+              {}
+            end
+            return { ok: false, unit: unit, holder: existing[:agent_id] } if existing[:until].to_i > now && existing[:agent_id].to_s != agent
+
+            row = { unit: unit, agent_id: agent, until: now + ttl }
+            f.rewind
+            f.truncate(0)
+            f.write(JSON.generate(row))
+            { ok: true, unit: unit, agent_id: agent, until: row[:until] }
+          end
+        end
+
         # Author(s):: 0day Inc. <support@0dayinc.com>
 
         public_class_method def self.authors
@@ -535,6 +563,14 @@ module PWN
               engagement_id: 'optional - engagement id (defaults to default)'
             )
 
+            # Atomically claim a work unit (INSERT-or-fail until TTL).
+            #{self}.claim(
+              unit: 'required - normalized target+phase key',
+              engagement_id: 'optional - engagement id (defaults to default)',
+              ttl: 'optional - seconds until the claim expires (defaults to 300)',
+              agent_id: 'optional - claimant id'
+            )
+
             # Print the AUTHOR(S) string for this module.
             #{self}.authors
           "

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

@@ -5,6 +5,9 @@ require 'json'
 require 'fileutils'
 require 'securerandom'
 require 'time'
+require 'openssl'
+require 'uri'
+require 'base64'
 
 module PWN
   module AI
@@ -41,7 +44,12 @@ module PWN
         end
 
         public_class_method def self.placeholder?(opts = {})
-          PLACEHOLDER_RX.match?(opts[:text].to_s)
+          s = opts[:text].to_s.dup
+          s.gsub!(/<<[-~]?\s*(['"])(\w+)\1.*?^\2\s*$/m, ' ')
+          s.gsub!(/<<[-~]?\s*(\w+).*?^\1\s*$/m, ' ')
+          s.gsub!(/'[^']*'/, "''")
+          s.gsub!(/"([^"\\]|\\.)*"/, '""')
+          PLACEHOLDER_RX.match?(s)
         rescue StandardError
           false
         end
@@ -60,18 +68,36 @@ module PWN
         end
 
         public_class_method def self.mint_canary(opts = {})
-          n = (opts[:bytes] || 8).to_i
-          n = 8 if n <= 0
-          tok = "PWNCANARY#{SecureRandom.hex(n)}"
+          _bytes = opts[:bytes]
+          turn = (opts[:turn] || Thread.current[:pwn_loop_iter] || 0).to_i
+          sid = (opts[:session_id] || Thread.current[:pwn_session_id] || 'sess').to_s
+          key = (Thread.current[:pwn_canary_key] ||= SecureRandom.hex(16))
+          tok = OpenSSL::HMAC.hexdigest('SHA256', key, "#{sid}:#{turn}")[0, 16]
+          hist = Thread.current[:pwn_canary_hist] ||= []
+          hist << tok
+          hist.shift while hist.length > 4
           Thread.current[:pwn_canary] = tok
           tok
         end
 
         public_class_method def self.canary_leak?(opts = {})
-          tok = Thread.current[:pwn_canary].to_s
-          return false if tok.empty?
-
-          opts[:text].to_s.include?(tok)
+          text = opts[:text].to_s
+          toks = Array(Thread.current[:pwn_canary_hist])
+          toks << Thread.current[:pwn_canary].to_s
+          toks = toks.reject(&:empty?).uniq
+          return false if toks.empty?
+
+          require 'base64'
+          toks.any? do |tok|
+            next true if text.include?(tok)
+
+            b64 = Base64.strict_encode64(tok)
+            b64u = Base64.urlsafe_encode64(tok)
+            hex = tok.each_byte.map { |b| format('%02x', b) }.join
+            enc = URI.encode_www_form_component(tok)
+            rot = tok.tr('A-Za-z', 'N-ZA-Mn-za-m')
+            text.include?(b64) || text.include?(b64u) || text.include?(hex) || text.include?(enc) || text.include?(rot)
+          end
         end
 
         public_class_method def self.injection_score(opts = {})
@@ -442,6 +468,49 @@ module PWN
           nil
         end
 
+        public_class_method def self.policy_decision(opts = {})
+          name = opts[:name].to_s
+          blob = opts[:args].inspect
+          path = File.join(Dir.home, '.pwn', 'toolguard.yaml')
+          return nil unless File.file?(path)
+
+          require 'yaml'
+          doc = YAML.safe_load_file(path, permitted_classes: [Symbol]) || {}
+          Array(doc['rules'] || doc[:rules]).each do |rule|
+            next unless rule.is_a?(Hash)
+
+            tool = (rule['tool'] || rule[:tool]).to_s
+            next unless tool.empty? || tool == name
+
+            pat = (rule['arg_pattern'] || rule[:arg_pattern]).to_s
+            next if pat.empty? || blob.match?(Regexp.new(pat)) == false
+
+            action = (rule['action'] || rule[:action] || 'allow').to_s
+            next if action == 'allow'
+
+            return {
+              action: action,
+              success: false,
+              error: (rule['reason'] || rule[:reason] || 'toolguard policy deny').to_s,
+              code: 'POLICY_DENY',
+              tool: name
+            }
+          end
+          nil
+        rescue StandardError
+          nil
+        end
+
+        public_class_method def self.scope_check!(opts = {})
+          return nil unless defined?(Engagement)
+
+          Engagement.deny_if_out_of_scope(
+            args: opts[:args],
+            command: opts[:command] || opts[:args].inspect,
+            text: opts[:text]
+          )
+        end
+
         public_class_method def self.rfc1918?(opts = {})
           oct = opts[:ip].to_s.split('.').map(&:to_i)
           return false unless oct.length == 4
@@ -535,7 +604,9 @@ module PWN
 
             # Mint a per-thread session canary token stored on Thread.current.
             #{self}.mint_canary(
-              bytes: 'optional - hex length (defaults to 8)'
+              bytes: 'optional - unused reserved length (HMAC uses 16 hex chars)',
+              turn: 'optional - turn number mixed into the HMAC',
+              session_id: 'optional - session id mixed into the HMAC'
             )
 
             # True when text contains the current session canary.
@@ -690,6 +761,19 @@ module PWN
               payload: 'optional - command string if class omitted'
             )
 
+            # Evaluate ~/.pwn/toolguard.yaml first-match rules.
+            #{self}.policy_decision(
+              name: 'required - tool name',
+              args: 'required - Hash of tool arguments'
+            )
+
+            # Block network args outside the active engagement scope.
+            #{self}.scope_check!(
+              args: 'optional - Hash of tool arguments',
+              command: 'optional - command string to scan for hosts',
+              text: 'optional - free-form blob to scan'
+            )
+
             # Print the AUTHOR(S) string for this module.
             #{self}.authors
           "

data/lib/pwn/ai/agent/tools/debug_lane.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require 'pwn/ai/agent/registry'
+
+PWN::AI::Agent::Registry.register(
+  name: 'debug_session',
+  toolset: 'pwn',
+  schema: {
+    name: 'debug_session',
+    description: 'Run a binary under gdb to crash and return typed crash_info.',
+    parameters: {
+      type: 'object',
+      properties: {
+        binary: { type: 'string' },
+        args: { type: 'array', items: { type: 'string' } },
+        script: { type: 'array', items: { type: 'string' } }
+      },
+      required: %w[binary]
+    }
+  },
+  handler: lambda { |args|
+    PWN::Plugins::GDB.debug_session(
+      binary: args[:binary] || args['binary'],
+      args: args[:args] || args['args'],
+      commands: args[:script] || args['script']
+    )
+  }
+)
+PWN::AI::Agent::Registry.register(
+  name: 'binary_diff',
+  toolset: 'pwn',
+  schema: {
+    name: 'binary_diff',
+    description: 'Diff two binaries (radiff2 -C) and rank changed functions.',
+    parameters: {
+      type: 'object',
+      properties: { a: { type: 'string' }, b: { type: 'string' } },
+      required: %w[a b]
+    }
+  },
+  handler: lambda { |args|
+    PWN::Plugins::BinaryParser.diff(a: args[:a] || args['a'], b: args[:b] || args['b'])
+  }
+)
+PWN::AI::Agent::Registry.register(
+  name: 'crash_triage',
+  toolset: 'pwn',
+  schema: {
+    name: 'crash_triage',
+    description: 'Dedupe AFL crashes, minimize, debug, and emit findings with PoCs.',
+    parameters: {
+      type: 'object',
+      properties: { campaign: { type: 'string' }, out_dir: { type: 'string' }, target: { type: 'string' } }
+    }
+  },
+  handler: lambda { |args|
+    dir = args[:out_dir] || args['out_dir'] || File.join(Dir.home, '.pwn', 'fuzz', (args[:campaign] || args['campaign'] || 'default').to_s)
+    PWN::Plugins::AFLplusplus.crash_triage(out_dir: dir)
+  }
+)
+PWN::AI::Agent::Registry.register(
+  name: 'capability_request',
+  toolset: 'sessions',
+  schema: {
+    name: 'capability_request',
+    description: 'Request a grantable capability (never auto-sudo).',
+    parameters: {
+      type: 'object',
+      properties: { cap: { type: 'string' }, reason: { type: 'string' }, operator_ack: { type: 'boolean' } },
+      required: %w[cap]
+    }
+  },
+  handler: lambda { |args|
+    PWN::Plugins::Capability.request(
+      cap: args[:cap] || args['cap'],
+      reason: args[:reason] || args['reason'],
+      operator_ack: args[:operator_ack] || args['operator_ack']
+    )
+  }
+)
+PWN::AI::Agent::Registry.register(
+  name: 'emulate',
+  toolset: 'pwn',
+  schema: {
+    name: 'emulate',
+    description: 'Emulate one function (Unicorn) and return registers/memory writes.',
+    parameters: {
+      type: 'object',
+      properties: {
+        binary: { type: 'string' },
+        addr: { type: 'string' },
+        args: { type: 'array' },
+        max_insns: { type: 'integer' }
+      },
+      required: %w[binary addr]
+    }
+  },
+  handler: lambda { |args|
+    PWN::Plugins::Emulator.emulate(
+      binary: args[:binary] || args['binary'],
+      addr: args[:addr] || args['addr'],
+      args: args[:args] || args['args'],
+      max_insns: args[:max_insns] || args['max_insns']
+    )
+  }
+)
+PWN::AI::Agent::Registry.register(
+  name: 'detonate',
+  toolset: 'pwn',
+  schema: {
+    name: 'detonate',
+    description: 'Run a sample in an isolated container. Refuses if isolation is missing.',
+    parameters: {
+      type: 'object',
+      properties: { path: { type: 'string' }, timeout: { type: 'integer' }, network: { type: 'string' } },
+      required: %w[path]
+    }
+  },
+  handler: lambda { |args|
+    PWN::Plugins::Detonate.detonate(
+      path: args[:path] || args['path'],
+      timeout: args[:timeout] || args['timeout'],
+      network: args[:network] || args['network']
+    )
+  }
+)
+PWN::AI::Agent::Registry.register(
+  name: 'budget_status',
+  toolset: 'sessions',
+  schema: {
+    name: 'budget_status',
+    description: 'Read-only remaining time/token/mutation budget for this loop.',
+    parameters: { type: 'object', properties: {} }
+  },
+  handler: ->(_args) { PWN::AI::Agent::Loop.budget_status }
+)
+PWN::AI::Agent::Registry.register(
+  name: 'pty_expect',
+  toolset: 'terminal',
+  schema: {
+    name: 'pty_expect',
+    description: 'Send optional data and wait for a regex on a PTY with timeout.',
+    parameters: {
+      type: 'object',
+      properties: {
+        session: { type: 'string' },
+        id: { type: 'string' },
+        send: { type: 'string' },
+        expect: { type: 'string' },
+        timeout: { type: 'integer' }
+      }
+    }
+  },
+  handler: lambda { |args|
+    id = args[:session] || args[:id] || args['session'] || args['id']
+    line = args[:send] || args['send']
+    PWN::Plugins::ProcessTube.write_line(id: id, line: line) if line.to_s != ''
+    PWN::Plugins::ProcessTube.expect(id: id, until: args[:expect] || args['expect'], timeout: args[:timeout])
+  }
+)

data/lib/pwn/ai/agent/tools/engagement.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'pwn/ai/agent/registry'
+
+PWN::AI::Agent::Registry.register(
+  name: 'engagement_open',
+  toolset: 'sessions',
+  schema: {
+    name: 'engagement_open',
+    description: 'Open or update an engagement scope document and mark it active.',
+    parameters: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        scope_cidrs: { type: 'array', items: { type: 'string' } },
+        scope_domains: { type: 'array', items: { type: 'string' } }
+      },
+      required: %w[name]
+    }
+  },
+  handler: lambda { |args|
+    PWN::AI::Agent::Engagement.open(
+      name: args[:name] || args['name'],
+      scope_cidrs: args[:scope_cidrs] || args['scope_cidrs'],
+      scope_domains: args[:scope_domains] || args['scope_domains']
+    )
+  }
+)
+PWN::AI::Agent::Registry.register(
+  name: 'engagement_close',
+  toolset: 'sessions',
+  schema: { name: 'engagement_close', description: 'Clear the active engagement.', parameters: { type: 'object', properties: {} } },
+  handler: ->(_args) { PWN::AI::Agent::Engagement.close }
+)
+PWN::AI::Agent::Registry.register(
+  name: 'engagement_status',
+  toolset: 'sessions',
+  schema: { name: 'engagement_status', description: 'Return the active engagement document.', parameters: { type: 'object', properties: { name: { type: 'string' } } } },
+  handler: ->(args) { PWN::AI::Agent::Engagement.status(name: args[:name] || args['name']) }
+)