pwn 0.5.682 → 0.5.684

data/documentation/pwn-ai-Agent.md

@@ -102,7 +102,7 @@ $ pwn --ai "run bin/pwn_sast against ./src and push findings to DefectDojo"
 
 ## What the agent can call
 
-13 toolsets · **85 tools** - full table at
+13 toolsets · **87 tools** - full table at
 [Agent Tool Registry](Agent-Tool-Registry.md).
 
 The two that matter most:
@@ -144,7 +144,7 @@ There is no request type. Every request gets an English task compass.
 - Advancement needs a PRM +1 streak or a clear phase shift after tools on the active task (not a blind every-3-tools hop).
 - REPL contract: `on_tool.call('task', full_summary_text, '')` - result empty, no truncation.
 
-**Long-run pressure:** when recent turns keep hitting the iteration ceiling, the agent tightens the rest of the turn: lower `max_iters` (stricter on local engines than remote), a text-only finish, and no extra counterfactual forks. Task state and Learning still flush on the way out so the run ends with a real answer instead of thrashing.
+**Long-run pressure:** budget-hot turns skip extra counterfactual forks. The last iteration strips tools only when the original request is already satisfied. Scars and overconfidence do not lower this request's `max_iters` (default 777). Task state and Learning still flush on the exhaust path.
 
 ![TaskSummarizer](diagrams/task-summarizer.svg)
 
@@ -156,7 +156,7 @@ task_summary_every: 5           # verbose progress every N tools
 task_summary_interval_s: 8.0    # or every N seconds (verbose)
 task_summary_verbose: false     # mid-flight Progress: lines
 task_summary_llm: true          # LLM task decompose (default on)
-max_iters: 75                   # budget pressure may lower the effective cap (stricter on local engines)
+max_iters: 777                  # scars / overconf do not lower this request
 ```
 
 
@@ -197,7 +197,7 @@ max_iters: 75                   # budget pressure may lower the effective cap (s
 | `reward_llm_timeout` | `12` | seconds for the cheap ORM chat (clamped 2..30) |
 | `verify_as_reward` | `nil` (auto) | browser-grounded claim sample policy |
 | `local_introspect` | `:failure_only` | ollama / openwebui end-of-turn introspect policy |
-| `tool_preference` | CORE_TOOLS list (act leads with shell) | Rank bonus + Policy suggested-action order |
+| `tool_preference` | same list as CORE_TOOLS (`memory_recall`, `session_recall`, `skills_recall`, `pwn_eval`, `shell`, `mistakes_record`, `mistakes_resolve`, `learning_note_outcome`, `memory_remember`) | Rank bonus + Policy suggested-action order |
 | `defer_introspect` | `true` | Post-answer Learning on a background thread |
 | `prompt_cache` | `true` | Engine-native prefix cache (not Ollama / Open WebUI) |
 
@@ -227,3 +227,8 @@ The `shell` tool also blocks hping3 / nmap-style sweep commands when recon is
 not authorized. On how-to asks, memory SOPs about repo rubocop/rake hygiene are
 kept out of the prompt so the model does not pivot into unrelated verification.
 
+Keyword routing, unfinished-goal resume (`continue` / `resume`), and
+write-then-read completion: [Session Workflow](Session-Workflow.md).
+
+[← Home](Home.md)
+

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

@@ -47,7 +47,7 @@ module PWN
           required = Array(entry.schema&.dig(:parameters, :required))
           args = ToolGuard.coerce_args(args: args, required: required) if defined?(ToolGuard)
           result = entry.handler.call(args)
-          JSON.generate(success: true, result: result)
+          JSON.generate(success: true, result: result, effect: effect(name: entry.name, args: args))
         rescue StandardError => e
           JSON.generate(
             success: false,
@@ -281,6 +281,56 @@ module PWN
           []
         end
 
+        # Effect of a tool call from NAME + ARGV only — never stdout.
+        # :write mutate, :browse navigate, :recall store lookup, :read/:eval observe.
+        WRITE_ARGV_RX = /
+          \bsed\s+-i\b|\bruby\s+-i\b|\btee\b|
+          (?:\s|\A)>{1,2}\s+\S|
+          File\.(?:write|open|binwrite)|IO\.write|
+          \bopen\s*\([^)]*['"]w|
+          \b(?:cp|mv|rm|mkdir|touch|chmod|chown)\b|
+          \bgit\s+(?:add|commit|rm)
+        /ix
+        BROWSE_ARGV_RX = /
+          TransparentBrowser|browser_obj|\.goto\b|dump_links|
+          watir|headless_?chrome|\bdevtools\b
+        /ix
+        RECALL_TOOLS = %w[
+          memory_recall session_recall skills_recall sessions_view
+          sessions_list sessions_current
+        ].freeze
+        STORE_TOOLS = %w[
+          memory_remember mistakes_record mistakes_resolve
+          learning_note_outcome skill_create skill_add_reference
+        ].freeze
+
+        public_class_method def self.effect(opts = {})
+          name = opts[:name].to_s
+          return :read if name.empty?
+          return :recall if RECALL_TOOLS.include?(name)
+          return :store if STORE_TOOLS.include?(name)
+
+          blob = argv_blob(args: opts[:args])
+          return :browse if blob.match?(BROWSE_ARGV_RX)
+          return :write if blob.match?(WRITE_ARGV_RX)
+          return :eval if name == 'pwn_eval'
+
+          :read
+        rescue StandardError
+          :read
+        end
+
+        private_class_method def self.argv_blob(opts = {})
+          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(' ')
+          else args.to_s
+          end
+        rescue StandardError
+          opts[:args].to_s
+        end
+
         private_class_method def self.symbolize(opts = {})
           hash = opts[:hash] ||= {}
           hash.each_with_object({}) { |(k, v), m| m[k.to_sym] = v }
@@ -306,6 +356,7 @@ module PWN
               )
 
               PWN::AI::Agent::Dispatch.repair_name(name: 'run_shell')  # => 'shell'
+              PWN::AI::Agent::Dispatch.effect(name: 'shell', args: { command: 'ls' })
               PWN::AI::Agent::Dispatch.tool_calls_from_text(text: 'shell(command="id")')
 
               #{self}.authors