pikuri-code 0.0.6 → 0.1.0

data/lib/pikuri/code/bash.rb

@@ -1,84 +1,73 @@
 # frozen_string_literal: true
 
-require 'rainbow'
-
 module Pikuri
   module Code
     # The +bash+ tool — run an arbitrary shell command in the workspace.
-    # Instantiating +Code::Bash.new(workspace: ws, confirmer: c)+ produces
-    # a tool whose {Pikuri::Tool#to_ruby_llm_tool} wiring is identical to
-    # any bundled tool's. Same shape as {Pikuri::Workspace::Write}
-    # (workspace + confirmer captured by the +execute+ closure at
-    # construction).
+    # +Code::Bash.new(filesystem: fs, confirmer: c)+ produces a tool whose
+    # {Pikuri::Tool#to_ruby_llm_tool} wiring is identical to any bundled tool's
+    # (filesystem + confirmer captured by the +execute+ closure).
     #
     # == Confirmation
     #
-    # Every command requires confirmation. Bash composes the full prompt
-    # (header line, +$ <command>+ echo, +(y/n)?+ cue) and hands it to the
-    # confirmer; the confirmer renders + parses the answer. The command
-    # echo passes through {.visible} which escapes control bytes so the
-    # model can't smuggle a +\r\033[2K rm -rf ~/+ behind the displayed
-    # text. Execution uses the raw command; only the *display* is
-    # sanitized.
+    # Every command is confirmed (unless a +passive_detector+ pre-approves it).
+    # Bash composes a semantic {Pikuri::Workspace::Confirmer::Request} — a
+    # question plus +$ <command>+ detail — and hands it to the confirmer, which
+    # owns ALL presentation and medium-appropriate escaping of the raw bytes
+    # (terminal neutralizes control bytes, web client HTML-escapes). The request
+    # carries the command verbatim so each renderer escapes for its own medium.
+    # The *observation* echo (+$ ...+ in the tool result) passes through
+    # {.visible}, so the model can't smuggle a +\r\033[2K rm -rf ~/+ behind it
+    # either. Execution uses the raw command; only displays are sanitized.
     #
     # == Subprocess wiring
     #
-    # The command runs through {Pikuri::Subprocess.spawn} with argv:
-    #
     #   timeout --signal=TERM --kill-after=5s <timeout>s bash -c <command>
     #
-    # +bash -c+ (no +-l+) — no profile/rc sourcing, no inherited login
-    # environment beyond what pikuri itself runs in. +timeout(1)+ from
-    # GNU coreutils handles the SIGTERM-then-SIGKILL race; we never use
-    # Ruby's +Timeout.timeout+ (can't reliably kill subprocesses). The
-    # +--kill-after=5s+ gives the command 5 seconds to handle SIGTERM
-    # cleanly before SIGKILL is sent.
+    # +bash -c+ (no +-l+) — no profile/rc sourcing. +timeout(1)+ from GNU
+    # coreutils handles the SIGTERM-then-SIGKILL race (Ruby's +Timeout.timeout+
+    # can't reliably kill subprocesses); +--kill-after=5s+ gives 5s to handle
+    # SIGTERM before SIGKILL. The environment is de-bundlerized first, or a
+    # +bundle exec+ against another project would pick up *pikuri's* Gemfile.
+    # See {.subprocess_env} and {Pikuri::BundlerEnv}.
     #
     # == Timeout detection
     #
