pikuri-workspace

Filesystem tools + Workspace/Confirmer seams for the pikuri AI-assistant toolkit.

Self-contained "operate on a directory tree" toolkit:

• Pikuri::Workspace::Filesystem — scopes filesystem access to a project root + explicit readable / writable prefix lists, with an optional ephemeral temp playground. Rejects ..-escapes and symlinks that resolve outside the configured roots.
• Pikuri::Workspace::Confirmer — abstract base + AUTO_APPROVE / TERMINAL for user-state mutations.
• Five file tools: Pikuri::Workspace::Read, Pikuri::Workspace::Write, Pikuri::Workspace::Edit, Pikuri::Workspace::Grep, Pikuri::Workspace::Glob.

No shell execution — Pikuri::Code::Bash ships in pikuri-code on top of these.

Install

# Gemfile
gem 'pikuri-workspace'

Usage

require 'pikuri-core'
require 'pikuri-workspace'

workspace = Pikuri::Workspace::Filesystem.new(project_root: Dir.pwd)
confirmer = Pikuri::Workspace::Confirmer::TERMINAL

agent = Pikuri::Agent.new(
  transport: ...,
  system_prompt: ...,
) do |c|
  c.add_tool Pikuri::Workspace::Read.new(workspace: workspace)
  c.add_tool Pikuri::Workspace::Grep.new(workspace: workspace)
  c.add_tool Pikuri::Workspace::Glob.new(workspace: workspace)
  c.add_tool Pikuri::Workspace::Edit.new(workspace: workspace)
  c.add_tool Pikuri::Workspace::Write.new(workspace: workspace, confirmer: confirmer)
  c.add_listener ...
end

Workspace is the "look-but-don't-leak" guard around filesystem access. Read tools route through #resolve_for_read(path); mutating tools route through #resolve_for_write(path) + the Confirmer's #confirm?(prompt:). Pass temp: true to mint an ephemeral writable playground via Dir.mktmpdir — its path is exposed as workspace.temp and auto-removed at process exit.

Further reading

• Narrative walkthrough: the "Workspace seam" and "Confirmer seam" sections of chapter 8 of the pikuri guide — what each kwarg of Filesystem.new controls, when to use the AllowAll variant, and how the seams fit alongside Sandbox.
• API reference: browse the YARD docs at https://rubydoc.info/gems/pikuri-workspace (once published), or run bundle exec yard in this directory for a local copy.