pikuri-workspace 0.0.7 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3918af9bb28c07c5706f2738899b05cda0a9c65a3a59b7e10799a98c8b8bc0b8
-  data.tar.gz: 142a335f7f42891c0f9f5cd9964dc31202691f1fa470fef526ad61280a2f8bff
+  metadata.gz: 120a595848652290fe60f2505a6cf74ff7d8f83764da5a22b89c7f71c95b5796
+  data.tar.gz: cb6348c77246df64f29b03cdb6d846abbd4bfa97f9c4830c155fd978ea1b65cb
 SHA512:
-  metadata.gz: a20b8468fa2fc9cbed1aed620b645443cc6fb8969aad611de24e8620c88efe16b692265aabb5520d0c5231f5f6da2c31a0cae3f815eed2fd4e7840ef13e637d5
-  data.tar.gz: b5c6f5bc61a0f45641127a252c5f55bac9e0d3f5bb5ee577abeed31419859454daf7b7db26a0f5880cd638304ab3bd7da5d63b910093c4223372f21b5a97f2cb
+  metadata.gz: a3d79a08b112424947f74667a24750e82a86539b61a1edfdbabb2ab2270d610d0d91442c05aab6f186f869dff70376259fecc6172ca60c23d43560797e536de2
+  data.tar.gz: 1fe906ff062d7dc37e1666f8f2ebf56c18eb3e7bc389fcef5bf8f6334548f1cc10684113f2d1331af11b92befd33ba72f5dac217d42ef02cc668b6f66262f3c6

data/README.md

@@ -8,8 +8,11 @@ Self-contained "operate on a directory tree" toolkit:
   project root + explicit readable / writable prefix lists, with an
   optional ephemeral temp playground. Rejects `..`-escapes and
   symlinks that resolve outside the configured roots.
-- `Pikuri::Workspace::Confirmer` — abstract base + `AUTO_APPROVE` /
-  `TERMINAL` for user-state mutations.
+- `Pikuri::Workspace::Confirmer` — abstract base for approving
+  user-state mutations, plus `AUTO_APPROVE` (headless) and `Terminal`
+  (stdin/stdout). `Terminal` is written for pikuri's own single-threaded
+  demo scripts — a real app implements this seam itself and reads
+  `Terminal` as the worked example.
 - Five file tools: `Pikuri::Workspace::Read`,
   `Pikuri::Workspace::Write`, `Pikuri::Workspace::Edit`,
   `Pikuri::Workspace::Grep`, `Pikuri::Workspace::Glob`.
@@ -31,7 +34,8 @@ require 'pikuri-core'
 require 'pikuri-workspace'
 
 workspace = Pikuri::Workspace::Filesystem.new(project_root: Dir.pwd)
