pwn 0.5.613 → 0.5.617

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

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'pwn/ai/agent/registry'
+require 'pwn/sessions'
+
+# Thin wrappers around PWN::Sessions so the model can DISCOVER and INSPECT
+# the JSONL transcripts that learning_reflect / learning_distill_skill
+# consume. Without these the model has to blindly `shell("ls ~/.pwn/sessions")`
+# and guess a session_id — this closes that gap in the learning loop.
+
+PWN::AI::Agent::Registry.register(
+  name: 'sessions_list',
+  toolset: 'sessions',
+  schema: {
+    name: 'sessions_list',
+    description: 'List every pwn-ai session transcript in ~/.pwn/sessions ' \
+                 '(id, path, size_bytes, mtime, line_count) newest-first. ' \
+                 'Use to discover a session_id for learning_reflect / ' \
+                 'learning_distill_skill / sessions_view.',
+    parameters: {
+      type: 'object',
+      properties: {
+        limit: { type: 'integer', default: 25, description: 'Max sessions to return (newest first).' }
+      },
+      required: []
+    }
+  },
+  check: -> { defined?(PWN::Sessions) },
+  handler: lambda { |args|
+    limit = (args[:limit] || 25).to_i
+    PWN::Sessions.list.sort_by { |s| s[:mtime].to_s }.reverse.first(limit)
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'sessions_view',
+  toolset: 'sessions',
+  schema: {
+    name: 'sessions_view',
+    description: 'Load a session transcript by id and return its entries ' \
+                 '(role, timestamp, truncated content). Inspect BEFORE ' \
+                 'calling learning_reflect / learning_distill_skill on it.',
+    parameters: {
+      type: 'object',
+      properties: {
+        session_id: { type: 'string', description: 'PWN::Sessions id (basename without .jsonl).' },
+        max_entries: { type: 'integer', default: 200, description: 'Cap on transcript entries returned.' },
+        truncate: { type: 'integer', default: 400, description: 'Chars to keep per entry content.' }
+      },
+      required: %w[session_id]
+    }
+  },
+  check: -> { defined?(PWN::Sessions) },
+  handler: lambda { |args|
+    sid   = args[:session_id].to_s
+    cap   = (args[:max_entries] || 200).to_i
+    trunc = (args[:truncate] || 400).to_i
+    rows  = PWN::Sessions.load(session_id: sid)
+    raise ArgumentError, "no such session: #{sid}" if rows.empty?
+
+    entries = rows.first(cap).map do |e|
+      {
+        role: e[:role],
+        timestamp: e[:timestamp],
+        content: e[:content].to_s[0, trunc]
+      }
+    end
+    { session_id: sid, total_entries: rows.length, returned: entries.length, entries: entries }
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'sessions_delete',
+  toolset: 'sessions',
+  schema: {
+    name: 'sessions_delete',
+    description: 'Delete a session transcript (~/.pwn/sessions/<id>.jsonl). ' \
+                 'Use to prune noisy / failed / dev-experiment transcripts ' \
+                 'so the reflect() corpus stays high-signal. Irreversible.',
+    parameters: {
+      type: 'object',
+      properties: {
+        session_id: { type: 'string' }
+      },
+      required: %w[session_id]
+    }
+  },
+  check: -> { defined?(PWN::Sessions) },
+  handler: lambda { |args|
+    sid = args[:session_id].to_s
+    raise ArgumentError, 'session_id is required' if sid.empty?
+
+    { session_id: sid, deleted: PWN::Sessions.delete(session_id: sid) }
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'sessions_stats',
+  toolset: 'sessions',
+  schema: {
+    name: 'sessions_stats',
+    description: 'Aggregate stats over all session transcripts: total_sessions, ' \
+                 'total_lines, oldest, newest, disk_bytes.',
+    parameters: { type: 'object', properties: {}, required: [] }
+  },
+  check: -> { defined?(PWN::Sessions) },
+  handler: lambda { |_args|
+    listing = PWN::Sessions.list
+    PWN::Sessions.stats.merge(
+      disk_bytes: listing.sum { |s| s[:size].to_i },
+      dir: PWN::Sessions.sessions_dir
+    )
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'sessions_current',
+  toolset: 'sessions',
+  schema: {
+    name: 'sessions_current',
+    description: 'Return the ACTIVE pwn-ai session_id (the one this ' \
+                 'conversation is being appended to). Pass it directly to ' \
+                 'learning_reflect / learning_distill_skill / sessions_view ' \
+                 'without copy-pasting from the system-prompt banner.',
+    parameters: { type: 'object', properties: {}, required: [] }
+  },
+  check: -> { defined?(PWN::Sessions) },
+  handler: lambda { |_args|
+    sid = nil
+    sid = PWN::Env.dig(:ai, :session_id) if defined?(PWN::Env) && PWN::Env.is_a?(Hash)
+    sid ||= (Pry.config.pwn_ai_session_id if defined?(Pry) && Pry.respond_to?(:config) && Pry.config.respond_to?(:pwn_ai_session_id))
+    path = sid ? File.join(PWN::Sessions.sessions_dir, "#{sid}.jsonl") : nil
+    {
+      session_id: sid,
+      path: path,
+      exists: (path && File.exist?(path)) || false
+    }
+  }
+)

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

@@ -6,19 +6,30 @@ require 'pwn/ai/agent/registry'
 # Thin wrappers around the PWN::Skills store (~/.pwn/skills/*.md) so the
 # model can list/read/write reusable procedures. PromptBuilder injects
 # the index (name + first line); skill_view loads the full body on demand.
+#
+# Each skill may carry a :references Array (URLs, CWE/CVE/ATT&CK ids,
+# NIST 800-53 controls, docs) parsed from YAML front-matter or a
+# "## References" markdown section. References let the agent cite
+# authoritative sources when applying a skill and mirror the
+# PWN::SAST::*.security_references convention.
 
 PWN::AI::Agent::Registry.register(
   name: 'skill_list',
   toolset: 'skills',
   schema: {
     name: 'skill_list',
-    description: 'List available pwn-ai skills (name + first line of content).',
+    description: 'List available pwn-ai skills (name + first line + reference count).',
     parameters: { type: 'object', properties: {}, required: [] }
   },
   check: -> { defined?(PWN::Skills) && PWN::Skills.is_a?(Hash) },
   handler: lambda { |_args|
     PWN::Skills.map do |name, meta|
-      { name: name, type: meta[:type], summary: meta[:content].to_s.lines.first.to_s.strip[0, 120] }
+      {
+        name: name,
+        type: meta[:type],
+        summary: meta[:content].to_s.lines.first.to_s.strip[0, 120],
+        references: Array(meta[:references]).length
+      }
     end
   }
 )
@@ -28,7 +39,7 @@ PWN::AI::Agent::Registry.register(
   toolset: 'skills',
   schema: {
     name: 'skill_view',
-    description: 'Read the full content of a named skill.',
+    description: 'Read the full content of a named skill, including its references.',
     parameters: {
       type: 'object',
       properties: { name: { type: 'string' } },
@@ -41,7 +52,13 @@ PWN::AI::Agent::Registry.register(
     meta = PWN::Skills[key]
     raise ArgumentError, "no such skill: #{key}" unless meta
 
-    { name: key, type: meta[:type], path: meta[:path], content: meta[:content] }
+    {
+      name: key,
+      type: meta[:type],
+      path: meta[:path],
+      references: Array(meta[:references]),
+      content: meta[:content]
+    }
   }
 )
 
@@ -51,12 +68,20 @@ PWN::AI::Agent::Registry.register(
   schema: {
     name: 'skill_create',
     description: 'Save a new reusable skill (markdown procedure) to ~/.pwn/skills/. ' \
-                 'It will be listed in every future pwn-ai system prompt.',
+                 'It will be listed in every future pwn-ai system prompt. Optionally ' \
+                 'attach references (URLs, CWE/CVE ids, MITRE ATT&CK, NIST 800-53, docs).',
     parameters: {
       type: 'object',
       properties: {
         name: { type: 'string', description: 'lowercase, hyphens/underscores only' },
-        content: { type: 'string', description: 'Full markdown body of the skill.' }
+        content: { type: 'string', description: 'Full markdown body of the skill.' },
+        references: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Optional list of reference URLs / identifiers (CWE-79, T1059, ' \
+                       'https://..., NIST SI-3, etc.). Written as YAML front-matter and ' \
+                       'a "## References" section.'
+        }
       },
       required: %w[name content]
     }
@@ -66,11 +91,102 @@ PWN::AI::Agent::Registry.register(
     name = args[:name].to_s.gsub(/[^a-z0-9_-]/i, '_')
     raise ArgumentError, 'name is required' if name.empty?
 
+    body = args[:content].to_s
+    refs = Array(args[:references]).map(&:to_s).map(&:strip).reject(&:empty?).uniq
+
+    unless refs.empty?
+      # YAML front-matter (only if body doesn't already have one)
+      unless body.start_with?("---\n")
+        fm = "---\nreferences:\n#{refs.map { |r| "  - #{r}" }.join("\n")}\n---\n"
+        body = fm + body
+      end
+      # ## References section (only if not already present)
+      body = "#{body.rstrip}\n\n## References\n#{refs.map { |r| "- #{r}" }.join("\n")}\n" unless body =~ /^\#{1,3}\s*References\s*$/i
+    end
+
     dir = PWN::Config.pwn_skills_path
     FileUtils.mkdir_p(dir)
     path = File.join(dir, "#{name}.md")
-    File.write(path, args[:content].to_s)
+    File.write(path, body)
     PWN::Config.load_skills(pwn_skills_path: dir) # refresh PWN::Skills const
-    { saved: true, path: path, total: PWN::Skills.keys.length }
+    { saved: true, path: path, references: refs, total: PWN::Skills.keys.length }
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'skill_add_reference',
+  toolset: 'skills',
+  schema: {
+    name: 'skill_add_reference',
+    description: 'Append one or more references (URL, CWE/CVE id, MITRE ATT&CK ' \
+                 'technique, NIST control, doc link) to an existing skill.',
+    parameters: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Existing skill name.' },
+        references: { type: 'array', items: { type: 'string' } }
+      },
+      required: %w[name references]
+    }
+  },
+  check: -> { defined?(PWN::Skills) && PWN::Skills.is_a?(Hash) },
+  handler: lambda { |args|
+    key  = args[:name].to_s.to_sym
+    meta = PWN::Skills[key]
+    raise ArgumentError, "no such skill: #{key}" unless meta
+
+    new_refs = Array(args[:references]).map(&:to_s).map(&:strip).reject(&:empty?)
+    raise ArgumentError, 'references must be a non-empty array' if new_refs.empty?
+
+    body     = File.read(meta[:path])
+    existing = Array(meta[:references])
+    add      = (new_refs - existing)
+
+    if body =~ /^(\#{1,3}\s*References\s*)$/i
+      # Append bullets right after the References heading block (end of file safest)
+      body = "#{body.rstrip}\n#{add.map { |r| "- #{r}" }.join("\n")}\n" unless add.empty?
+    else
+      body = "#{body.rstrip}\n\n## References\n#{(existing + add).uniq.map { |r| "- #{r}" }.join("\n")}\n"
+    end
+
+    File.write(meta[:path], body)
+    PWN::Config.load_skills(pwn_skills_path: File.dirname(meta[:path]))
+    {
+      saved: true,
+      name: key,
+      path: meta[:path],
+      added: add,
+      references: Array(PWN::Skills[key][:references])
+    }
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'skill_delete',
+  toolset: 'skills',
+  schema: {
+    name: 'skill_delete',
+    description: 'Delete a skill from ~/.pwn/skills/ by name. Use to prune ' \
+                 'low-quality auto-distilled skills so they stop appearing ' \
+                 'in every future system prompt. Irreversible.',
+    parameters: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Existing skill name (basename without extension).' }
+      },
+      required: %w[name]
+    }
+  },
+  check: -> { defined?(PWN::Skills) && PWN::Skills.is_a?(Hash) },
+  handler: lambda { |args|
+    key  = args[:name].to_s.to_sym
+    meta = PWN::Skills[key]
+    raise ArgumentError, "no such skill: #{key}" unless meta
+
+    path = meta[:path]
+    dir  = File.dirname(path)
+    FileUtils.rm_f(path)
+    PWN::Config.load_skills(pwn_skills_path: dir)
+    { deleted: true, name: key, path: path, remaining: PWN::Skills.keys.length }
   }
 )

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

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require 'pwn/ai/agent/registry'
+require 'pwn/ai/agent/swarm'
+
+# Multi-agent orchestration tools. These let the PRIMARY pwn-ai agent
+# spawn/ask/debate SUB-agents (personas from ~/.pwn/agents.yml), each of
+# which is a full PWN::AI::Agent::Loop.run — tool-calling, memory-aware,
+# metrics-recorded, learning-reflected. This replaces the legacy pwn-irc
+# "N chatbots on inspircd" mechanism with an in-process JSONL bus under
+# ~/.pwn/swarm/<id>/, so conversations survive the process and can be
+# resumed cross-session by any pwn-ai / PWN::Cron job.
+
+PWN::AI::Agent::Registry.register(
+  name: 'agent_list',
+  toolset: 'swarm',
+  schema: {
+    name: 'agent_list',
+    description: 'List defined multi-agent personas from ~/.pwn/agents.yml ' \
+                 '(name, role summary, engine, toolsets, max_iters). Use ' \
+                 'before agent_ask / agent_debate to see who you can ' \
+                 'delegate to. Define new ones with agent_spawn.',
+    parameters: { type: 'object', properties: {}, required: [] }
+  },
+  check: -> { defined?(PWN::AI::Agent::Swarm) },
+  handler: lambda { |_args|
+    PWN::AI::Agent::Swarm.personas.map do |name, p|
+      {
+        name: name,
+        role: p[:role].to_s[0, 200],
+        engine: p[:engine],
+        toolsets: p[:toolsets],
+        max_iters: p[:max_iters]
+      }
+    end
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'agent_spawn',
+  toolset: 'swarm',
+  schema: {
+    name: 'agent_spawn',
+    description: 'Define (or overwrite) a persona in ~/.pwn/agents.yml so ' \
+                 'it can be used with agent_ask / agent_debate. A persona ' \
+                 'is a system-role overlay + toolset allow-list + engine ' \
+                 'override. Omit "swarm" from toolsets to prevent that ' \
+                 'persona from recursively spawning further sub-agents.',
+    parameters: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'snake_case persona name.' },
+        role: { type: 'string', description: 'System-role overlay describing this persona.' },
+        toolsets: {
+          type: 'array', items: { type: 'string' },
+          description: 'Registry toolset names this persona may use ' \
+                       '(e.g. terminal, pwn, memory, skills, extrospection). ' \
+                       'Default: everything except swarm/cron.'
+        },
+        engine: {
+          type: 'string', enum: %w[openai anthropic grok gemini ollama],
+          description: 'Override AI engine for this persona (model diversity ' \
+                       '= real antagonism). Default: inherit active engine.'
+        },
+        max_iters: {
+          type: 'integer',
+          description: 'Per-turn tool-loop cap for this persona (default 25).'
+        }
+      },
+      required: %w[name role]
+    }
+  },
+  check: -> { defined?(PWN::AI::Agent::Swarm) },
+  handler: lambda { |args|
+    PWN::AI::Agent::Swarm.spawn(
+      name: args[:name],
+      role: args[:role],
+      toolsets: args[:toolsets],
+      engine: args[:engine],
+      max_iters: args[:max_iters]
+    )
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'agent_ask',
+  toolset: 'swarm',
+  schema: {
+    name: 'agent_ask',
+    description: 'Run ONE turn of a named persona as a full tool-calling ' \
+                 'sub-agent (PWN::AI::Agent::Loop.run under that persona). ' \
+                 'The reply comes back to YOU as a tool result. Request + ' \
+                 'reply are appended to ~/.pwn/swarm/<swarm_id>/bus.jsonl so ' \
+                 'other personas (and future sessions) can see them. ' \
+                 'Recursion is depth-capped by PWN::Env[:ai][:agent][:max_depth].',
+    parameters: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Persona name (see agent_list).' },
+        request: { type: 'string', description: 'What to ask / instruct the persona.' },
+        swarm_id: {
+          type: 'string',
+          description: 'Existing swarm to join (from swarm_list / a prior ' \
+                       'agent_ask). Omit to auto-create a new swarm.'
+        }
+      },
+      required: %w[name request]
+    }
+  },
+  max_chars: 32_000,
+  check: -> { defined?(PWN::AI::Agent::Swarm) },
+  handler: lambda { |args|
+    PWN::AI::Agent::Swarm.ask(
+      name: args[:name],
+      request: args[:request],
+      swarm_id: args[:swarm_id]
+    )
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'agent_debate',
+  toolset: 'swarm',
+  schema: {
+    name: 'agent_debate',
+    description: 'Round-robin an antagonistic debate between 2+ personas. ' \
+                 'Each persona sees the swarm bus tail (prior turns) and is ' \
+                 'asked to respond/critique/advance. Returns the full ' \
+                 'transcript plus swarm_id so you can continue it later. ' \
+                 'This is the native replacement for the legacy pwn-irc ' \
+                 'multi-agent chat.',
+    parameters: {
+      type: 'object',
+      properties: {
+        names: {
+          type: 'array', items: { type: 'string' },
+          description: '>=2 persona names in speaking order.'
+        },
+        topic: { type: 'string', description: 'Opening question / claim / target.' },
+        rounds: { type: 'integer', default: 2, description: 'Full passes over names.' },
+        swarm_id: { type: 'string', description: 'Existing swarm to continue.' }
+      },
+      required: %w[names topic]
+    }
+  },
+  max_chars: 48_000,
+  check: -> { defined?(PWN::AI::Agent::Swarm) },
+  handler: lambda { |args|
+    PWN::AI::Agent::Swarm.debate(
+      names: args[:names],
+      topic: args[:topic],
+      rounds: args[:rounds],
+      swarm_id: args[:swarm_id]
+    )
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'agent_broadcast',
+  toolset: 'swarm',
+  schema: {
+    name: 'agent_broadcast',
+    description: 'Fan the same request out to multiple personas (default: ' \
+                 'all defined) and return {name => reply}. Useful for ' \
+                 'ensemble opinions / voting on an approach.',
+    parameters: {
+      type: 'object',
+      properties: {
+        request: { type: 'string' },
+        names: { type: 'array', items: { type: 'string' } },
+        swarm_id: { type: 'string' }
+      },
+      required: %w[request]
+    }
+  },
+  max_chars: 48_000,
+  check: -> { defined?(PWN::AI::Agent::Swarm) },
+  handler: lambda { |args|
+    PWN::AI::Agent::Swarm.broadcast(
+      request: args[:request],
+      names: args[:names],
+      swarm_id: args[:swarm_id]
+    )
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'swarm_bus',
+  toolset: 'swarm',
+  schema: {
+    name: 'swarm_bus',
+    description: 'Tail the JSONL message bus for a swarm ' \
+                 '(~/.pwn/swarm/<id>/bus.jsonl). Read-side of agent_ask / ' \
+                 'agent_debate — use to inspect what personas said in a ' \
+                 'prior (or concurrent) session before continuing it.',
+    parameters: {
+      type: 'object',
+      properties: {
+        swarm_id: { type: 'string' },
+        limit: { type: 'integer', default: 25 }
+      },
+      required: %w[swarm_id]
+    }
+  },
+  check: -> { defined?(PWN::AI::Agent::Swarm) },
+  handler: lambda { |args|
+    PWN::AI::Agent::Swarm.bus_tail(
+      swarm_id: args[:swarm_id],
+      limit: args[:limit] || 25
+    )
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'swarm_list',
+  toolset: 'swarm',
+  schema: {
+    name: 'swarm_list',
+    description: 'List all swarms under ~/.pwn/swarm/ (swarm_id, message ' \
+                 'count, mtime). Pick one to resume with agent_ask / ' \
+                 'agent_debate(swarm_id:) — this is how cross-session ' \
+                 'multi-agent conversations continue without a daemon.',
+    parameters: { type: 'object', properties: {}, required: [] }
+  },
+  check: -> { defined?(PWN::AI::Agent::Swarm) },
+  handler: lambda { |_args|
+    PWN::AI::Agent::Swarm.list
+  }
+)

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

@@ -20,7 +20,7 @@ module PWN
 
           system_role_content = "Being an expert penetration tester skilled in code analysis, debugging, and exploitation while stepping through JavaScript in a Chrome DevTools debugging session:  1. Your sole purpose is to analyze each JavaScript step and generate an Exploit Prediction Scoring System (EPSS) score between 0% - 100%.  The step currently resides in this block of JavaScript:\n```\n#{source_to_review}\n```\n2. If the score is >= 75%, generate a JavaScript proof-of-concept that would allow a threat actor to directly exploit or target a user for exploitation (i.e. no self-exploit).  3. If the EPSS score is >= 75% also provide a code fix. *** If the EPSS score is < 75%, no explanations or summaries - just the EPSS score."
 
-          PWN::AI::Introspection.reflect_on(
+          PWN::AI::Agent::Introspection.reflect_on(
             system_role_content: system_role_content,
             request: request,
             suppress_pii_warning: true

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

@@ -12,7 +12,7 @@ module PWN
       # 4. CVSS score, vector string, and first.org calculator URI
       # 5. CWE category, brief description, and CWE URI
       # 6. Relevant NIST 800-53 control
-      # It leverages the PWN::AI::Introspection.reflect_on method. Defaults to Jira for existing workflow compatibility.
+      # It leverages the PWN::AI::Agent::Introspection.reflect_on method. Defaults to Jira for existing workflow compatibility.
       module VulnGen
         # Supported Method Parameters::
         # ai_analysis = PWN::AI::Agent::VulnGen.analyze(
@@ -60,7 +60,7 @@ module PWN
           6. NIST 800-53 Security Control that is impacted by this vulnerability.
           "
 
-          analysis = PWN::AI::Introspection.reflect_on(
+          analysis = PWN::AI::Agent::Introspection.reflect_on(
             system_role_content: system_role_content,
             request: request,
             suppress_pii_warning: true

data/lib/pwn/ai/agent.rb

@@ -23,6 +23,11 @@ module PWN
       autoload :Result,        'pwn/ai/agent/result'
       autoload :PromptBuilder, 'pwn/ai/agent/prompt_builder'
       autoload :Loop,          'pwn/ai/agent/loop'
+      autoload :Metrics,       'pwn/ai/agent/metrics'
+      autoload :Learning,      'pwn/ai/agent/learning'
+      autoload :Extrospection, 'pwn/ai/agent/extrospection'
+      autoload :Introspection, 'pwn/ai/agent/introspection'
+      autoload :Swarm,         'pwn/ai/agent/swarm'
 
       # Display a List of Every PWN::AI Module
 

data/lib/pwn/ai/anthropic.rb

@@ -155,7 +155,7 @@ module PWN
       #   tool_choice: 'optional - "auto" | "none" | "required" | {type:"function", function:{name:..}}',
       #   model: 'optional - overrides PWN::Env[:ai][:anthropic][:model]',
       #   temp: 'optional - temperature (defaults to PWN::Env[:ai][:anthropic][:temp] || 1)',
-      #   max_tokens: 'optional - defaults to 4096',
+      #   max_tokens: 'optional - defaults to PWN::Env[:ai][:anthropic][:max_tokens] || 128_000',
       #   timeout: 'optional - seconds (default 900)',
       #   spinner: 'optional - display spinner (default false)'
       # )
@@ -175,7 +175,7 @@ module PWN
 
         http_body = {
           model: model,
-          max_tokens: opts[:max_tokens] || 4096,
+          max_tokens: opts[:max_tokens] || engine[:max_tokens] || 128_000,
           temperature: temp,
           messages: anth_messages
         }
@@ -284,7 +284,22 @@ module PWN
       # Anthropic /v1/messages response -> OpenAI chat/completions shape
       private_class_method def self.anthropic_resp_to_oa(opts = {})
         resp = opts[:response] ||= {}
-        blocks     = Array(resp[:content])
+        blocks = Array(resp[:content])
+        # When Anthropic hits max_tokens mid tool_use emission it returns the
+        # block with input:{} and stop_reason:"max_tokens". Dispatching that
+        # yields "ArgumentError: <param> is required" from every tool handler,
+        # and round-tripping it in _native_content without a matching
+        # tool_result 400s the next turn. Strip those artifacts here.
+        if resp[:stop_reason] == 'max_tokens'
+          truncated, blocks = blocks.partition do |b|
+            b[:type] == 'tool_use' && (b[:input].nil? || (b[:input].respond_to?(:empty?) && b[:input].empty?))
+          end
+          unless truncated.empty?
+            names = truncated.map { |b| b[:name] }.join(', ')
+            warn "[pwn-ai] Anthropic hit max_tokens mid tool_use (#{names}); " \
+                 'dropping partial call. Raise ai.anthropic.max_tokens in PWN::Env.'
+          end
+        end
         text       = blocks.select { |b| b[:type] == 'text' }.map { |b| b[:text] }.join
         tool_calls = blocks.select { |b| b[:type] == 'tool_use' }.map do |b|
           {
@@ -375,7 +390,7 @@ module PWN
 
         http_body = {
           model: model,
-          max_tokens: 4096,
+          max_tokens: engine[:max_tokens] || 128_000,
           temperature: temp,
           system: system_role_content,
           messages: []