pwn 0.5.668 → 0.5.669

data/documentation/diagrams/persistence-filesystem.svg

@@ -254,16 +254,16 @@
 <!-- cur -->
 <g id="node18" class="node">
 <title>cur</title>
-<path fill="#fcd34d" stroke="#334155" stroke-width="1.3" d="M408.62,-238C408.62,-240.21 374.45,-242 332.38,-242 290.3,-242 256.12,-240.21 256.12,-238 256.12,-238 256.12,-202 256.12,-202 256.12,-199.79 290.3,-198 332.38,-198 374.45,-198 408.62,-199.79 408.62,-202 408.62,-202 408.62,-238 408.62,-238"/>
-<path fill="none" stroke="#334155" stroke-width="1.3" d="M408.62,-238C408.62,-235.79 374.45,-234 332.38,-234 290.3,-234 256.12,-235.79 256.12,-238"/>
-<text xml:space="preserve" text-anchor="middle" x="332.38" y="-222.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">curriculum/</text>
-<text xml:space="preserve" text-anchor="middle" x="332.38" y="-210.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">self&#45;play reproducers · A/B eval</text>
+<path fill="#fcd34d" stroke="#334155" stroke-width="1.3" d="M413.5,-238C413.5,-240.21 377.14,-242 332.38,-242 287.61,-242 251.25,-240.21 251.25,-238 251.25,-238 251.25,-202 251.25,-202 251.25,-199.79 287.61,-198 332.38,-198 377.14,-198 413.5,-199.79 413.5,-202 413.5,-202 413.5,-238 413.5,-238"/>
+<path fill="none" stroke="#334155" stroke-width="1.3" d="M413.5,-238C413.5,-235.79 377.14,-234 332.38,-234 287.61,-234 251.25,-235.79 251.25,-238"/>
+<text xml:space="preserve" text-anchor="middle" x="332.38" y="-222.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">curriculum/ + curriculum_kpi.jsonl</text>
+<text xml:space="preserve" text-anchor="middle" x="332.38" y="-210.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">self&#45;play · A/B eval · KPI trend</text>
 </g>
 <!-- Root&#45;&gt;cur -->
 <g id="edge17" class="edge">
 <title>Root&#45;&gt;cur</title>
-<path fill="none" stroke="#94a3b8" stroke-width="1.1" d="M105.59,-671.76C106.02,-605.83 116.42,-377.3 235.5,-253 239.43,-248.9 243.89,-245.31 248.68,-242.17"/>
-<polygon fill="#94a3b8" stroke="#94a3b8" stroke-width="1.1" points="249.72,-244.4 254.49,-238.72 247.22,-240.18 249.72,-244.4"/>
+<path fill="none" stroke="#94a3b8" stroke-width="1.1" d="M105.59,-671.76C106.02,-605.83 116.42,-377.3 235.5,-253 238.03,-250.35 240.79,-247.92 243.72,-245.68"/>
+<polygon fill="#94a3b8" stroke="#94a3b8" stroke-width="1.1" points="245.06,-247.73 249.45,-241.75 242.29,-243.69 245.06,-247.73"/>
 </g>
 <!-- ftn -->
 <g id="node19" class="node">

data/documentation/diagrams/sdr-radio-flow.svg

@@ -10,7 +10,7 @@
 <title>PWN_SDR</title>
 <polygon fill="#0f172a" stroke="none" points="-43.2,43.2 -43.2,-821.05 1748.95,-821.05 1748.95,43.2 -43.2,43.2"/>
 <text xml:space="preserve" text-anchor="start" x="614.38" y="-755.85" font-family="sans-Serif" font-weight="bold" font-size="20.00" fill="#e2e8f0">PWN::SDR &#45; Software&#45;Defined Radio &amp; RF Hacking</text>