-confirmer = Pikuri::Workspace::Confirmer::TERMINAL
+# Fine for a script like this one; write your own for a real app.
+confirmer = Pikuri::Workspace::Confirmer::Terminal.new
 
 agent = Pikuri::Agent.new(
   transport: ...,
@@ -57,7 +61,7 @@ writable playground via `Dir.mktmpdir` — its path is exposed as
 
 - **Narrative walkthrough:** the "Workspace seam" and "Confirmer
   seam" sections of
-  [chapter 8 of the pikuri guide](../docs/guide/08-code.md) — what
+  [the coding-agent chapter of the pikuri guide](../book/code.md) — what
   each kwarg of `Filesystem.new` controls, when to use the
   `AllowAll` variant, and how the seams fit alongside `Sandbox`.
 - **API reference:** browse the YARD docs at

data/lib/pikuri/workspace/confirmer/terminal.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require 'rainbow'
+require 'reline'
+require 'tmpdir'
+
+module Pikuri
+  module Workspace
+    class Confirmer
+      # Stdin/stdout implementation, written for pikuri's own single-threaded
+      # +bin/+ scripts — **not a component to build a host on**. A real host
+      # (TUI, web) owns its screen and its event loop, so it cannot have a
+      # library class calling +puts+ and +gets+ behind its back; it writes its
+      # own {Confirmer} and this is the worked example to read while doing it.
+      # The one piece to carry over is not the chrome but the warning-gated
+      # retype below — everything else is a terminal's answer to a problem your
+      # UI will answer differently.
+      #
+      # Renders the request as up to several lines
+      # (a leading +puts+ separates it from any streamed output above):
+      #
+      # 1. a bold-yellow warning block (one line per {Pikuri::Sanitizer::Warning})
+      #    when the sanitizer flagged the question or detail
+      # 2. the question, bold
+      # 3. the detail, dim — omitted when +nil+
+      # 4. the answer cue
+      #
+      # Question and detail pass through {Pikuri::Sanitizer}, which neutralizes
+      # control bytes (else a model could craft +"\rrm -rf ~/"+ that overwrites
+      # the echoed line after the user read it) and reports *why* it was unsafe.
+      # Colors are Rainbow (self-disables on non-TTY).
+      #
+      # The human *chrome* — the one confirmer that renders a dialog and reads an
+      # answer. In its own file so the base seam carries no rendering deps
+      # (Rainbow / Reline / tmpdir ride only here).
+      #
+      # == The two flows
+      #
+      # A *non-editable* request (bash, write) gets +(y/n)?+: +y+ → {Approved},
+      # +n+ → {Rejected} (after an optional reason), EOF → {Rejected}, else
+      # re-prompt.
+      #
+      # An *editable* request (the +agent+ task) also offers +e+ to edit, and
+      # the warning set gates the pre-fill: the payload sent onward is RAW bytes
+      # but the terminal must *display* sanitized bytes, so pre-filling an
+      # editable buffer with raw bytes would reintroduce the control-byte attack.
+      # So a *clean* task offers +[y] approve  [e] edit  [n] reject+ (+e+ opens
+      # the raw task editable), a *flagged* task drops bare-approve and forces a
+      # retype: +[e] edit  [n] reject+. Honest limit: a terminal can't
+      # *structurally* forbid a rubber-stamp +y+ on a clean task — the pure
+      # no-rubber-stamp author seat is a richer-UI invariant; the warning-gated
+      # retype is the terminal's partial answer.
+      #
+      # == Sharing
+      #
+      # +P_one_agent+, and no lock is coming: this is the demo chrome, and one
+      # script is one agent. Two agents prompting at once would interleave their
+      # blocks on one terminal, and whichever +gets+ runs first reads the answer
+      # — so agent A could consume the +y+ meant for agent B and approve a
+      # command nobody read. There is no state to corrupt; the contended
+      # resource is the terminal and the human at it.
+      #
+      # That queue belongs to whoever owns the screen, and it needs more than a
+      # mutex — it has to say *which* agent is asking. Which is the same
+      # sentence as the paragraph at the top: a multi-agent host writes its own
+      # confirmer.
+      class Terminal < Confirmer
+        LOGGER = Pikuri.logger_for('Workspace::Confirmer')
+
+        # Maximum diff lines rendered before truncation — keeps a
+        # whole-file rewrite from scrolling the terminal off-screen.
+        DIFF_MAX_LINES = 300
+
+        # @param request [Request]
+        # @return [Approved, Rejected]
+        def ask(request:)
+          warnings = render(request)
+          if request.editable && !request.detail.nil?
+            ask_editable(request, clean: warnings.empty?)
+          else
+            ask_plain(request)
+          end
+        end
+
+        private
+
+        # Print the sanitized question / detail / warning block.
+        #
+        # @param request [Request]
+        # @return [Array<Pikuri::Sanitizer::Warning>] the flagged warnings
+        #   (empty when clean) — the caller gates the edit pre-fill on this.
+        def render(request)
+          question = Pikuri::Sanitizer.sanitize(request.question)
+          detail   = request.detail ? Pikuri::Sanitizer.sanitize(request.detail) : nil
+          raw_diff = request.change ? unified_diff(request.change) : nil
+          diff     = raw_diff ? Pikuri::Sanitizer.sanitize(raw_diff) : nil
+          warnings = question.warnings + (detail ? detail.warnings : []) + (diff ? diff.warnings : [])
+
+          puts
+          unless warnings.empty?
+            puts Rainbow('⚠ Suspicious content detected — read carefully before approving:').yellow.bold
+            warnings.each { |w| puts Rainbow("  ! #{w.explanation}").yellow }
+          end
+          puts Rainbow(question.text).bold
+          puts Rainbow(detail.text).dimgray if detail
+          print_diff(diff.text) if diff
+          warnings
+        end
+
+        # Render a unified diff of +change+ by shelling to +diff -u+ (routed
+        # through {Pikuri::Subprocess}; a richer client uses its own diff lib).
+        # Old/new bytes go to tempfiles under a self-cleaning dir. Returns the
+        # diff capped at {DIFF_MAX_LINES}, or +nil+ on any failure (empty diff,
+        # missing +diff+, IO error) — a cosmetic path, so it degrades to "no
+        # diff shown" rather than raising.
+        #
+        # @param change [Change]
+        # @return [String, nil]
+        def unified_diff(change)
+          Dir.mktmpdir('pikuri-diff-') do |dir|
+            old_f = File.join(dir, 'old')
+            new_f = File.join(dir, 'new')
+            out_f = File.join(dir, 'out')
+            File.binwrite(old_f, change.old || '')
+            File.binwrite(new_f, change.new)
+            File.open(out_f, 'w') do |o|
+              Pikuri::Subprocess.run(
+                'diff', '-u', '--label', "a/#{change.path}", '--label', "b/#{change.path}",
+                old_f, new_f, stdin_data: '', stdout: o, chdir: dir
+              )
+            end
+            text = File.read(out_f)
+            return nil if text.empty?
+
+            lines = text.lines
+            return text if lines.size <= DIFF_MAX_LINES
+
+            lines.first(DIFF_MAX_LINES).join + "… (#{lines.size - DIFF_MAX_LINES} more diff lines)\n"
+          end
+        rescue StandardError => e
+          LOGGER.warn("diff render failed (#{e.class}: #{e.message}); confirming without a diff")
+          nil
+        end
+
+        # Print a sanitized unified diff, coloring +added+/-removed/@@hunk@@
+        # lines. Sanitization ran in {#render}; this only adds color.
+        #
+        # @param text [String] sanitized diff text
+        # @return [void]
+        def print_diff(text)
+          text.each_line do |line|
+            body = line.chomp
+            puts(case body[0]
+                 when '+' then Rainbow(body).green
+                 when '-' then Rainbow(body).red
+                 when '@' then Rainbow(body).cyan
+                 else Rainbow(body).dimgray
+                 end)
+          end
+        end
+
+        # The +(y/n)?+ flow, returning {Approved}/{Rejected} and prompting for a
+        # decline reason on +n+.
+        #
+        # @param request [Request]
+        # @return [Approved, Rejected]
+        def ask_plain(request)
+          puts '(y/n)?'
+          $stdout.flush
+          loop do
+            line = $stdin.gets
+            return Rejected.new(reason: nil) if line.nil?
+
+            answer = line.strip.downcase
+            return Approved.new(new_request_detail: request.detail) if answer == 'y' || answer == 'yes'
+            return Rejected.new(reason: read_reason) if answer == 'n' || answer == 'no'
+
+            print 'Please answer y or n: '
+            $stdout.flush
+          end
+        end
+
+        # The editable flow: approve-as-is (clean only), edit, or reject.
+        #
+        # @param request [Request]
+        # @param clean [Boolean] whether the payload passed the sanitizer
+        #   (gates the pre-fill and the bare-approve path)
+        # @return [Approved, Rejected]
+        def ask_editable(request, clean:)
+          puts(clean ? '[y] approve  [e] edit  [n] reject' : '⚠ retype required — [e] edit  [n] reject')
+          $stdout.flush
+          loop do
+            line = $stdin.gets
+            return Rejected.new(reason: nil) if line.nil?
+
+            answer = line.strip.downcase
+            if clean && (answer == 'y' || answer == 'yes')
+              return Approved.new(new_request_detail: request.detail)
+            end
+            if answer == 'e' || answer == 'edit'
+              return Approved.new(new_request_detail: read_edited(initial: request.detail, prefill: clean))
+            end
+            return Rejected.new(reason: read_reason) if answer == 'n' || answer == 'no'
+
+            print(clean ? 'Please answer y, e, or n: ' : 'Please answer e or n: ')
+            $stdout.flush
+          end
+        end
+
+        # Read the human's (re)authored task.
+        #
+        # @param initial [String] the raw payload to pre-fill with
+        # @param prefill [Boolean] +true+ places +initial+ in the editable buffer
+        #   (clean payloads only); +false+ forces a fresh line — the retype for
+        #   flagged input, which never puts raw bytes on the terminal.
+        # @return [String] the edited text (may be empty)
+        def read_edited(initial:, prefill:)
+          if prefill
+            Reline.pre_input_hook = lambda do
+              Reline.insert_text(initial)
+              Reline.pre_input_hook = nil
+            end
+          end
+          (Reline.readline('task> ', false) || '').chomp
+        ensure
+          Reline.pre_input_hook = nil
+        end
+
+        # Prompt for an optional decline reason (steering handed back to the
+        # model).
+        #
+        # @return [String, nil] the trimmed reason, or +nil+ for blank / EOF
+        def read_reason
+          print 'Reason (optional, Enter to skip): '
+          $stdout.flush
+          line = $stdin.gets
+          return nil if line.nil?
+
+          reason = line.strip
+          reason.empty? ? nil : reason
+        end
+      end
+    end
+  end
+end

data/lib/pikuri/workspace/confirmer.rb

@@ -1,156 +1,173 @@
 # frozen_string_literal: true
 
-require 'rainbow'
-
 module Pikuri
   module Workspace
-    # Port for asking the user to confirm a potentially destructive tool
-    # operation — currently {Pikuri::Code::Bash} (every command) and
-    # {Write} (overwrite of an existing file with non-identical
-    # content). Subclass and implement {#confirm?}.
+    # Port for resolving a "may I do this?" confirmation to a decision —
+    # currently {Pikuri::Code::Bash}, {Write}, and the +agent+ tool's
+    # delegation gate. Subclass and implement {#ask}.
+    #
+    # == The one job: resolve a {Request} to a decision
+    #
+    # A Confirmer takes a semantic {Request} and returns {Approved} or
+    # {Rejected}. That is *all*: it carries **no tool policy** and never
+    # classifies the request's *content* (no filesystem reads, no command
+    # parsing, no notion of "passive"). Two shipped implementations:
+    #
+    # * {Terminal} — the human *chrome*: shows the request and reads the answer.
+    #   In +confirmer/terminal.rb+ so this seam file stays free of rendering deps.
+    #   Written for pikuri's own single-threaded +bin/+ scripts and best read as
+    #   the worked example — a TUI or web host implements this seam itself.
+    # * {AutoApprove} — the headless stance: ignores the request and
+    #   blanket-approves (+--yolo+ / dev-container). Request-independent, so it
+    #   encodes no policy either.
+    #
+    # Sharing is per implementation, and the two shipped ones differ:
+    # {AutoApprove} is +P_stateless+ and shares freely, while {Terminal} is
+    # +P_one_agent+ because concurrent agents fight over one human's keystrokes.
+    # A confirmer written for a multi-agent host owns that queueing — and owns
+    # naming which agent is asking, which is why the queue can't usefully live
+    # down here.
+    #
+    # Content classification ("is this bash command provably passive, skip the
+    # prompt?") deliberately does *not* live here — it's a tool concern
+    # ({Pikuri::Code::Bash} takes a separate +passive_detector:+ predicate,
+    # falling through to this confirmer only for commands it can't pre-approve).
+    # Keeping them apart lets one stateless chrome serve every tool.
+    #
+    # == The return type: {Approved} / {Rejected}
     #
-    # == Why a Boolean return
+    # {#ask} returns {Approved} (the possibly-edited {Request#detail} to act on)
+    # or {Rejected} (an optional decline reason); callers pattern-match:
     #
-    # v1 returns +true+ or +false+. Two paths-not-taken worth recording
-    # so a future reader knows the design space was considered:
+    #   case confirmer.ask(request: request)
+    #   in Confirmer::Approved(new_request_detail:) then ...act on it...
+    #   in Confirmer::Rejected(reason:)             then ...steer with it...
+    #   end
     #
-    # 1. Richer return (+:once+ / +:always+ / +:reject+) — rejected
-    #    because it creates decision fatigue, and the long-term answer
-    #    is to make confirmations rare rather than smart (sandboxing,
-    #    agentic destructiveness analysis).
-    # 2. Agentic destructive-or-not classifier — deferred to v2.
+    # {#confirm?} is the derived boolean convenience for gates ({Write},
+    # {Pikuri::Code::ExitPlanMode}) needing neither the payload nor the reason.
+    # Two orthogonal axes ride the richer return:
     #
-    # The intended escape from confirmation prompts today is sandboxing
-    # (docker / dev-container) plus the +--yolo+ flag on +bin/pikuri-code+
-    # (which wires {AUTO_APPROVE} instead of {TERMINAL}).
+    # 1. *Editing* (opt-in via {Request#editable}) — when +detail+ is the
+    #    verbatim actionable payload (the +agent+ task, where +detail == task+),
+    #    a confirmer may let the human *rewrite* it — "human as author, not
+    #    approver". Bash's +"$ <command>"+ is a decorated display string, so it
+    #    stays non-editable.
+    # 2. *Reason* (universal) — any decline can carry typed steering ("use the
+    #    other library") back to the model as the next observation.
+    #
+    # A +:once+/+:always+ scope knob was *rejected*: it manages decision
+    # *fatigue*, a distinct axis, and the long-term answer to fatigue is making
+    # confirmations rare (sandboxing, +--yolo+, the +passive_detector+ skip),
+    # not smarter approval modes. (An agentic destructive-or-not classifier is a
+    # deferred v2.)
     #
     # == Seam discipline
     #
-    # Tools that need confirmation take a {Confirmer} via constructor and
-    # invoke {#confirm?} with a semantic {Request} — *what* is being
-    # asked, never *how* it should look. All presentation belongs to the
-    # confirmer implementation: color, the answer cue, answer parsing,
-    # and — security-relevant — neutralizing hostile bytes in
-    # LLM-supplied text. The chrome-independent half of that (escape
-    # control bytes, flag bidi / zero-width / homoglyph spoofs) is the
-    # shared {Pikuri::Sanitizer}; the medium-specific half stays with the
-    # renderer that knows its medium (a terminal prints the sanitized
-    # text directly; a web client wraps it in HTML-escaping). Tools do *not*
-    # call +gets+ / +puts+ directly — same lesson as listeners, keep IO
-    # at the seam so a TUI / web client can plug a different
-    # implementation in without touching tool code.
+    # Tools take a {Confirmer} via constructor and invoke {#ask} with a semantic
+    # {Request} — *what* is asked, never *how* it looks. All presentation
+    # belongs to the confirmer: color, the answer cue, parsing, the edit
+    # affordance, and — security-relevant — neutralizing hostile bytes in
+    # LLM-supplied text. The chrome-independent half (escape control bytes, flag
+    # bidi/zero-width/homoglyph spoofs) is the shared {Pikuri::Sanitizer}; the
+    # medium-specific half stays with the renderer (a terminal prints sanitized
+    # text; a web client HTML-escapes). Tools never call +gets+/+puts+ directly
+    # — keep IO at the seam so a TUI/web client plugs in without touching tools.
     class Confirmer
-      # The semantic payload of one confirmation. Two fields:
+      # The semantic payload of one confirmation:
       #
-      # * +question+ — one-line headline composed by the calling tool,
-      #   e.g. +"OK to overwrite foo.rb: 120 → 245 bytes?"+. The caller
-      #   owns the phrasing and punctuation; the renderer owns the
-      #   answer cue (+"(y/n)?"+, buttons, ...).
-      # * +detail+ — optional preformatted body, possibly multi-line:
-      #   the raw bash command for {Pikuri::Code::Bash}, +nil+ for
-      #   {Write}. Renderers typically display it monospaced / dimmed.
+      # * +question+ — one-line headline the tool composes (e.g. +"OK to
+      #   overwrite foo.rb: 120 → 245 bytes?"+); the caller owns phrasing, the
+      #   renderer owns the answer cue.
+      # * +detail+ — optional preformatted body: the raw bash command, the
+      #   +agent+ task, +nil+ for {Write}. When +editable+, the exact text the
+      #   human may rewrite, returned as {Approved#new_request_detail}.
+      # * +editable+ — whether the human may edit +detail+ (default +false+);
+      #   +true+ only when +detail+ is the verbatim payload (the +agent+ task),
+      #   never a decorated string (bash's +"$ <command>"+).
       #
-      # Both fields are RAW, straight from tool arguments the LLM
-      # composed (+detail+ is the command verbatim; +question+ may embed
-      # an LLM-written description). Renderers MUST neutralize them before
-      # display — route through {Pikuri::Sanitizer} (see {Terminal}), and
-      # additionally HTML-escape in a web client.
-      Request = Data.define(:question, :detail) do
+      # +question+/+detail+ are RAW LLM-composed text — renderers MUST neutralize
+      # them via {Pikuri::Sanitizer} (see {Terminal}), plus HTML-escape in a web
+      # client.
+      Request = Data.define(:question, :detail, :editable, :change) do
         # @param question [String] one-line headline; caller owns phrasing
-        # @param detail [String, nil] optional preformatted body
-        def initialize(question:, detail: nil)
+        # @param detail [String, nil] optional preformatted body / editable payload
+        # @param editable [Boolean] whether the human may rewrite +detail+
+        # @param change [Change, nil] optional structured file change; when
+        #   present a diff-capable chrome renders a diff of it (see {Change}).
+        def initialize(question:, detail: nil, editable: false, change: nil)
           super
         end
       end
 
-      # @param request [Request] semantic content composed by the
-      #   calling tool. The confirmer renders it (escaping for its
-      #   medium), poses the question, and parses the answer.
-      # @return [Boolean] +true+ iff approved
+      # A structured file change for a {Write}/{Edit} confirmation: the
+      # *semantic* change (path + old bytes + new bytes), not a pre-rendered
+      # string, so diff rendering stays the confirmer's job. {Terminal} shells
+      # to +diff+; a richer client renders the same {Change} its own way. +old+
+      # is the current bytes, or +nil+ for a new file.
+      Change = Data.define(:path, :old, :new)
+
+      # An approval carrying the text to act on: the human-authored (possibly
+      # edited) {Request#detail} when editable, else +detail+ verbatim.
+      Approved = Data.define(:new_request_detail)
+
+      # A decline carrying the human's optional steering reason (+nil+ if none),
+      # which the tool folds into the observation handed back to the model.
+      Rejected = Data.define(:reason)
+
+      # @param request [Request] semantic content composed by the calling
+      #   tool. The confirmer renders it (escaping for its medium), poses
+      #   the question, and parses the answer.
+      # @return [Approved, Rejected]
       # @raise [NotImplementedError] in the abstract base
-      def confirm?(request:)
-        raise NotImplementedError, "#{self.class}#confirm? must be implemented"
+      def ask(request:)
+        raise NotImplementedError, "#{self.class}#ask must be implemented"
       end
 
-      # Stdin/stdout implementation. Renders the request as up to several
-      # lines (a leading +puts+ guarantees separation from any streamed
-      # output the +Terminal+ listener may have produced just above):
-      #
-      # 1. a bold-yellow warning block — one line per
-      #    {Pikuri::Sanitizer::Warning} — shown only when the sanitizer
-      #    flagged something suspicious in the question or detail
-      # 2. the question, bold
-      # 3. the detail, dim — omitted when +nil+
-      # 4. the +(y/n)?+ cue
+      # Boolean convenience over {#ask} for gates needing neither the edited
+      # payload nor the reason.
       #
-      # Both question and detail pass through {Pikuri::Sanitizer}, which
-      # neutralizes control bytes — without it, a model could craft a
-      # command or description containing +"\rrm -rf ~/"+ that visually
-      # overwrites the echoed line after the user has already read it —
-      # and reports *why* it was unsafe so the user reads the warning
-      # before answering. Colors come from Rainbow (already in the
-      # dependency closure via pikuri-core), which self-disables on
-      # non-TTY output; the bold-yellow warning rendering is this
-      # terminal chrome's call, not the sanitizer's (the +Warning+
-      # carries plain text only).
+      # @param request [Request]
+      # @return [Boolean] +true+ iff approved
+      def confirm?(request:)
+        ask(request:).is_a?(Approved)
+      end
+
+      # Whether {#ask} can actually stop and wait for a person — the posture
+      # {Pikuri::Trifecta} reads when deciding whether a gated tool reaches the
+      # approver seat rather than counting as autonomous egress.
       #
-      # Then reads one line from +$stdin+ and parses it strictly:
+      # +true+ on the base class: a confirmer exists to ask, so a subclass that
+      # doesn't must say so, and one that forgets is credited with a gate it
+      # does not have only if it also forgets to be {AutoApprove}. Override to
+      # +false+ for any request-independent auto-answer.
       #
-      # * +"y"+ / +"yes"+ (case-insensitive, stripped) → +true+
-      # * +"n"+ / +"no"+ → +false+
-      # * EOF / Ctrl+D (+gets+ returns +nil+) → +false+, deliberate abort
-      # * anything else (blank, typo, +"maybe"+) → re-prompt with a short
-      #   "Please answer y or n: " line and loop
+      # This is what makes +--no-confirm+ re-harden a wiring's verdict on its
+      # own, with nothing in the detector special-casing the flag.
       #
-      # No retry cap; EOF eventually breaks adversarial input.
-      class Terminal < Confirmer
-        # @param request [Request]
-        # @return [Boolean]
-        def confirm?(request:)
-          question = Pikuri::Sanitizer.sanitize(request.question)
-          detail   = request.detail ? Pikuri::Sanitizer.sanitize(request.detail) : nil
-          warnings = question.warnings + (detail ? detail.warnings : [])
-
-          puts
-          unless warnings.empty?
-            puts Rainbow('⚠ Suspicious content detected — read carefully before approving:').yellow.bold
-            warnings.each { |w| puts Rainbow("  ! #{w.explanation}").yellow }
-          end
-          puts Rainbow(question.text).bold
-          puts Rainbow(detail.text).dimgray if detail
-          puts '(y/n)?'
-          $stdout.flush
-          loop do
-            line = $stdin.gets
-            return false if line.nil?
-
-            answer = line.strip.downcase
-            return true  if answer == 'y' || answer == 'yes'
-            return false if answer == 'n' || answer == 'no'
+      # @return [Boolean]
+      def blocks_on_human? = true
 
-            print 'Please answer y or n: '
-            $stdout.flush
-          end
-        end
-      end
-
-      # Approves everything. Used by +bin/pikuri-code --yolo+ (docker /
-      # dev-container mode) and by tool specs that don't want to
-      # coordinate stdin. The name +AUTO_APPROVE+ matches the public
-      # constant {AUTO_APPROVE}.
+      # Approves everything unedited — the headless "opted out of dialogs"
+      # stance. Request-independent, so it classifies nothing and stays a
+      # legitimate Confirmer. Used by +bin/pikuri-code --yolo+, downstream hosts'
+      # yolo modes, and specs that don't want to coordinate stdin.
       class AutoApprove < Confirmer
-        # @param request [Request] ignored
-        # @return [true]
-        def confirm?(request:)
-          true
+        # @param request [Request]
+        # @return [Approved] always, carrying +detail+ unchanged
+        def ask(request:)
+          Approved.new(new_request_detail: request.detail)
         end
-      end
 
-      # Shared singleton instance of {Terminal}. Stateless; reusable
-      # across tools and sub-agents.
-      TERMINAL = Terminal.new
+        # @return [Boolean] +false+ — nobody is asked, so a tool gated by this
+        #   confirmer holds autonomous egress however human-gated its wiring
+        #   looks on paper
+        def blocks_on_human? = false
+      end
 
-      # Shared singleton instance of {AutoApprove}.
+      # Shared stateless {AutoApprove} singleton, reusable across tools,
+      # sub-agents, and hosts' yolo modes. (No +TERMINAL+ singleton: {Terminal}
+      # is a demo chrome, and real front-ends bring their own.)
       AUTO_APPROVE = AutoApprove.new
     end
   end