-    # GNU coreutils' +timeout+ exits +124+ after a successful SIGTERM,
-    # +137+ after escalating to SIGKILL. We treat both as "command timed
-    # out". A third code, +125+, is also accepted: uutils-coreutils 0.2.2
-    # (the Rust reimplementation shipped on some distros) sends the
-    # SIGTERM correctly but then mis-reports +125+ ("timeout itself
-    # failed") instead of +124+ whenever +--kill-after+ is in play. False-
-    # positive risk on real GNU coreutils is low — our argv is fixed and
-    # well-formed, so a +125+ there would indicate a misconfigured PATH
-    # rather than a routine timeout.
-    #
-    # Caveat: +137+ is ambiguous — a command killed by the OOM-killer
-    # also exits +137+. v1 accepts the mis-classification; the
-    # observation tells the user "sent SIGTERM, then SIGKILL" regardless.
+    # GNU +timeout+ exits +124+ after SIGTERM, +137+ after escalating to
+    # SIGKILL; both are treated as "timed out". +125+ is also accepted:
+    # uutils-coreutils 0.2.2 (the Rust reimplementation on some distros)
+    # mis-reports +125+ instead of +124+ when +--kill-after+ is in play.
+    # False-positive risk on real GNU coreutils is low (fixed, well-formed
+    # argv). Caveat: +137+ is ambiguous — the OOM-killer also exits +137+; v1
+    # accepts the mis-classification (the observation says "sent SIGTERM, then
+    # SIGKILL" regardless).
     #
     # == Output handling
     #
-    # Combined stdout+stderr (popen2e). Head+tail truncation at
-    # {OUTPUT_HEAD} + {OUTPUT_TAIL} bytes with a marker reporting both
-    # bytes-omitted and the original total — the model needs the scale
-    # to decide whether to re-run with +head+/+tail+/+grep+.
+    # Combined stdout+stderr (popen2e), head+tail truncated at {OUTPUT_HEAD} +
+    # {OUTPUT_TAIL} bytes with a marker reporting bytes-omitted and total — the
+    # model needs the scale to decide whether to re-run with +head+/+grep+.
     #
     # == Backgrounded subprocesses
     #
-    # Plain +cmd &+ does NOT detach — the backgrounded child inherits our
-    # combined-output pipe by default, so {Pikuri::Subprocess#wait} blocks
-    # on +io.read+ until the backgrounded process exits. The model must
-    # redirect fds away from our pipe to genuinely background:
-    # +cmd >/dev/null 2>&1 &+. Such commands stay in our pgroup and get
-    # SIGTERM on pikuri exit via {Pikuri::Subprocess.cleanup!}; +nohup+ /
-    # +setsid+ plus redirection opt out of cleanup.
+    # Plain +cmd &+ does NOT detach — the child inherits our combined-output
+    # pipe, so {Pikuri::Subprocess#wait} blocks on +io.read+ until it exits. The
+    # model must redirect fds to genuinely background: +cmd >/dev/null 2>&1 &+.
+    # Such commands stay in our pgroup and get SIGTERM on pikuri exit via
+    # {Pikuri::Subprocess.cleanup!}; +nohup+ / +setsid+ plus redirection opt out.
     #
-    # == Refusals
+    # == Sharing
     #
-    # All returned as +"Error: ..."+ observations:
+    # +P_one_agent+, but only because of the {Pikuri::Workspace::Confirmer}: with
+    # a shared {Confirmer::Terminal} two agents fight over one human's
+    # keystrokes. In substance this tool is stateless — every call spawns its
+    # own subprocess, and the {Pikuri::Workspace::Filesystem}, {Bash::Sandbox}
+    # and +passive_detector+ it holds are immutable — so under
+    # {Confirmer::AutoApprove} nothing stops one instance serving every agent.
     #
-    # * Empty / whitespace-only +command+ → fast reject before confirming.
-    # * +timeout+ outside +[1, MAX_TIMEOUT]+ → bounds error.
-    # * User declined the confirmation → +"Error: user declined ..."+.
-    # * +timeout+ exit (+124+ / +137+) → timeout error with partial output.
+    # Concurrency the *commands* create is not pikuri's to serialize: ten agents
+    # running +bundle install+ in one workspace will corrupt each other's work
+    # exactly as ten shells would.
     class Bash < Pikuri::Tool
-      # Pikuri-convention per-module logger; the +Bash+ progname tags the
-      # construction-time warning below so it's clear in the shared
-      # +Pikuri.log_io+ stream which tool issued it.
       # @return [Logger]
       LOGGER = Pikuri.logger_for('Bash')
 
@@ -92,6 +81,29 @@ module Pikuri
       #   passed to +timeout --kill-after=...+.
       KILL_AFTER = '5s'
 
