pikuri 0.0.1

data/lib/pikuri/tool/bash.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+require 'rainbow'
+
+module Pikuri
+  class Tool
+    # The +bash+ tool — run an arbitrary shell command in the workspace.
+    # Instantiating +Tool::Bash.new(workspace: ws, confirmer: c)+ produces
+    # a tool whose {Tool#to_ruby_llm_tool} wiring is identical to any
+    # bundled tool's. Same shape as {Tool::Write} (workspace + confirmer
+    # captured by the +execute+ closure at construction).
+    #
+    # == 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.
+    #
+    # == 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.
+    #
+    # == 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.
+    #
+    # == 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+.
+    #
+    # == 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.
+    #
+    # == Refusals
+    #
+    # All returned as +"Error: ..."+ observations:
+    #
+    # * 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.
+    class Bash < 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')
+
+      # @return [Integer] default value of the +timeout+ parameter (seconds).
+      DEFAULT_TIMEOUT = 120
+
+      # @return [Integer] hard upper bound on the +timeout+ parameter.
+      MAX_TIMEOUT = 600
+
+      # @return [String] grace period between SIGTERM and SIGKILL,
+      #   passed to +timeout --kill-after=...+.
+      KILL_AFTER = '5s'
+
+      # @return [Integer] bytes preserved from the start of the output
+      #   when the combined-output stream exceeds {OUTPUT_HEAD} + {OUTPUT_TAIL}.
+      OUTPUT_HEAD = 15 * 1024
+
+      # @return [Integer] bytes preserved from the end of the output.
+      OUTPUT_TAIL = 15 * 1024
+
+      # Description shown to the LLM. opencode-shape: summary + +Usage:+
+      # bullets. Per-parameter constraints (default, max) live in the
+      # parameter descriptions.
+      #
+      # @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.
+        - Each call starts in the workspace root; there is no pwd persistence between calls. Use `cd /path && cmd` in one command.
+        - 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.
+      DESC
+
+      # @param workspace [Tool::Workspace] captured for +chdir+; commands
+      #   run in +workspace.cwd+. Bash does NOT path-resolve individual
+      #   arguments — the +command+ string is opaque shell syntax.
+      # @param confirmer [Tool::Confirmer] consulted before every command.
+      # @raise [RuntimeError] if +bash+ or +timeout+ aren't on +PATH+;
+      #   fail-loud at construction rather than the first tool call.
+      # @return [Bash]
+      def initialize(workspace:, confirmer:)
+        Bash.send(:check_binaries!)
+        # Prototype-stage capability advisory. The Bash tool runs commands
+        # with pikuri's own UID and inherits its filesystem view — there is
+        # no chroot, container, seccomp, or syscall filter today. 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; logged loud so anyone wiring this tool up
+        # sees the warning at startup, not on the day of an incident.
+        LOGGER.warn(
+          'Tool::Bash is a prototype: commands run unsandboxed under your UID and can read ' \
+          'sensitive files (~/.ssh, AWS credentials, browser sessions, ...). Use with care; ' \
+          'a future release will gate this behind a sandbox.'
+        )
+        super(
+          name: 'bash',
+          description: DESCRIPTION,
+          parameters: Parameters.build { |p|
+            p.required_string :command,
+                              'Bash command to execute. Multi-line is fine. ' \
+                              'Example: "ls -la lib/".'
+            p.optional_string :description,
+                              'Short 3-7 word label shown to the user alongside ' \
+                              'the command, e.g. "Run unit tests".'
+            p.optional_integer :timeout,
+                               "Timeout in seconds. Defaults to #{DEFAULT_TIMEOUT}, " \
+                               "max #{MAX_TIMEOUT}, e.g. 300."
+          },
+          execute: ->(command:, description: nil, timeout: DEFAULT_TIMEOUT) {
+            Bash.run(workspace: workspace, confirmer: confirmer,
+                     command: command, description: description, timeout: timeout)
+          }
+        )
+      end
+
+      # Bounds-check, confirm, spawn, and render the observation. Returns
+      # either +"$ ...\n<out>\n\nexit status: N"+ on a normal exit, or
+      # +"Error: ..."+ on rejection / timeout / bad inputs.
+      #
+      # @param workspace [Tool::Workspace]
+      # @param confirmer [Tool::Confirmer]
+      # @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:)
+        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)
+
+        result = Pikuri::Subprocess.spawn(
+          'timeout', '--signal=TERM', "--kill-after=#{KILL_AFTER}", "#{timeout}s",
+          'bash', '-c', command,
+          chdir: workspace.cwd.to_s
+        ).wait
+
+        output = truncate(result.output)
+        exit_code = result.status.exitstatus
+
+        # 124 (GNU SIGTERM), 137 (GNU SIGKILL), 125 (uutils-coreutils
+        # 0.2.2 bug when --kill-after is set). See class header.
+        if exit_code == 124 || exit_code == 137 || exit_code == 125
+          "Error: command timed out after #{timeout}s (sent SIGTERM, then SIGKILL).\n\n" \
+            "$ #{visible(command)}\n#{output}"
+        else
+          "$ #{visible(command)}\n#{output}\n\nexit status: #{exit_code}"
+        end
+      end
+
+      # Compose the multi-line confirmation prompt. Three lines:
+      #
+      # 1. +OK to run bash[: <desc>][ \[Timeout: Ns\]]+ (bold)
+      # 2. +$ <visible(command)>+ (dim)
+      # 3. +(y/n)?+
+      #
+      # 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'
+        desc_clean = description&.strip
+        header << ": #{desc_clean}" if desc_clean && !desc_clean.empty?
+        header << " [Timeout: #{timeout}s]" if timeout != DEFAULT_TIMEOUT
+
+        [
+          Rainbow(header).bold,
+          Rainbow("$ #{visible(command)}").dimgray,
+          '(y/n)?'
+        ].join("\n")
+      end
+      private_class_method :compose_prompt
+
+      # 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.
+      #
+      # @param command [String]
+      # @return [String]
+      def self.visible(command)
+        command.gsub(/[\x00-\x09\x0b-\x1f\x7f]/) { |c| format('\\x%02x', c.ord) }
+      end
+      private_class_method :visible
+
+      # Head+tail-truncate +output+ to {OUTPUT_HEAD} + {OUTPUT_TAIL}
+      # bytes with a marker reporting both bytes-omitted and total.
+      # No-op when the output already fits.
+      #
+      # @param output [String]
+      # @return [String]
+      def self.truncate(output)
+        total = output.bytesize
+        return output if total <= OUTPUT_HEAD + OUTPUT_TAIL
+
+        omitted = total - (OUTPUT_HEAD + OUTPUT_TAIL)
+        head = output.byteslice(0, OUTPUT_HEAD)
+        tail = output.byteslice(total - OUTPUT_TAIL, OUTPUT_TAIL)
+        "#{head}\n... [#{omitted} bytes omitted; total was #{total} bytes] ...\n#{tail}"
+      end
+      private_class_method :truncate
+
+      # Verify +bash+ and GNU +timeout+ are reachable on +PATH+. Routed
+      # through {Pikuri::Subprocess.spawn} to honor the subprocess seam
+      # (no direct +system+ / +backtick+ in +lib/+). +bash+ missing
+      # surfaces as +Errno::ENOENT+ from +popen2e+; +timeout+ missing
+      # surfaces as a non-zero exit from +command -v+.
+      #
+      # @return [void]
+      # @raise [RuntimeError] if either binary is missing
+      def self.check_binaries!
+        result = Pikuri::Subprocess.spawn('bash', '-c', 'command -v timeout >/dev/null', chdir: '/').wait
+        raise "Tool::Bash requires GNU coreutils 'timeout' on PATH" unless result.status.success?
+      rescue Errno::ENOENT
+        raise "Tool::Bash requires 'bash' on PATH"
+      end
+      private_class_method :check_binaries!
+    end
+  end
+end