-<text xml:space="preserve" text-anchor="start" x="469.62" y="-744.4" font-family="sans-Serif" font-size="11.00" fill="#94a3b8">GQRX · FlipperZero · RFIDler · FrequencyAllocation · Decoder::* (20) · Base.run_iq (true&#45;air) · FFI::{Volk,Liquid,FFTW,RTLSdr,HackRF,AdalmPluto,SoapySDR}</text>
+<text xml:space="preserve" text-anchor="start" x="440.75" y="-744.4" font-family="sans-Serif" font-size="11.00" fill="#94a3b8">GQRX · FlipperZero · RFIDler · FrequencyAllocation · Decoder::* (20+Base/DSP) · Base.run_iq (true&#45;air) · FFI::{Volk,Liquid,FFTW,RTLSdr,HackRF,AdalmPluto,SoapySDR}</text>
 <g id="clust1" class="cluster">
 <title>cluster_hw</title>
 <path fill="#022c22" stroke="#047857" d="M223.5,-558C223.5,-558 487,-558 487,-558 493,-558 499,-564 499,-570 499,-570 499,-697 499,-697 499,-703 493,-709 487,-709 487,-709 223.5,-709 223.5,-709 217.5,-709 211.5,-703 211.5,-697 211.5,-697 211.5,-570 211.5,-570 211.5,-564 217.5,-558 223.5,-558"/>

data/documentation/pwn-ai-Agent.md

@@ -90,7 +90,7 @@ $ pwn --ai "run bin/pwn_sast against ./src and push findings to DefectDojo"
 
 ## What the agent can call
 
-12 toolsets · **78 tools** - full table at
+12 toolsets · **82 tools** - full table at
 [Agent Tool Registry](Agent-Tool-Registry.md).
 
 The two that matter most:
@@ -118,7 +118,7 @@ full `Loop.run` under a persona overlay) that share a JSONL bus. See
 | Surface | When | Content |
 |---|---|---|
 | `emit_plan!` | User submit | **Full** goal + ordered plain-English tangible tasks (each may need many tools) |
-| `about_to` | Before each tool batch | **Primary:** `task k/n: <english>`  -  **secondary:** `via shell×2 (search)` (not raw argv) |
+| `about_to` | Before each tool batch | **Primary:** `task k/n: <english>` - **secondary:** `via shell×2 (search)` (not raw argv) |
 | `plan_context` / `active_task_prompt` | Into Loop messages | Same English tasks steer tool choice (not TUI-only) |
 | `record!` | After each tool | Advances `plan_idx`; emits English advancement brief when the index moves; verbose progress only if `task_summary_verbose` |
 | `flush!` | End of turn | Optional closing brief with active `task k/n` |
@@ -131,7 +131,7 @@ full `Loop.run` under a persona overlay) that share a JSONL bus. See
 - 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.
 
-**Budget pressure:** when unresolved `agent_loop` / `assistant_answer` budget-exhaustion fingerprints dominate, `Loop.budget_exhaustion_hot?` tightens the live turn (stricter `max_iters` on local engines than remote), forces a text-only tail, skips counterfactual forks, and still flushes task state + Learning on the exhaust path.
+**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.
 
 ![TaskSummarizer](diagrams/task-summarizer.svg)
 
@@ -157,18 +157,17 @@ max_iters: 25                   # budget pressure may lower the effective cap (s
 - Run `mistakes_list` before retrying something that failed last session -
   the fix may already be recorded.
 - `ai.agent.tool_router: true` + `ai.agent.plan_first: true` when running on
-  a local model - dramatically cuts mis-routing.
+  a local model - that cuts mis-routing a lot.
 - Set `ai.reflect_engine:` to a frontier provider so lessons written to
-  `~/.pwn/memory.json` are high-signal even when the *executing* engine is
+  `~/.pwn/memory.json` stay high-signal even when the executing engine is
   local.
-- `PWN::AI::Agent::Learning.export_finetune` + `Reward.export_dpo` turn every
-  successful session and every preference pair into supervised / DPO
-  datasets under `~/.pwn/finetune/` - `Curriculum.train_and_gate` then
-  LoRA-tunes the local model and promotes only under **gate v2** (resolved
-  margin + mean judge + frozen smoke set). Preference pairs prefer trajectory
-  geometry: revised answers and winning traces, not fix-commentary prose.
-  `scrub_preferences` and the export filter enforce that; practice lands
-  winning traces.
+- `PWN::AI::Agent::Learning.export_finetune` and `Reward.export_dpo` turn
+  successful sessions and preference pairs into supervised / preference
+  datasets under `~/.pwn/finetune/`. `Curriculum.train_and_gate` can then
+  fine-tune a local model and promote only when resolved-mistake margin,
+  mean judge score, and a frozen smoke set all look healthy. Preference
+  pairs should be real answer revisions and winning traces, not fix-commentary
+  prose. `scrub_preferences` and the export filter enforce that.
   See [Reinforcement Learning](Reinforcement-Learning.md).
 
 ## RL feature flags (`PWN::Env[:ai][:agent]`)
@@ -189,3 +188,20 @@ Full detail: [Reinforcement Learning](Reinforcement-Learning.md).
 [Extrospection](Extrospection.md) · [Swarm](Swarm.md) · [Cron](Cron.md)
 
 [← Home](Home.md)