+      # Git config keys forced onto every git invocation, threaded in via
+      # {.git_hardening_delta}. What each key does:
+      #
+      # * +core.fsmonitor=false+ — the headline vector: a repo-local
+      #   +core.fsmonitor = <cmd>+ runs +<cmd>+ on every index refresh (plain
+      #   +git status+/+diff+, no +.gitattributes+ needed). +false+ is git's
+      #   default, so legitimate status/diff are unaffected.
+      # * +core.pager=cat+ — belt-and-suspenders; auto-paging is already inert
+      #   under our non-TTY pipe, but a forced +cat+ makes it a no-op regardless.
+      #
+      # Why this exists — the config-execution vector that makes even a *passive*
+      # git command an unconfirmed RCE without it, the narrow diff-driver
+      # residual it deliberately does NOT close (+diff.external+ /
+      # +.gitattributes+ +.textconv+, uncloseable via environment), and the tie
+      # to {PassiveCommandDetector}'s +allow_git:+ — lives in
+      # +pikuri-code/DESIGN.md+ (*Passive git needs Bash's hardening*).
+      #
+      # @return [Array<Array(String, String)>] +[key, value]+ pairs.
+      GIT_HARDENING = [
+        ['core.fsmonitor', 'false'],
+        ['core.pager', 'cat']
+      ].freeze
+
       # @return [Integer] bytes preserved from the start of the output
       #   when the combined-output stream exceeds {OUTPUT_HEAD} + {OUTPUT_TAIL}.
       OUTPUT_HEAD = 15 * 1024
@@ -103,52 +115,53 @@ module Pikuri
       # bullets. Per-parameter constraints (default, max) live in the
       # parameter descriptions.
       #
+      # The +Avoid ... cat / rg / find+ bullet is load-bearing, not etiquette —
+      # a shell read skips the +cat -n+ numbering {Pikuri::Workspace::Edit}
+      # anchors on, the byte caps, the read-before-edit ledger and the path
+      # gate. (An outside-model review — Grok 4.6, 2026-08 — called the split
+      # the right bet; nothing tests that the model obeys the bullet.)
+      #
       # @return [String]
       DESCRIPTION = <<~DESC
         Run a bash command in the workspace.
 
         Usage:
         - Use for tasks the dedicated tools can't do: git, tests, package managers, multi-step shell pipelines.
-        - Prefer `read` / `write` / `edit` / `grep` / `glob` over `cat` / `sed` / `rg` / `find` — they're workspace-resolved.
+        - IMPORTANT: Avoid using this tool to run `cat`, plain `head` or `tail`, `sed`, `awk`, `rg`, `find` or `echo` commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user, respect the workspace and produce cleaner output.
         - Working directory is ALWAYS the project root: `pwd` returns it, and relative paths in commands resolve from there. To operate in a subfolder, chain `cd` in the same command (`cd src/foo && make test`) — `cd` does NOT persist across calls; each call starts fresh at the project root.
         - stdin is closed; interactive commands hang until timeout. Use non-interactive flags (`apt -y`, `git commit -m`).
         - Plain `cmd &` does NOT detach — the backgrounded process inherits our output pipe and blocks. To genuinely background, redirect fds: `cmd >/dev/null 2>&1 &`. Add `nohup` or `setsid` to survive pikuri exit.
         - Combined stdout+stderr is returned. Suppress either via `2>/dev/null` etc.
         - Large outputs are head+tail-truncated. Pipe through `head`/`tail`/`grep`/`wc` to control volume.
-        - Non-zero exit status is a normal observation, not an error.
-        - The user must confirm every command before it runs; on rejection an Error is returned.
+        # Git
+        - Interactive flags (`-i`, e.g. `git rebase -i`, `git add -i`) are not supported in this environment.
+        - Use the `gh` CLI (if available) for GitHub operations (PRs, issues, API).
+        - Commit or push only when the user asks.
       DESC
 