data/lib/pikuri/tool/calculator.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'dentaku'
+
+module Pikuri
+  class Tool
+    # Evaluates a basic arithmetic expression using Dentaku, with light
+    # preprocessing so the LLM can emit Python-flavored syntax (notably
+    # +**+ for exponentiation) instead of learning Dentaku's dialect.
+    #
+    # Scope is intentionally narrow: operators (+, -, *, /, **, %),
+    # parentheses, and decimal numbers. No variables, functions, or
+    # booleans — those would mean teaching the model a dialect, which we
+    # specifically want to avoid for this tool.
+    module Calculator
+      # Translate the operator differences between Python and Dentaku. In
+      # practice that is only +**+ → +^+; everything else in the supported
+      # subset is byte-identical.
+      #
+      # @param expression [String] raw expression as the model wrote it
+      # @return [String] expression with Python-style operators rewritten
+      def self.normalize(expression)
+        expression.gsub('**', '^')
+      end
+
+      # Evaluate +expression+ and return the result formatted as a String.
+      # Parse, unbound-variable, and division-by-zero failures are caught
+      # and returned as +"Error: ..."+ strings so the model can read the
+      # failure as the next observation and self-correct rather than
+      # crashing the agent loop.
+      #
+      # @param expression [String]
+      # @return [String] numeric result, or +"Error: ..."+ on failure
+      def self.calculate(expression)
+        result = Dentaku::Calculator.new.evaluate!(normalize(expression))
+        format_result(result)
+      rescue Dentaku::ZeroDivisionError, ZeroDivisionError
+        'Error: division by zero'
+      rescue Dentaku::Error => e
+        "Error: #{e.message}"
+      end
+
+      # Dentaku returns BigDecimal for any expression that touches division
+      # or a decimal literal, with full BigDecimal precision (47-digit tails
+      # for the leopard expression). Round to 3 places and strip the
+      # default scientific-notation formatting so the model sees a short
+      # readable number; integer/other results pass through unchanged.
+      def self.format_result(result)
+        case result
+        when BigDecimal then result.round(3).to_s('F')
+        else result.to_s
+        end
+      end
+      private_class_method :format_result
+    end
+
+    # Arithmetic-evaluation tool backed by {Tool::Calculator.calculate}.
+    # Accepts Python-flavored operator syntax (+, -, *, /, ** for
+    # exponentiation, %, parentheses, decimals) so the model can emit the
+    # syntax it already knows.
+    #
+    # @return [Tool]
+    CALCULATOR = new(
+      name: 'calculator',
+      description: <<~DESC,
+        Evaluates a basic arithmetic expression and returns the numeric result.
+
+        Usage:
+        - Use this for any arithmetic beyond simple mental math — do not eyeball multi-digit work.
+        - Operators supported: +, -, *, /, ** (exponentiation), %, parentheses, decimal numbers.
+        - Decimal results are rounded to 3 places; integer results are exact.
+        - Failures (parse error, division by zero) come back as "Error: ..." — read the message and re-call with a corrected expression.
+      DESC
+      parameters: Parameters.build { |p|
+        p.required_string :expression,
+                          'Arithmetic expression to evaluate, e.g. ' \
+                          '"155 / (58 * 1000.0 / 3600)" or "2**10".'
+      },
+      execute: ->(expression:) { Calculator.calculate(expression) }
+    )
+  end
+end