+
+## Intent routing (how-to vs act vs recon)
+
+On local engines (`ollama`, `openwebui`), plain "how do I..." questions used to
+kick off multi-step host probes and planner noise. Each user turn is classified
+first:
+
+| Intent | Example | Behavior |
+|--------|---------|----------|
+| How-to | "how to do a ping sweep of a subnet using hping3?" | Short explanation with example commands only. No tools and no live scan plan. |
+| Live recon | "using hping3 what live hosts can you find in this subnet?" | Needs clear in-scope / authorized engagement wording, or set `ai.agent.recon_authorized=true`. Otherwise the agent refuses and points you at the how-to form. |
+| Act | "refactor Loop.run and run rubocop" | Normal multi-step agent work with tools. |
+
+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.
+

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

@@ -1104,6 +1104,175 @@ module PWN
           nil
         end
 
+        # Request intent for routing (how-to vs act/recon). Local models thrash when
+        # pure explanation asks are force-planned into multi-step host probes.
+        # :howto → answer with explanation only (no plan_first / no live recon).
+        # :recon_act → live discovery; requires explicit authorization language.
+        # :act → general agent work with tools.
+        HOWTO_RX = /
+          \b(
+            how\s+to|how\s+do\s+i|how\s+can\s+i|how\s+would\s+i|how\s+does\s+one|
+            what\s+is\s+the\s+(?:syntax|command|usage|flag|option)|
+            explain\s+how|show\s+me\s+how|examples?\s+of\s+using|
+            manual\s+for|usage\s+of|syntax\s+for|man\s+page
+          )\b
+        /ix
+
+        LIVE_RECON_RX = /
+          \b(
+            (?:find|discover|enumerate|scan|sweep|probe|map)\s+
+            (?:live\s+)?(?:hosts?|ips?|targets?|subnet|network|range)|
+            live\s+hosts?\s+(?:can\s+you\s+)?find|
+            what\s+live\s+hosts|
+            ping\s+sweep\s+(?:of\s+)?(?:this|the|my)\s+
+            |(?:run|do|perform)\s+(?:a\s+)?(?:ping\s+)?sweep
+            |scan\s+(?:this|the|my)\s+(?:subnet|network|lan|range)
+          )\b
+        /ix
+
+        AUTH_SCOPE_RX = /
+          \b(
+            (?:in[-\s]?scope|authorized|authorised|engagement|written\s+permission|
+               bug\s*bounty|explicit(?:ly)?\s+allowed|lab\s+only|my\s+lab|
+               roe\b|rules?\s+of\s+engagement|i\s+own\s+this|owned\s+by\s+me|
+               permission\s+to\s+(?:scan|test|probe)|scope:\s*\S+)
+          )\b
+        /ix
+
+        public_class_method def self.request_intent(opts = {})
+          req = opts[:request].to_s
+          return :empty if req.strip.empty?
+
+          # Live-action recon takes precedence over bare "how to" when both appear
+          # only if the user clearly asks the agent to do the sweep here.
+          live = req.match?(LIVE_RECON_RX) && req.match?(
+            /\b(can\s+you|could\s+you|please|go\s+ahead|now|on\s+this\s+host|
+                this\s+subnet|this\s+network|find\s+(?:for\s+me|me)|discover)\b/ix
+          )
+          return :recon_act if live || (req.match?(LIVE_RECON_RX) && !req.match?(HOWTO_RX))
+          return :howto if req.match?(HOWTO_RX)
+          # Interrogative documentation without "how to"
+          if req.match?(/\b(what\s+(?:flags?|options?|switches?)|usage|syntax)\b/i) &&
+             !req.match?(/\b(run|execute|scan|find|discover)\b/i)
+            return :howto
+          end
+
+          :act
+        rescue StandardError
+          :act
+        end
+
+        public_class_method def self.recon_authorized?(opts = {})
+          req = opts[:request].to_s
+          return true if req.match?(AUTH_SCOPE_RX)
+
+          # Explicit engage flag from operator / REPL
+          v = (PWN::Env.dig(:ai, :agent, :recon_authorized) if defined?(PWN::Env))
+          return true if v == true || v.to_s =~ /\A(1|true|yes|on)\z/i
+
+          false
+        rescue StandardError
+          false
+        end
+
+        # Pure how-to: one text-only chat (no tools, no plan_first, no task recon).
+        private_class_method def self.answer_howto(opts = {})
+          request = opts[:request].to_s
+          session_id = opts[:session_id]
+          system_role_content = opts[:system_role_content].to_s
+          engine = active_engine
+          mod_name = ENGINE_MODS[engine]
+          raise "ERROR: Unsupported AI engine for agent loop: #{engine}" unless mod_name
+
+          mod = Object.const_get(mod_name)
+          howto_sys = <<~SYS
+            #{system_role_content}
+
+            INTENT: HOW-TO / DOCUMENTATION (this turn only)
+              The user wants a concise explanation of how to use a tool or technique.
+              Answer in plain US English with example command lines only.
+              Do NOT call tools. Do NOT plan multi-step work. Do NOT run scans,
+              probes, rubocop, rake, or host verification. Do NOT invent task
+              traces or internal planner monologue. Do NOT claim you ran anything.
+              If the topic is network discovery, give safe lab examples and note
+              that live sweeps need explicit in-scope authorization.
+          SYS
+
+          txt =
+            if mod.respond_to?(:chat)
+              r = mod.chat(
+                request: request,
+                system_role_content: howto_sys,
+                spinner: true
+              )
+              if r.is_a?(Hash)
+                (r.dig(:choices, -1, :content) || r.dig(:choices, -1, :text) || r[:content]).to_s
+              else
+                r.to_s
+              end
+            else
+              # chat_with_tools without tools
+              messages = [
+                { role: 'system', content: howto_sys },
+                { role: 'user', content: request }
+              ]
+              msg = call_engine(messages: messages, tools: nil)
+              msg.is_a?(Hash) ? msg[:content].to_s : msg.to_s
+            end
+
+          txt = txt.to_s.strip
+          if txt.empty?
+            txt = <<~FALLBACK
+              Example hping3 ICMP ping sweep (lab / authorized targets only):
+
+                # Needs root/CAP_NET_RAW for raw sockets
+                sudo hping3 -1 --flood -c 1 192.168.1.x
+                # Or loop a /24 carefully (slow rate to avoid DoS):
+                for i in $(seq 1 254); do
+                  sudo hping3 -1 -c 1 -N $i 192.168.1.$i 2>/dev/null | grep -q "icmp"                      && echo "up 192.168.1.$i"
+                done
+
+              Prefer intentional CIDR targeting over blind sweeps. Live host
+              discovery without explicit engagement/scope authorization is out
+              of bounds for this agent.
+            FALLBACK
+          end
+
+          append_session(session_id: session_id, role: 'user', content: request)
+          append_session(session_id: session_id, role: 'assistant', content: txt)
+          if defined?(Learning) && should_auto_introspect?(local: local_engine?, turn_fails: {}, iter: 0)
+            Learning.auto_introspect(
+              session_id: session_id,
+              request: request,
+              final: txt,
+              predicted: 0.9,
+              plan: ['Explain tool usage without live recon'],
+              ts_state: nil
+            )
+          end
+          txt
+        rescue StandardError => e
+          warn "[pwn-ai/loop] answer_howto swallowed: #{e.class}: #{e.message}"
+          "Could not produce a how-to answer (#{e.class}: #{e.message}). Retry with a frontier engine or ask for a specific flag/example."
+        end
+
+        private_class_method def self.refuse_unauthorized_recon(opts = {})
+          request = opts[:request].to_s
+          session_id = opts[:session_id]
+          txt = <<~REFUSE
+            I will not run a live subnet sweep or raw-socket host discovery from this agent without explicit in-scope authorization.
+
+            Your request looks like active recon on "this" network/subnet. To proceed, restate with engagement language such as:
+              - "authorized engagement" / "in-scope" / "lab only" / "I own this network"
+              - or set PWN::Env[:ai][:agent][:recon_authorized] = true for this session
+
+            If you only wanted the command syntax, ask: how to do a ping sweep of a subnet using hping3?
+          REFUSE
+          append_session(session_id: session_id, role: 'user', content: request)
+          append_session(session_id: session_id, role: 'assistant', content: txt)
+          txt
+        end
+
         # Supported Method Parameters::
         # final = PWN::AI::Agent::Loop.run(
         #   request: 'required - what the human typed',