-      # @param workspace [Pikuri::Workspace::Filesystem] captured for
-      #   +chdir+; commands run in +workspace.project_root+, always.
-      #   Even when the surrounding Ruby process has already chdir'd
-      #   to the project root (e.g. +bin/pikuri-code+ does this at
-      #   startup), Bash still passes the explicit +chdir:+ — so a
-      #   sub-agent, future host, or anyone embedding Bash directly
-      #   gets the same predictable cwd. Bash does NOT path-resolve
-      #   individual arguments — the +command+ string is opaque shell
-      #   syntax.
-      # @param confirmer [Pikuri::Workspace::Confirmer] consulted before
-      #   every command.
-      # @param sandbox [Code::Bash::Sandbox] filesystem-sandbox seam
-      #   (default {Sandbox::NONE} — identity passthrough). Pass
-      #   {Sandbox::Bubblewrap.new(workspace: workspace)+} for an
-      #   isolated subprocess whose filesystem view is the workspace's
-      #   readable/writable roots plus the OS-runtime baseline. See
-      #   {Sandbox} for the rationale.
-      # @raise [RuntimeError] if +bash+ or +timeout+ aren't on +PATH+;
-      #   fail-loud at construction rather than the first tool call.
+      # @param filesystem [Pikuri::Workspace::Filesystem] captured for +chdir+;
+      #   commands always run in +filesystem.project_root+ (explicit +chdir:+
+      #   even when the process already chdir'd there, so a sub-agent or
+      #   embedding host gets the same cwd). Bash does NOT path-resolve
+      #   arguments — the +command+ is opaque shell syntax.
+      # @param confirmer [Pikuri::Workspace::Confirmer] consulted before every
+      #   command that +passive_detector+ does not pre-approve.
+      # @param passive_detector [#passive?, nil] optional predicate over the
+      #   raw command string ({PassiveCommandDetector}); +true+ runs with no
+      #   prompt, +false+/+nil+ falls through to +confirmer+. The
+      #   passive-auto-gate seam, kept separate so "how to ask" ({Confirmer})
+      #   and "what may skip asking" (this) stay composable axes.
+      # @param sandbox [Code::Bash::Sandbox] filesystem-sandbox seam (default
+      #   {Sandbox::NONE}). Pass {Sandbox::Bubblewrap.new(filesystem:)} for an
+      #   isolated subprocess; see {Sandbox}.
+      # @raise [RuntimeError] if +bash+ or +timeout+ aren't on +PATH+.
       # @return [Bash]
-      def initialize(workspace:, confirmer:, sandbox: Sandbox::NONE)
+      def initialize(filesystem:, confirmer:, sandbox: Sandbox::NONE, passive_detector: nil)
         Bash.send(:check_binaries!)
-        # Capability advisory when no sandbox is in play. Without a
-        # sandbox, +bash+ runs with pikuri's own UID + filesystem view —
-        # anything readable to the user is readable to the LLM via +cat
-        # ~/.ssh/id_*+ / +aws configure list+ / etc. The per-command
-        # +Confirmer+ is the only line of defense in that mode. The
-        # bundled {Sandbox::Bubblewrap} addresses this concern with a
-        # filesystem-restricted subprocess; warn only when the host has
-        # opted out (or never opted in).
+        # Without a sandbox, bash runs with pikuri's UID + filesystem view —
+        # anything the user can read the LLM can read (+cat ~/.ssh/id_*+, +aws
+        # configure list+), with the per-command Confirmer the only defense. Warn
+        # only when the host opted out (or never opted in); Bubblewrap fixes it.
         if sandbox.equal?(Sandbox::NONE)
           LOGGER.warn(
             'Code::Bash is unsandboxed: commands run under your UID and can read ' \
@@ -171,9 +184,31 @@ module Pikuri
                                "max #{MAX_TIMEOUT}, e.g. 300."
           },
           execute: ->(command:, description: nil, timeout: DEFAULT_TIMEOUT) {
-            Bash.run(workspace: workspace, confirmer: confirmer, sandbox: sandbox,
+            Bash.run(filesystem: filesystem, confirmer: confirmer, sandbox: sandbox,
+                     passive_detector: passive_detector,
                      command: command, description: description, timeout: timeout)
-          }
+          },
+          # Both inbound axes come from the *sandbox*, not the workspace: the
+          # workspace governs what the LLM observes through the file tools, the
+          # sandbox governs what bash sees. Scope the workspace to a vouched-for
+          # repo and +cat ~/Downloads/*+ still works under a full-root bind.
+          #
+          # Note what this does *not* claim: +:human_reviewed+, though a
+          # +Confirmer+ is right there. The human approves a *command* — a
+          # program, not a payload. Behind a pipe, a heredoc, +$(…)+ or a script
+          # file, the bytes that egress are computed at runtime and were never on
+          # screen, so approving +curl+ approves an intent. That failure of the
+          # payload-visibility clause is what keeps a coding agent over a private
+          # repo loud, and it is deliberately a literal here rather than
+          # something a rule engine could talk itself out of.
+          #
+          # The destination axis is left to derive: a shell picks its own host,
+          # so a live leg here is always +:attacker_reachable+.
+          trifecta_legs: Pikuri::Tool::TrifectaLegs.new(
+            private: filesystem.private?,
+            untrusted: sandbox.confined_to_workspace? && filesystem.trusted? ? :none : :hard,
+            egress_payload_review: sandbox.egress? ? :unreviewed : :no_egress
+          )
         )
       end
 