data/lib/pikuri/tool/confirmer.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Tool
+    # Port for asking the user to confirm a potentially destructive tool
+    # operation — currently {Tool::Bash} (every command) and
+    # {Tool::Write} (overwrite of an existing file with non-identical
+    # content). Subclass and implement {#confirm?}.
+    #
+    # == Why a Boolean return
+    #
+    # v1 returns +true+ or +false+. Two paths-not-taken worth recording
+    # so a future reader knows the design space was considered:
+    #
+    # 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.
+    #
+    # 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}).
+    #
+    # == 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.
+    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:
+      #
+      # * +"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
+      #
+      # 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?
+
+            answer = line.strip.downcase
+            return true  if answer == 'y' || answer == 'yes'
+            return false if answer == 'n' || answer == 'no'
+
+            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}.
+      class AutoApprove < Confirmer
+        # @param prompt [String] ignored
+        # @return [true]
+        def confirm?(prompt:)
+          true
+        end
+      end
+
+      # Shared singleton instance of {Terminal}. Stateless; reusable
+      # across tools and sub-agents.
+      TERMINAL = Terminal.new
+
+      # Shared singleton instance of {AutoApprove}.
+      AUTO_APPROVE = AutoApprove.new
+    end
+  end
+end

data/lib/pikuri/tool/edit.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Tool
+    # The +edit+ tool — exact-string replacement on an existing file.
+    # Instantiating +Tool::Edit.new(workspace: ws)+ produces a tool whose
+    # {Tool#to_ruby_llm_tool} wiring is identical to any bundled tool's.
+    # Same shape as {Tool::Read} (workspace captured by +execute+; no
+    # confirmer needed).
+    #
+    # == Why no confirmer
+    #
+    # The +old_string+ argument is itself an implicit read-check: the
+    # model can't write a correct +old_string+ without having seen the
+    # file (via {Tool::Read} or out-of-band), so the blast radius of any
+    # Edit is bounded by the model's actual knowledge of file state.
+    # That makes Edit safe to execute without prompting — by contrast,
+    # {Tool::Write} requires a confirmer because a hallucinated 500-line
+    # +content+ could clobber unread bytes.
+    #
+    # == Matching is strict (no fuzz cascade)
+    #
+    # +old_string+ must match the file byte-for-byte. v1 ships *no*
+    # fallback replacer (no whitespace-normalized, line-trimmed, block-
+    # anchor, etc.). Predictability beats fuzz: when an Edit fails, the
+    # model re-reads with {Tool::Read} and retries — clear failure mode,
+    # no compounding-heuristic risk. opencode runs a 9-replacer cascade
+    # under the hood despite its own description saying "must match
+    # exactly"; pi stays strict. We match pi.
+    #
+    # == Line endings get normalized
+    #
+    # The one structural exception to "strict bytes": files with CRLF
+    # line endings get matched in LF space, and the original line ending
+    # is restored on write. Reason: {Tool::Read} renders content via
+    # +each_line+ + +chomp+, which strips +\r\n+ to +\n+ in what the
+    # model sees. A pure strict byte-match would then never succeed on
+    # CRLF files because the model can only ever supply LF. opencode and
+    # pi both do this normalization for the same reason.
+    #
+    # Algorithm:
+    #
+    # 1. Detect whether the file contains +\r\n+ anywhere (treat as CRLF).
+    # 2. Normalize content, +old_string+, and +new_string+ to LF.
+    # 3. Match + replace in LF space.
+    # 4. If the file was CRLF, convert +\n+ → +\r\n+ on the way back out.
+    #
+    # Caveat: a mixed-line-ending file is treated as CRLF, which means
+    # any pre-existing bare-LF lines get converted on write. Rare in
+    # practice; acceptable for v1.
+    #
+    # == Refusals
+    #
+    # All returned as +"Error: ..."+ observations the LLM can react to:
+    #
+    # * Empty +old_string+ → "use the write tool" (keeps Edit/Write roles
+    #   non-overlapping).
+    # * +old_string+ == +new_string+ → no-op error.
+    # * +old_string+ not found in file → "must match exactly" error
+    #   pointing at the read tool.
+    # * +old_string+ found multiple times without +replace_all+ →
+    #   multi-match error suggesting more context or +replace_all+.
+    # * File missing / is a directory / is binary → respective error.
+    # * Workspace boundary violation / EACCES → standard rescue path.
+    class Edit < Tool
+      # Description shown to the LLM. Follows the opencode-shape (summary
+      # + +Usage:+ bullets) prescribed by the project's tool-description
+      # convention. Per-parameter constraints live in the parameter
+      # descriptions.
+      #
+      # @return [String]
+      DESCRIPTION = <<~DESC
+        Edit a file by exact-string replacement.
+
+        Usage:
+        - Use for partial changes to an existing file; for full rewrites or new files use `write` instead.
+        - `old_string` must match the file byte-for-byte (whitespace and indentation count); re-read the file with `read` if uncertain.
+        - `old_string` and `new_string` must differ.
+        - If `old_string` matches multiple times the call fails — add surrounding context to make the match unique, or set `replace_all: true`.
+        - Cannot create files (rejects empty `old_string` and missing files).
+        - Binary files are refused.
+        - CRLF files are matched in LF space; the original line endings are preserved on write.
+      DESC
+
+      # @param workspace [Tool::Workspace] captured for path resolution;
+      #   all reads/writes route through +workspace.resolve_for_write+
+      #   (Edit modifies, so it uses the write-set even though it doesn't
+      #   create files).
+      # @return [Edit]
+      def initialize(workspace:)
+        super(
+          name: 'edit',
+          description: DESCRIPTION,
+          parameters: Parameters.build { |p|
+            p.required_string :path,
+                              'Path to the file to edit. Relative paths ' \
+                              'resolve against the workspace root, e.g. ' \
+                              '"lib/foo.rb".'
+            p.required_string :old_string,
+                              'Exact text to find in the file. Must match ' \
+                              'byte-for-byte (whitespace counts); must be ' \
+                              'unique unless replace_all is true. Example: ' \
+                              '"def foo\n  bar\nend".'
+            p.required_string :new_string,
+                              'Replacement text. Must differ from ' \
+                              'old_string. Example: "def foo\n  baz\nend".'
+            p.optional_boolean :replace_all,
+                               'Replace every occurrence of old_string ' \
+                               'instead of failing on multiple matches. ' \
+                               'Defaults to false, e.g. true.'
+          },
+          execute: ->(path:, old_string:, new_string:, replace_all: false) {
+            Edit.edit(workspace: workspace, path: path,
+                      old_string: old_string, new_string: new_string,
+                      replace_all: replace_all)
+          }
+        )
+      end
+
+      # Resolve +path+ against +workspace+, run the precondition checks
+      # (non-empty / non-identical / file exists / not directory / not
+      # binary), match +old_string+ in line-ending-normalized form, and
+      # write the result back preserving the file's original line endings.
+      #
+      # @param workspace [Tool::Workspace]
+      # @param path [String] raw path as supplied by the LLM
+      # @param old_string [String] text to find
+      # @param new_string [String] text to substitute in
+      # @param replace_all [Boolean] when true, every occurrence is
+      #   replaced; when false (default) multiple matches are an error
+      # @return [String] tool observation
+      def self.edit(workspace:, path:, old_string:, new_string:, replace_all:)
+        return 'Error: old_string is empty; use the write tool to create or overwrite a file.' if old_string.empty?
+        return 'Error: old_string and new_string are identical — this edit is a no-op.' if old_string == new_string
+
+        resolved = workspace.resolve_for_write(path)
+        return "Error: file not found: #{path}" unless resolved.exist?
+        return "Error: #{path} is a directory" if resolved.directory?
+
+        raw = resolved.binread
+        sample = raw.byteslice(0, Tool::Read::BINARY_SAMPLE_BYTES)
+        return "Error: cannot edit binary file: #{path}" if Tool::Read.binary?(sample)
+
+        crlf    = raw.include?("\r\n")
+        content = crlf ? raw.gsub("\r\n", "\n") : raw
+        needle  = normalize_lf(old_string)
+        patch   = normalize_lf(new_string)
+
+        occurrences = content.scan(needle).size
+        if occurrences.zero?
+          return "Error: old_string not found in #{path}. It must match the file " \
+                 'exactly, including whitespace and indentation; re-read with the ' \
+                 'read tool if uncertain.'
+        end
+        if occurrences > 1 && !replace_all
+          return "Error: old_string matches #{occurrences} times in #{path}. " \
+                 'Provide more surrounding context to make the match unique, ' \
+                 'or set replace_all=true to replace all occurrences.'
+        end
+
+        replaced = replace_all ? occurrences : 1
+        new_content =
+          if replace_all
+            # Block form bypasses gsub's \1 / \& interpolation on the
+            # replacement String — we want literal substitution.
+            content.gsub(needle) { patch }
+          else
+            idx = content.index(needle)
+            content.byteslice(0, idx) + patch + content.byteslice(idx + needle.bytesize, content.bytesize - idx - needle.bytesize)
+          end
+
+        final = crlf ? new_content.gsub("\n", "\r\n") : new_content
+        resolved.write(final)
+
+        "Edited #{path}: replaced #{replaced} occurrence#{replaced == 1 ? '' : 's'}."
+      rescue Tool::Workspace::Error => e
+        "Error: #{e.message}"
+      rescue Errno::EACCES => e
+        "Error: cannot edit #{path}: #{e.message}"
+      end
+
+      # Force a String to BINARY encoding and collapse +\r\n+ → +\n+ so
+      # all matching/replacement happens in LF space with byte-stable
+      # comparisons. Applied to the file content, +old_string+, and
+      # +new_string+ alike — symmetric normalization keeps the byte-match
+      # semantics consistent across all three inputs.
+      #
+      # @param str [String]
+      # @return [String] BINARY-encoded, CRLF-collapsed copy
+      def self.normalize_lf(str)
+        str.b.gsub("\r\n", "\n")
+      end
+      private_class_method :normalize_lf
+    end
+  end
+end