@@ -1127,6 +1296,20 @@ module PWN
           expose_current_session(session_id: session_id)
           Mistakes.check_user_correction(request: request, session_id: session_id) if defined?(Mistakes)
 
+          intent = request_intent(request: request)
+          Thread.current[:pwn_request_intent] = intent
+          Thread.current[:pwn_recon_authorized] = recon_authorized?(request: request)
+          # How-to: never enter plan_first / task recon / tool thrash (ollama/openwebui).
+          if intent == :howto && opts[:force_tools] != true
+            return answer_howto(
+              request: request,
+              session_id: session_id,
+              system_role_content: system_role_content
+            )
+          end
+          # Live recon without authorization: refuse rather than probe the LAN.
+          return refuse_unauthorized_recon(request: request, session_id: session_id) if intent == :recon_act && !recon_authorized?(request: request) && opts[:force_tools] != true
+
           # Initial tool pool from the user request (bootstrap only). After
           # TaskSummarizer.emit_plan! we re-rank using English tangible tasks
           # so generated tasks — not the bare request — drive which tools
@@ -1153,7 +1336,8 @@ module PWN
           Thread.current[:pwn_plan_predicted] = nil
           cal_state = calibration_state
           force_plan = cal_state[:force_plan]
-          if (force_plan || agent_flag(key: :plan_first, default: local) || budget_exhaustion_hot?) && !Array(tools).empty?
+          skip_plan = (intent == :howto)
+          if !skip_plan && (force_plan || agent_flag(key: :plan_first, default: local) || budget_exhaustion_hot?) && !Array(tools).empty?
             predicted = plan_first(messages: messages, request: request, ts_state: ts_state)
             # P22 — prefer explicit return; fall back to thread stash
             predicted = Thread.current[:pwn_plan_predicted] if predicted.nil?