@@ -181,28 +216,42 @@ module Pikuri
       # either +"$ ...\n<out>\n\nexit status: N"+ on a normal exit, or
       # +"Error: ..."+ on rejection / timeout / bad inputs.
       #
-      # @param workspace [Pikuri::Workspace::Filesystem]
+      # @param filesystem [Pikuri::Workspace::Filesystem]
       # @param confirmer [Pikuri::Workspace::Confirmer]
-      # @param sandbox [Code::Bash::Sandbox] wraps the spawned argv;
-      #   {Sandbox::NONE} for identity passthrough,
-      #   {Sandbox::Bubblewrap} for filesystem isolation.
+      # @param sandbox [Code::Bash::Sandbox] wraps the spawned argv.
+      # @param passive_detector [#passive?, nil] passive-command pre-approval
+      #   predicate; a +true+ verdict skips the prompt. See {#initialize}.
       # @param command [String] raw command as supplied by the LLM
       # @param description [String, nil] optional short label for the user
       # @param timeout [Integer] seconds before SIGTERM is sent
       # @return [String]
-      def self.run(workspace:, confirmer:, command:, description:, timeout:, sandbox: Sandbox::NONE)
+      def self.run(filesystem:, confirmer:, command:, description:, timeout:,
+                   sandbox: Sandbox::NONE, passive_detector: nil)
         return 'Error: empty bash command.' if command.strip.empty?
         return "Error: timeout must be >= 1, got #{timeout}" if timeout < 1
         return "Error: timeout must be <= #{MAX_TIMEOUT}, got #{timeout}" if timeout > MAX_TIMEOUT
 
-        prompt = compose_prompt(command: command, description: description, timeout: timeout)
-        return 'Error: user declined the bash command.' unless confirmer.confirm?(prompt: prompt)
+        # A command the detector deems passive (provably observe-only) runs
+        # without a prompt; everything else is confirmed by the human.
+        unless passive_detector&.passive?(command)
+          request = compose_request(command: command, description: description, timeout: timeout)
+          case confirmer.ask(request: request)
+          in Pikuri::Workspace::Confirmer::Rejected(reason:)
+            msg = +'Error: user declined the bash command.'
+            msg << " Reason: #{reason}" if reason && !reason.empty?
+            return msg
+          in Pikuri::Workspace::Confirmer::Approved
+            # fall through to execution (the command is non-editable, so the
+            # approved detail is the same command we already hold)
+          end
+        end
 
         argv = sandbox.wrap([
           'timeout', '--signal=TERM', "--kill-after=#{KILL_AFTER}", "#{timeout}s",
           'bash', '-c', command
         ])
