pikuri-workspace 0.0.6 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52db0d4ce078507aa4a72cbc84d54a9433788f2a2d9a90ab883a9e469e6dea99
-  data.tar.gz: 107b34e1c3b387b4b68d542ff8ab2345885383a461c227a6b7aeb29973a4292e
+  metadata.gz: 120a595848652290fe60f2505a6cf74ff7d8f83764da5a22b89c7f71c95b5796
+  data.tar.gz: cb6348c77246df64f29b03cdb6d846abbd4bfa97f9c4830c155fd978ea1b65cb
 SHA512:
-  metadata.gz: 432af6cfc0a0f3555666e9c88accb0e9b6162af2c5f041c9ff71b10443f1681b8e70b9e46aa6c75ed12344357a286df087869b889f0a40aeb9635aa6c9a1e651
-  data.tar.gz: 362eb9437127e8734f15e09919ae7fb928e0d1b71fc9bb90a78f419cb7b4f52f29aebd323dd32e7bd491b0a73a3de60cff54a91e1756f24bcdc4e91d52de5fc2
+  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: ...,
@@ -49,7 +53,7 @@ end
 `Workspace` is the "look-but-don't-leak" guard around filesystem
 access. Read tools route through `#resolve_for_read(path)`; mutating
 tools route through `#resolve_for_write(path)` + the Confirmer's
-`#confirm?(prompt:)`. Pass `temp: true` to mint an ephemeral
+`#confirm?(request:)`. Pass `temp: true` to mint an ephemeral
 writable playground via `Dir.mktmpdir` — its path is exposed as
 `workspace.temp` and auto-removed at process exit.
 
@@ -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

@@ -2,94 +2,172 @@
 
 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}.
     #
-    # == Why a Boolean return
+    # == The one job: resolve a {Request} to a decision
     #
-    # v1 returns +true+ or +false+. Two paths-not-taken worth recording
-    # so a future reader knows the design space was considered:
+    # 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:
     #
-    # 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.
+    # * {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.
     #
-    # 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}).
+    # 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}
+    #
+    # {#ask} returns {Approved} (the possibly-edited {Request#detail} to act on)
+    # or {Rejected} (an optional decline reason); callers pattern-match:
+    #
+    #   case confirmer.ask(request: request)
+    #   in Confirmer::Approved(new_request_detail:) then ...act on it...
+    #   in Confirmer::Rejected(reason:)             then ...steer with it...
+    #   end
+    #
+    # {#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:
+    #
+    # 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 fully-composed prompt String. Tools do
-    # *not* call +gets+ / +puts+ directly — same lesson as listeners,
-    # keep IO at the seam so a future 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
-      # @param prompt [String] human-readable question composed by the
-      #   calling tool. The confirmer renders it and parses the answer;
-      #   it does NOT compose its own prompt content. Caller owns the
-      #   closing punctuation and any "(y/n)" cue.
-      # @return [Boolean] +true+ iff approved
-      # @raise [NotImplementedError] in the abstract base
-      def confirm?(prompt:)
-        raise NotImplementedError, "#{self.class}#confirm? must be implemented"
-      end
-
-      # Stdin/stdout implementation: prints +prompt+ on its own line (a
-      # leading +puts+ guarantees separation from any streamed output
-      # the +Terminal+ listener may have produced just above), reads one
-      # line from +$stdin+, parses it strictly:
+      # The semantic payload of one confirmation:
       #
-      # * +"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
+      # * +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>"+).
       #
-      # No retry cap; EOF eventually breaks adversarial input.
-      class Terminal < Confirmer
-        # @param prompt [String]
-        # @return [Boolean]
-        def confirm?(prompt:)
-          puts
-          puts prompt
-          $stdout.flush
-          loop do
-            line = $stdin.gets
-            return false if line.nil?
+      # +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 / 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
 
-            answer = line.strip.downcase
-            return true  if answer == 'y' || answer == 'yes'
-            return false if answer == 'n' || answer == 'no'
+      # 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)
 
-            print 'Please answer y or n: '
-            $stdout.flush
-          end
-        end
+      # 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 ask(request:)
+        raise NotImplementedError, "#{self.class}#ask must be implemented"
+      end
+
+      # Boolean convenience over {#ask} for gates needing neither the edited
+      # payload nor the reason.
+      #
+      # @param request [Request]
+      # @return [Boolean] +true+ iff approved
+      def confirm?(request:)
+        ask(request:).is_a?(Approved)
       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}.
+      # 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.
+      #
+      # +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.
+      #
+      # This is what makes +--no-confirm+ re-harden a wiring's verdict on its
+      # own, with nothing in the detector special-casing the flag.
+      #
+      # @return [Boolean]
+      def blocks_on_human? = true
+
+      # 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 prompt [String] ignored
-        # @return [true]
-        def confirm?(prompt:)
-          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