@@ -1483,6 +1667,10 @@ module PWN
               Supported engines: #{ENGINE_MODS.keys.join(', ')}
               Set PWN::Env[:ai][:active] to choose; PWN::Env[:ai][:agent][:max_iters] to bound.
 
+              Intent routing (all engines; critical for ollama/openwebui):
+                how-to / usage questions → text-only explanation (no tools, no plan_first)
+                live subnet sweeps without scope language → refuse
+                :recon_authorized    - Boolean session flag to allow raw-socket / sweep tools
               Local-model scaffolding (PWN::Env[:ai][:agent]):
                 :plan_first          - Boolean, plan-then-act pre-pass (default: local engine :ollama/:openwebui)
                 :tool_router         - Boolean/nil, slim Registry.definitions (nil=auto on for ollama)

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

@@ -70,6 +70,18 @@ module PWN
               irreversible destructive action, or missing external decision is
               strictly required. Partial progress reports without completing the
               goal are incorrect behavior.
+
+            INTENT AND SCOPE
+              Match effort to the user ask. Pure how-to / syntax / usage questions
+              get a concise explanation with example commands only — no tool calls,
+              no multi-step recon plan, no live probes, no rubocop/rake/docs side
+              quests, and no invented planner or verification monologue.
+              Do not treat process_sop_* or operator_pref_* memory about code
+              hygiene as the current user goal unless they asked to change code.
+              Live subnet sweeps, raw-socket discovery (hping3/nmap -sn mass
+              probes, etc.) require explicit in-scope / authorized engagement
+              language from the user. Without it, refuse the live scan and offer
+              the command syntax instead.
           PROMPT
         end
 
@@ -119,11 +131,18 @@ module PWN
 
           limit = opts[:limit] || 25
           req   = opts[:request]
-          ctx   = if req && defined?(PWN::MemoryIndex) && PWN::MemoryIndex.available?
-                    PWN::MemoryIndex.to_context(query: req, limit: limit)
-                  else
-                    PWN::Memory.to_context(limit: limit)
-                  end
+          # How-to / non-code asks: do not let code-hygiene SOPs dominate local context.
+          drop_hygiene = req.to_s.match?(/\b(how\s+to|how\s+do\s+i|syntax|usage|hping|nmap|ping\s+sweep|live\s+hosts?)\b/i) &&
+                         !req.to_s.match?(%r{\b(rubocop|rake|rspec|/opt/pwn|refactor|documentation|commit)\b}i)
+          ctx = if req && defined?(PWN::MemoryIndex) && PWN::MemoryIndex.available?
+                  PWN::MemoryIndex.to_context(query: req, limit: limit, drop_hygiene_sops: drop_hygiene)
+                else
+                  PWN::Memory.to_context(limit: limit)
+                end
+          if drop_hygiene && ctx.to_s.match?(/process_sop_.*rubocop|operator_pref_docs_after_rubocop|docs_after_rubocop_rake/i)
+            # Fallback filter when MemoryIndex unavailable or still returns SOPs
+            ctx = ctx.to_s.lines.grep_v(/process_sop_.*(?:rubocop|rake|docs_after)|operator_pref_docs_after_rubocop|code_hygiene/i).join
+          end
           ctx.to_s.strip.empty? ? '' : "MEMORY#{ctx}\n\n"
         rescue StandardError
           ''

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