-        result = Pikuri::Subprocess.spawn(*argv, chdir: workspace.project_root.to_s, env: workspace.env).wait
+        result = Pikuri::Subprocess.spawn(*argv, chdir: filesystem.project_root.to_s,
+                                                 env: subprocess_env(filesystem)).wait
 
         output = truncate(result.output)
         exit_code = result.status.exitstatus
@@ -217,41 +266,81 @@ module Pikuri
         end
       end
 
-      # Compose the multi-line confirmation prompt. Three lines:
+      # Compose the semantic confirmation request:
       #
-      # 1. +OK to run bash[: <desc>][ \[Timeout: Ns\]]+ (bold)
-      # 2. +$ <visible(command)>+ (dim)
-      # 3. +(y/n)?+
+      # * question — +OK to run bash[: <desc>][ \[Timeout: Ns\]]+
+      # * detail — +$ <command>+, the command VERBATIM (the confirmer
+      #   escapes for its medium; see the class header's Confirmation
+      #   section)
       #
       # Colon after +bash+ is dropped when there's no description, since a
       # trailing colon with nothing after it reads as broken. Timeout
       # suffix appears only when non-default.
       #
-      # @return [String]
-      def self.compose_prompt(command:, description:, timeout:)
-        header = +'OK to run bash'
+      # @return [Pikuri::Workspace::Confirmer::Request]
+      def self.compose_request(command:, description:, timeout:)
+        question = +'OK to run bash'
         desc_clean = description&.strip
-        header << ": #{desc_clean}" if desc_clean && !desc_clean.empty?
-        header << " [Timeout: #{timeout}s]" if timeout != DEFAULT_TIMEOUT
+        question << ": #{desc_clean}" if desc_clean && !desc_clean.empty?
+        question << " [Timeout: #{timeout}s]" if timeout != DEFAULT_TIMEOUT
+
+        Pikuri::Workspace::Confirmer::Request.new(question: question, detail: "$ #{command}")
+      end
+      private_class_method :compose_request
+
+      # Environment for the bash subprocess: the de-bundlerized base
+      # ({Pikuri::BundlerEnv.clean_delta}), then git hardening
+      # ({.git_hardening_delta}), then the filesystem's git identity
+      # ({Pikuri::Workspace::Filesystem#env}). The three deltas touch disjoint
+      # keys (bundler vars / +GIT_CONFIG_*+ / +GIT_AUTHOR_*+ +
+      # +GIT_COMMITTER_*+), so merge order is immaterial.
+      #
+      # @param filesystem [Pikuri::Workspace::Filesystem]
+      # @return [Hash{String=>(String,nil)}] +env:+ delta for
+      #   {Pikuri::Subprocess.spawn} (a +nil+ value unsets the key).
+      def self.subprocess_env(filesystem)
+        Pikuri::BundlerEnv.clean_delta.merge(git_hardening_delta).merge(filesystem.env)
+      end
+      private_class_method :subprocess_env
 
-        [
-          Rainbow(header).bold,
-          Rainbow("$ #{visible(command)}").dimgray,
-          '(y/n)?'
-        ].join("\n")
+      # Emit {GIT_HARDENING} as a +GIT_CONFIG_COUNT+ / +GIT_CONFIG_KEY_<n>+ /
+      # +GIT_CONFIG_VALUE_<n>+ env delta. This protocol has the same top
+      # precedence as command-line +-c+, so it overrides a hostile repo-local
+      # +core.fsmonitor+ regardless of what the repo says.
+      #
+      # Via *environment*, not by rewriting the model's command, because the
+      # command is opaque shell syntax we refuse to parse, and env applies
+      # uniformly to *every* git in the command — each link of a +&&+/+|+ chain,
+      # and any git a script underneath forks — with no parsing.
+      #
+      # Indices are offset past any +GIT_CONFIG_COUNT+ already inherited, so our
+      # keys append rather than clobber a host's; the higher index also wins
+      # under git's last-wins rule on a duplicate key.
+      #
+      # @return [Hash{String=>String}]
+      def self.git_hardening_delta
+        base = ENV['GIT_CONFIG_COUNT'].to_i
+        delta = {}
+        GIT_HARDENING.each_with_index do |(key, value), i|
+          delta["GIT_CONFIG_KEY_#{base + i}"] = key
+          delta["GIT_CONFIG_VALUE_#{base + i}"] = value
+        end
+        delta['GIT_CONFIG_COUNT'] = (base + GIT_HARDENING.size).to_s
+        delta
       end