@@ -51,12 +51,19 @@ module PWN
           should perform. Rules:
           - 2..12 tasks. Each task is one coherent unit of work (may need many tools).
           - Plain US English. Imperative mood. No tool names, paths, or shell commands.
+          - Match effort to intent: pure how-to / usage / syntax questions get 1..2
+            documentation tasks only (explain usage, present examples). Do NOT invent
+            live recon, host discovery, rubocop, rake, or code-verification steps for
+            those. Only plan discovery/recon when the user asked to scan/find live hosts.
           - Cover discovery/recon, the core work, verification, and the requested
-            deliverable/format when relevant.
+            deliverable/format ONLY when relevant to THIS request.
           - Tailor steps to THIS request only — do not reuse a canned domain script.
           - Last task should verify or present the final result when that fits.
+          - Never append unrelated repo hygiene (rubocop/rake/docs) unless the user
+            asked to change code under /opt/pwn.
           - Output ONLY a JSON array of strings. No markdown, no prose, no keys.
           Example: ["determine the local IPv4 subnet","find live hosts on that subnet","present live hosts as JSON"]
+          How-to example: ["Explain hping3 ping-sweep syntax with safe lab examples","Present the commands clearly"]
         SYS
 
         public_class_method def self.enabled?
@@ -319,11 +326,33 @@ module PWN
           goal.empty? ? [] : normalize_task_list(tasks: ["Carry out: #{goal}"], goal: goal)
         end
 
+        private_class_method def self.howto_goal?(opts = {})
+          goal = opts[:goal].to_s
+          return true if defined?(PWN::AI::Agent::Loop) &&
+                         PWN::AI::Agent::Loop.respond_to?(:request_intent) &&
+                         PWN::AI::Agent::Loop.request_intent(request: goal) == :howto
+
+          goal.match?(/\b(how\s+to|how\s+do\s+i|how\s+can\s+i|syntax|usage of|explain how|show me how)\b/i)
+        rescue StandardError
+          false
+        end
+
         private_class_method def self.normalize_task_list(opts = {})
           goal = opts[:goal]
           list = Array(opts[:tasks]).map { |t| t.to_s.gsub(/\s+/, ' ').strip }.reject(&:empty?).uniq
           list = ["Carry out: #{goal}"] if list.empty?
-          # Ensure a verify/close step when the model omitted one.
+          # Strip contaminated repo-hygiene tasks on non-code requests.
+          unless goal.to_s.match?(%r{\b(rubocop|rake|rspec|/opt/pwn|refactor|patch|commit|documentation)\b}i)
+            list.reject! { |t| t.match?(/\b(rubocop|rvmsudo\s+rake|bundle\s+exec\s+rake|fix rake|lint offenses)\b/i) }
+            list = ["Carry out: #{goal}"] if list.empty?
+          end
+          # How-to: keep explanation-only plan; never force recon/verify thrash.
+          if howto_goal?(goal: goal)
+            list = list.first(2)
+            list = ['Explain the requested tool usage with concrete examples', 'Present the answer clearly'] if list.empty?
+            return list.first(MAX_PLAN_TASKS)
+          end
+          # Ensure a verify/close step when the model omitted one (act/recon only).
           list << 'Verify the result and report completion' unless list.last.to_s.match?(/verif|test|confirm|rubocop|rake|accept|done|close|summar|json|yaml|table|present|format|convert|report completion|report results/i)
           list.first(MAX_PLAN_TASKS)
         end
@@ -584,6 +613,12 @@ module PWN
             return tasks
           end
 
+          if howto_goal?(goal: goal_text)
+            tasks << "Explain how to do: #{truncate_goal(goal: goal_text)}"
+            tasks << 'Present clear example commands only (no live probes)'
+            return tasks
+          end
+
           tasks << "Understand the request: #{truncate_goal(goal: goal_text)}"
           tasks << "Carry out the core work for: #{truncate_goal(goal: goal_text)}"
 
@@ -594,7 +629,9 @@ module PWN
             tasks << 'Present the final results in the requested format'
           end
 