-      private_class_method :compose_prompt
+      private_class_method :git_hardening_delta
 
-      # Escape control bytes for safe display while preserving +\n+
-      # (multi-line shell commands are normal). Catches +\r+, +\x1b+
-      # (ESC, the ANSI introducer), +\b+, NUL, DEL, etc. — without this,
-      # a model could craft +command: "\rrm -rf ~/"+ that visually
-      # overwrites the echo line after the user has already read it.
+      # Neutralize control bytes for the *observation* echo (+"$ ..."+ in the
+      # tool result) — without this a model could craft +command: "\rrm -rf
+      # ~/"+ that visually overwrites the echo line after the user read it.
+      # Delegates to {Pikuri::Sanitizer} (preserves +\n+, visualizes the rest).
+      # The echo is passive, so {Pikuri::Sanitizer::Warning}s are dropped here —
+      # they surface at the confirmation prompt, before the user approves.
       #
       # @param command [String]
       # @return [String]
       def self.visible(command)
-        command.gsub(/[\x00-\x09\x0b-\x1f\x7f]/) { |c| format('\\x%02x', c.ord) }
+        Pikuri::Sanitizer.sanitize(command).text
       end
       private_class_method :visible
 

data/lib/pikuri/code/enter_plan_mode.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Code
+    # The +enter_plan_mode+ tool: turns on the shared
+    # {Pikuri::Workspace::ReadOnly} flag. Once active, Write/Edit refuse and the
+    # {Extension}'s per-turn reminder steers the model to research and propose;
+    # the model exits via {ExitPlanMode}, or the host flips the same flag from a
+    # key binding / slash command. Entry is just as often host-initiated as
+    # model-driven — either way the flag is the single source of truth. (It
+    # gates Write/Edit, not Bash — see {Pikuri::Workspace::ReadOnly}.)
+    #
+    # Sharing: +P_shared_locked+ — the flag it flips is thread-safe, so nothing
+    # breaks. Decide the *semantics* on purpose, though: agents sharing one flag
+    # share one plan mode, so this agent entering it disables writes for all of
+    # them. Per-agent plan mode means a {Pikuri::Workspace::ReadOnly} each.
+    class EnterPlanMode < Pikuri::Tool
+      # @return [String]
+      DESCRIPTION = <<~DESC
+        Enter plan mode: a read-only posture for researching and designing a change before writing any of it.
+
+        Usage:
+        - Reach for this before a non-trivial change — new features, multi-file edits, refactors, or anything with several valid approaches — so the user can sign off on the approach before code is written.
+        - Skip it for small, unambiguous edits (a typo, an obvious one-line fix) and for pure research questions.
+        - While in plan mode the file-editing tools are disabled; explore and reason freely, then present a plan with exit_plan_mode for approval.
+        - When unsure, prefer entering: alignment up front is cheaper than redone work.
+      DESC
+
+      # @param read_only [Pikuri::Workspace::ReadOnly] the shared
+      #   read-only flag to activate.
+      # @return [EnterPlanMode]
+      def initialize(read_only:)
+        super(
+          name: 'enter_plan_mode',
+          description: DESCRIPTION,
+          parameters: Parameters::EMPTY,
+          execute: -> { EnterPlanMode.run(read_only: read_only) },
+          # No legs: flips a local mode flag.
+          trifecta_legs: Pikuri::Tool::TrifectaLegs::NONE
+        )
+      end
+
+      # Activate plan mode (idempotent) and return the observation that
+      # confirms the posture to the model.
+      #
+      # @param read_only [Pikuri::Workspace::ReadOnly]
+      # @return [String] tool observation
+      def self.run(read_only:)
+        read_only.activate!
+        'You are now in plan mode (read-only): research and design only, do not edit ' \
+          'files. When the plan is ready, call exit_plan_mode to present it for approval.'
+      end
+    end
+  end
+end