-          tasks << 'Run specs, rubocop, and/or rake to verify' if goal_lc.match?(/\b(test|spec|rubocop|rake|lint|verify|accept)\b/)
+          # Only when the user actually asked about tests/lint — not bare "verify".
+          tasks << 'Run specs, rubocop, and/or rake to verify' if goal_lc.match?(/\b(test|spec|rubocop|rake|lint)\b/) &&
+                                                                  goal_lc.match?(%r{\b(/opt/pwn|code|patch|refactor|commit)\b})
 
           tasks
         rescue StandardError

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

@@ -46,6 +46,38 @@ PWN::AI::Agent::Registry.register(
     timeout = (args[:timeout] || 120).to_i
     raise ArgumentError, 'command is required' if cmd.empty?
 
+    # Guard: raw-socket / subnet discovery without explicit engagement auth.
+    # Intent routing should short-circuit most of these; this is defense-in-depth
+    # when a local model still emits hping3/nmap sweeps mid-loop.
+    recon_blocked = begin
+      auth = Thread.current[:pwn_recon_authorized] == true
+      unless auth
+        v = (PWN::Env.dig(:ai, :agent, :recon_authorized) if defined?(PWN::Env))
+        auth = v == true || v.to_s =~ /\A(1|true|yes|on)\z/i
+      end
+      !auth && cmd.match?(
+        %r{
+          (?:^|[;&|\s])(?:sudo\s+)?hping3?(?:\s|$).*(?:-1|--icmp|--flood|/[0-9]{1,2}|seq\s+|for\s+)
+          |(?:^|[;&|\s])(?:sudo\s+)?nmap\b[^\n]*(?:-sn|-sP|-PE|-PP|-PM)[^\n]*(?:/[0-9]{1,2}|\d+\.\d+\.\d+\.\d+)
+          |(?:^|[;&|\s])(?:sudo\s+)?masscan\b
+          |(?:^|[;&|\s])(?:sudo\s+)?nping\b
+          |(?:^|[;&|\s])(?:sudo\s+)?fping\b[^\n]*/
+          |for\s+\w+\s+in\s+\$?\(?seq[^)]*\)?[^;]*;\s*do\s[^;]*(?:hping|ping\s+-c|nmap)
+        }ix
+      )
+    rescue StandardError
+      false
+    end
+    if recon_blocked
+      msg = "[pwn-ai/guard] blocked unauthorized recon/sweep command. Need explicit in-scope authorization on the user request or PWN::Env[:ai][:agent][:recon_authorized]=true. Refused: #{cmd[0, 200]}"
+      return {
+        stdout: '',
+        stderr: msg,
+        exit: 126,
+        error: 'unauthorized_recon_blocked'
+      }
+    end
+
     stdout = +''
     stderr = +''
     exitstatus = nil

data/lib/pwn/memory_index.rb

@@ -84,8 +84,23 @@ module PWN
     # identical so PromptBuilder needs no special-casing.
 
     public_class_method def self.to_context(opts = {})
-      hits = recall_semantic(query: opts[:query], limit: opts[:limit] || 6)
-      return PWN::Memory.to_context(limit: opts[:limit] || 6) if hits.empty?
+      limit = opts[:limit] || 6
+      # Fetch extra when filtering hygiene SOPs so we still fill the budget.
+      fetch_n = opts[:drop_hygiene_sops] ? [limit * 3, 18].max : limit
+      hits = recall_semantic(query: opts[:query], limit: fetch_n)
+      return PWN::Memory.to_context(limit: limit) if hits.empty?
+
+      if opts[:drop_hygiene_sops]
+        hits = hits.reject do |h|
+          k = h[:key].to_s
+          v = h[:value].to_s
+          k.match?(/process_sop_.*(?:rubocop|rake|docs_after|code_hygiene)|operator_pref_docs_after_rubocop/i) ||
+            v.match?(/\b(?:bundle exec )?rubocop\b.*\brake\b|docs_after_rubocop_rake|Documentation after code changes/i)
+        end.first(limit)
+        return PWN::Memory.to_context(limit: limit) if hits.empty?
+      else
+        hits = hits.first(limit)
+      end
 
       ctx = "\n\nPERSISTENT MEMORY (relevance-ranked for this request - use PWN::Memory.remember to store new ones):\n"
       hits.each do |h|

data/lib/pwn/plugins/repl.rb

@@ -949,14 +949,15 @@ module PWN
           description 'Edit the pwn.yaml configuration file.'
 
           def process
-            pi = pry_instance
             pwn_env_path = PWN::Env[:driver_opts][:pwn_env_path] ||= "#{Dir.home}/.pwn/pwn.yaml"
             unless File.exist?(pwn_env_path)
               puts "ERROR: pwn environment file not found: #{pwn_env_path}"
               return
             end
 