data/lib/pikuri/code/exit_plan_mode.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Code
+    # The +exit_plan_mode+ tool: presents the finished plan for approval and, on
+    # a yes, turns the shared {Pikuri::Workspace::ReadOnly} flag back off. The
+    # plan is shown and the yes/no collected through the same
+    # {Pikuri::Workspace::Confirmer} the +write+/+bash+ tools use, so
+    # presentation + attacker-text sanitization live in one place. On approval
+    # the flag flips off and the model is told to proceed; on a decline it stays
+    # on and the observation steers a refine-and-re-present, never an edit. The
+    # LLM-authored plan is passed as the request +detail+, so the Confirmer
+    # neutralizes it before display.
+    #
+    # Sharing: as {EnterPlanMode} — +P_shared_locked+ on the flag, and sharing
+    # it makes plan mode VM-wide. The {Pikuri::Workspace::Confirmer} pulls the
+    # other way ({Confirmer::Terminal} is +P_one_agent+), so a shared instance
+    # is only as shareable as the confirmer behind it.
+    class ExitPlanMode < Pikuri::Tool
+      # @return [String]
+      DESCRIPTION = <<~DESC
+        Exit plan mode by presenting your finished implementation plan for the user's approval.
+
+        Usage:
+        - Call this only once your plan is complete and unambiguous; pass the full plan as the `plan` argument.
+        - The user is shown the plan and asked to approve. On approval you leave plan mode and may implement it; on a decline you stay in plan mode — refine the plan and call this again.
+        - If a requirement is still unclear, ask the user directly first (without leaving plan mode) rather than presenting a half-formed plan.
+        - Do not use this for pure research tasks — those never enter plan mode in the first place.
+      DESC
+
+      # @param read_only [Pikuri::Workspace::ReadOnly] the shared
+      #   read-only flag to deactivate on approval.
+      # @param confirmer [Pikuri::Workspace::Confirmer] consulted to
+      #   present the plan and collect the approval.
+      # @return [ExitPlanMode]
+      def initialize(read_only:, confirmer:)
+        super(
+          name: 'exit_plan_mode',
+          description: DESCRIPTION,
+          parameters: Parameters.build { |p|
+            p.required_string :plan,
+                              'Your complete implementation plan, in Markdown, ' \
+                              'shown to the user for approval. Cover the files ' \
+                              'to change and the changes to each, e.g. ' \
+                              '"## Plan\n1. Add X to foo.rb\n2. ...".'
+          },
+          execute: ->(plan:) {
+            ExitPlanMode.run(read_only: read_only, confirmer: confirmer, plan: plan)
+          },
+          # No legs: flips a local mode flag (behind a confirmer, which grades
+          # nothing here — there is no leg to gate).
+          trifecta_legs: Pikuri::Tool::TrifectaLegs::NONE
+        )
+      end
+
+      # Present +plan+ for approval; on yes deactivate plan mode, on no
+      # keep it active. Returns the observation the model reacts to.
+      #
+      # @param read_only [Pikuri::Workspace::ReadOnly]
+      # @param confirmer [Pikuri::Workspace::Confirmer]
+      # @param plan [String] the LLM-authored plan to show the user
+      # @return [String] tool observation
+      def self.run(read_only:, confirmer:, plan:)
+        unless read_only.active?
+          return 'Error: not in plan mode, so there is nothing to exit. ' \
+                 'Proceed with the work directly.'
+        end
+
+        request = Pikuri::Workspace::Confirmer::Request.new(
+          question: 'Approve this plan? (approving exits plan mode and lets the agent edit files)',
+          detail: plan
+        )
+
+        if confirmer.confirm?(request: request)
+          read_only.deactivate!
+          'Plan approved — you are no longer in plan mode. Implement the plan now.'
+        else
+          'The user did not approve the plan; you are still in plan mode (read-only). ' \
+            'Ask what they would like changed, revise the plan, and call exit_plan_mode ' \
+            'again when ready. Do not edit any files.'
+        end
+      end
+    end
+  end
+end