-            pwn_dec_path = PWN::Env[:driver_opts][:pwn_dec_path] ||= "#{Dir.home}/.pwn/pwn.decryptor.yaml"
+            # Prefer driver_opts (set by Config.refresh_env); fall back to the
+            # canonical sidecar path Config uses: <pwn.yaml>.decryptor
+            pwn_dec_path = PWN::Env[:driver_opts][:pwn_dec_path] ||= "#{pwn_env_path}.decryptor"
             unless File.exist?(pwn_dec_path)
               puts "ERROR: pwn decryptor file not found: #{pwn_dec_path}"
               return
@@ -966,11 +967,39 @@ module PWN
             key = decryptor[:key]
             iv = decryptor[:iv]
 
-            PWN::Plugins::Vault.edit(
-              file: pwn_env_path,
-              key: key,
-              iv: iv
-            )
+            # Vault.edit decrypts -> opens editor -> encrypts and only sets
+            # Pry.config.refresh_pwn_env = true. PWN::Config.refresh_env (which
+            # raises RuntimeError on invalid pwn.yaml) historically ran later in
+            # the PS1 hook, OUTSIDE this command - so the old rescue/retry never
+            # saw Config errors. Validate here: on RuntimeError print the error,
+            # prompt "Press Enter to Resolve", wait on $stdin.gets, then re-open
+            # the editor until the vault loads cleanly.
+            loop do
+              PWN::Plugins::Vault.edit(
+                file: pwn_env_path,
+                key: key,
+                iv: iv
+              )
+
+              begin
+                PWN::Config.refresh_env(
+                  pwn_env_path: pwn_env_path,
+                  pwn_dec_path: pwn_dec_path,
+                  key: key,
+                  iv: iv
+                )
+                break
+              rescue RuntimeError => e
+                # Keep the prior in-memory Env usable if the operator aborts
+                # further edits; otherwise the next PS1 tick would raise again.
+                Pry.config.refresh_pwn_env = false if defined?(Pry)
+                print "\001\e[33m\002"
+                puts e.message
+                print 'Press ENTER to resolve...'
+                print "\001\e[0m\002\s"
+                $stdin.gets
+              end
+            end
           rescue StandardError => e
             raise e
           end

data/lib/pwn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PWN
-  VERSION = '0.5.668'
+  VERSION = '0.5.669'
 end

data/spec/lib/pwn/ai/agent/loop_spec.rb

@@ -145,6 +145,37 @@ describe PWN::AI::Agent::Loop do
     end
   end
 
+  describe 'intent routing (ollama/openwebui how-to + recon guard)' do
+    it 'classifies pure how-to vs live recon vs act' do
+      expect(described_class.request_intent(request: 'how to do a ping sweep of a subnet using hping3?')).to eq(:howto)
+      expect(described_class.request_intent(request: 'using hping3 what live hosts can you find in this subnet?')).to eq(:recon_act)
+      expect(described_class.request_intent(request: 'refactor Loop.run and run rubocop')).to eq(:act)
+    end
+
+    it 'recon_authorized? requires scope language or env flag' do
+      expect(described_class.recon_authorized?(request: 'find live hosts on this subnet')).to eq(false)
+      expect(described_class.recon_authorized?(request: 'authorized engagement: find live hosts on this lab subnet')).to eq(true)
+      allow(PWN::Env).to receive(:dig).and_call_original
+      allow(PWN::Env).to receive(:dig).with(:ai, :agent, :recon_authorized).and_return(true)
+      expect(described_class.recon_authorized?(request: 'find live hosts')).to eq(true)
+    end
+
+    it 'run short-circuits how-to without plan_first or tools' do
+      src = File.read(described_class.method(:run).source_location.first)
+      expect(src).to match(/request_intent/)
+      expect(src).to match(/answer_howto/)
+      expect(src).to match(/refuse_unauthorized_recon/)
+      expect(src).to match(/intent == :howto/)
+      expect(src).to match(/skip_plan/)
+    end
+
+    it 'answer_howto does not register shell tool use in source path' do
+      src = File.read(described_class.method(:run).source_location.first)
+      # how-to return happens before task_summary_plan!
+      expect(src).to match(/if intent == :howto.*?return answer_howto/m)
+    end
+  end
+
   describe '.openai_wire_messages' do
     it 'stringifies Hash function.arguments and drops private keys' do
       wire = described_class.openai_wire_messages(