agent-petri-dish 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 849092bef9d9c12b37c15092a716f21cafa4d4bf145ad06258d0e92d053ce569
+  data.tar.gz: b895970d3c5c42dc66f12da3ff2ef51bbfc1f6695a9066575fde7febab59c255
+SHA512:
+  metadata.gz: 5f7261bb5640b236e155221bb9239ac99330bef6c0b952ba1739f44ee33c75e26e8ae6b49a9b308b1c09efe2defdd387335cfac08bceda6e601773ba2d5a13a0
+  data.tar.gz: d740e94d2459baf5ba0f74913a8b4e3dfa675a9ef14f3ea54c7e53e0e429d18d84d4d6d0a534968a76a366a96b64770c24d7309885211d19f67ded797a2fe276

data/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing to petri-dish
+
+Thanks for considering a contribution.
+
+## Adding an example culture
+
+Each culture lives under `examples/<name>/` and contains:
+
+- `config.yml`: environment, plugins, settings, runtime config, prompt mode.
+- `prompt.md`: what Claude should do.
+
+See existing examples for the shape, and read [`claude-plugin/skills/petri-dish/references/authoring-cultures.md`](claude-plugin/skills/petri-dish/references/authoring-cultures.md) for the conventions behind those shapes (prompt anatomy, baseline cells, preamble selection, multi-run discipline, gotchas). Culture names follow `category-NN[variant]-short-description`, e.g. `sandbox-07b-escape-hatch-disabled`.
+
+For multi-part cultures sharing a prompt, symlink the shared prompt:
+
+```
+examples/sandbox-07b-escape-hatch-disabled/prompt.md -> ../sandbox-07-escape-hatch/prompt.md
+```
+
+## Running an example locally
+
+```
+petri-dish setup --cultures-dir examples sandbox-01-baseline
+petri-dish run --cultures-dir examples sandbox-01-baseline
+petri-dish results --cultures-dir examples sandbox-01-baseline
+```
+
+## Code style
+
+- `frozen_string_literal: true` at the top of every Ruby file.
+- No em-dashes in user-facing strings (use parens, colons, or split sentences).
+- Keep modules small and focused.
+
+## Submitting changes
+
+Open a PR with a clear description of the change and which examples were verified.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Josh Nichols
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,145 @@
+# petri-dish
+
+A petri-dish for agentic coding experiments. Keep your cultures in your lab; load them into a dish to see how they grow.
+
+## Why
+
+Your `~/.claude/` is production. There's no staging copy of it, no rollback if a hook misbehaves or a plugin clobbers your settings. [I've written about this.](https://pickles.dev/dot-claude-is-production/) `CLAUDE_CONFIG_DIR` gets you a sandbox; petri-dish gets you reproducible experiments inside one.
+
+A **culture** is one experiment: a `config.yml` + `prompt.md` pair. A **petri-dish** is what runs it. Each dish is isolated via [cenv](https://github.com/technicalpickles/cenv) so the experiment never touches your real config, and hooks injected into the dish observe the run from inside without disturbing it.
+
+## What it does
+
+`petri-dish run <culture>` boots an isolated cenv environment, injects PreToolUse/PostToolUse/PermissionRequest hooks, runs Claude Code against your prompt, and correlates the event log into a structured results file.
+
+## Requirements
+
+- Ruby >= 3.2
+- [cenv](https://github.com/technicalpickles/cenv) for environment isolation
+- tmux
+- The Claude Code CLI (`claude`)
+
+## Install
+
+```
+gem install agent-petri-dish
+```
+
+That puts `petri-dish` on your PATH. (The gem name is prefixed because `petri_dish` was already taken on rubygems; the CLI stays `petri-dish`.)
+
+### Without setting up Ruby
+
+If you don't want to deal with a Ruby toolchain, use [rv](https://github.com/spinel-coop/rv). It manages an isolated Ruby per tool and installs one for you if you don't have one.
+
+```
+brew install rv
+rv tool install agent-petri-dish
+```
+
+For one-off invocation without touching shell init:
+
+```
+rv tool run --from agent-petri-dish petri-dish list
+```
+
+For the `petri-dish` binary on your PATH, follow `rv shell <your-shell>` to wire rv into your shell.
+
+### From source
+
+```
+git clone https://github.com/technicalpickles/petri-dish.git
+cd petri-dish
+gem build petri-dish.gemspec
+gem install agent-petri-dish-0.1.0.gem
+```
+
+## Quick start
+
+```
+mkdir my-lab && cd my-lab
+mkdir -p cultures/my-first-culture
+# write cultures/my-first-culture/config.yml and prompt.md
+petri-dish setup my-first-culture
+petri-dish run my-first-culture
+petri-dish results my-first-culture
+```
+
+By default, petri-dish looks for cultures in `./cultures/` relative to your current directory. Override with `--cultures-dir <path>` or `PETRIDISH_CULTURES_DIR`.
+
+To explore the bundled examples, from the cloned petri-dish repo:
+
+```
+petri-dish run --cultures-dir examples sandbox-01-baseline
+```
+
+## How it works
+
+1. **Environment.** Each culture gets its own cenv environment with specific settings (sandbox config, permissions, plugins). Nothing touches your `~/.claude/`.
+2. **Hooks.** PreToolUse, PostToolUse, and PermissionRequest hooks are injected into the dish to log events and auto-handle permission prompts.
+3. **Prompt.** A markdown prompt tells Claude what commands to run and what to observe.
+4. **Results.** Hook event logs are correlated into structured results (prompted vs silent, timing, outcomes).
+
+## CLI reference
+
+```
+Usage: petri-dish <command> [options]
+
+Commands:
+  run <culture> [--deny] [--debug] [--keep] [--cultures-dir DIR]
+  list                    List available cultures
+  results [culture]       Show past results
+  setup [culture]         Create environments
+  setup --clean [culture] Tear down environments
+  help                    Show this help
+```
+
+## Adding a culture
+
+Each culture directory needs two files:
+
+```
+cultures/my-culture/
+  config.yml
+  prompt.md
+```
+
+See `examples/` for working configs. The schema:
+
+```yaml
+name: my-culture
+description: "One-line description"
+
+environment:
+  name: test-my-culture
+  plugins: []
+  settings:
+    sandbox:
+      enabled: true
+    permissions:
+      allow:
+        - Read
+        - Write
+
+runtime:
+  work_dir: /tmp/sandbox-test
+  preamble: lib/preambles/sandbox.md   # optional, resolves to a bundled or local preamble
+  inject_results_file: true
+  timeout: 300
+
+prompt_mode: accept   # or "deny"
+```
+
+For a longer reference, including prompt-shape conventions, cell discipline (baseline cells, multi-run averaging, A/B variants), preamble selection, and the brittle bits to watch for, see [`claude-plugin/skills/petri-dish/references/authoring-cultures.md`](claude-plugin/skills/petri-dish/references/authoring-cultures.md).
+
+If you use Claude Code, the [companion plugin](claude-plugin/README.md) ships that same reference as a skill so an agent can author cultures with the discipline already in working memory.
+
+## Examples included
+
+- `sandbox-*`: probes of Claude Code's sandbox behavior across filesystem, network, IPC, and escape-hatch settings.
+- `permissions-*`: how permission prompts behave under different settings.
+- `guidance-*`: prompt-layer interventions for sandbox-safe path selection.
+- `parser-*`: Claude Code's permission parser boundary cases.
+
+## License
+
+MIT. See LICENSE.

data/bin/petri-dish

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "petri_dish"
+
+PetriDish::CLI.new(ARGV).run

data/hooks/event-logger.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Hook event logger: reads JSON from stdin, adds timestamp, appends to JSONL file.
+# Attached to all non-decision hook event types: PreToolUse, PostToolUse,
+# UserPromptSubmit, Notification, Stop, SubagentStop, PreCompact, SessionStart,
+# SessionEnd, PermissionDenied.
+#
+# Environment:
+#   PETRIDISH_HOOK_LOG_FILE - path to append JSONL entries (required)
+
+set -euo pipefail
+
+LOG_FILE="${PETRIDISH_HOOK_LOG_FILE:?PETRIDISH_HOOK_LOG_FILE must be set}"
+TS=$(date -u +"%Y-%m-%dT%H:%M:%S.%3NZ" 2>/dev/null || date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+PAYLOAD=$(cat)
+
+printf '{"ts":"%s","payload":%s}\n' "$TS" "$PAYLOAD" >> "$LOG_FILE"
+
+exit 0

data/hooks/permission-handler.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Permission handler: logs PermissionRequest/PermissionDenied events and
+# returns allow/deny decision for PermissionRequest.
+#
+# Environment:
+#   PETRIDISH_HOOK_LOG_FILE            - path to append JSONL entries (required)
+#   PETRIDISH_PERMISSION_MODE  - "accept" or "deny" (default: accept)
+
+set -euo pipefail
+
+LOG_FILE="${PETRIDISH_HOOK_LOG_FILE:?PETRIDISH_HOOK_LOG_FILE must be set}"
+MODE="${PETRIDISH_PERMISSION_MODE:-accept}"
+TS=$(date -u +"%Y-%m-%dT%H:%M:%S.%3NZ" 2>/dev/null || date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+PAYLOAD=$(cat)
+
+# Log the event
+printf '{"ts":"%s","payload":%s}\n' "$TS" "$PAYLOAD" >> "$LOG_FILE"
+
+# Extract event name to decide whether to return a decision
+EVENT_NAME=$(printf '%s' "$PAYLOAD" | grep -o '"hook_event_name":"[^"]*"' | cut -d'"' -f4)
+
+if [ "$EVENT_NAME" = "PermissionRequest" ]; then
+  if [ "$MODE" = "deny" ]; then
+    cat <<'DENY'
+{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"deny","message":"Denied by petri-dish"}}}
+DENY
+  else
+    cat <<'ALLOW'
+{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow"}}}
+ALLOW
+  fi
+fi
+
+exit 0

data/lib/petri-dish.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "petri_dish"

data/lib/petri_dish/cli.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "fileutils"
+
+module PetriDish
+  class CLI
+    def initialize(argv)
+      @argv = argv
+    end
+
+    def run
+      if @argv.empty?
+        usage
+        exit 1
+      end
+
+      command = @argv.shift
+      case command
+      when "run"      then cmd_run
+      when "list"     then cmd_list
+      when "results"  then cmd_results
+      when "setup"    then cmd_setup
+      when "help", "--help", "-h"
+        usage
+      else
+        $stderr.puts "Unknown command: #{command}"
+        usage
+        exit 1
+      end
+    end
+
+    private
+
+    def cultures_dir
+      @cultures_dir ||= ENV["PETRIDISH_CULTURES_DIR"] || File.join(Dir.pwd, "cultures")
+    end
+
+    def results_dir
+      @results_dir ||= File.join(Dir.pwd, "results")
+    end
+
+    def parse_cultures_dir_flag!
+      parser = OptionParser.new do |opts|
+        opts.on("--cultures-dir DIR", "Override the cultures directory") { |d| @cultures_dir = d }
+      end
+      parser.order!(@argv)
+    end
+
+    def cmd_run
+      parse_cultures_dir_flag!
+      options = { deny: false, debug: false, keep: false }
+      parser = OptionParser.new do |opts|
+        opts.on("--deny", "Deny all permission prompts") { options[:deny] = true }
+        opts.on("--debug", "Show hook events in real time") { options[:debug] = true }
+        opts.on("--keep", "Don't kill tmux on completion") { options[:keep] = true }
+      end
+      parser.parse!(@argv)
+
+      test_name = @argv.shift
+      unless test_name
+        $stderr.puts "Usage: petri-dish run <culture> [options]"
+        exit 1
+      end
+
+      validate_test!(test_name)
+      runner = Runner.new(test_name, cultures_dir: cultures_dir, results_dir: results_dir, **options)
+      runner.run!
+    end
+
+    def cmd_list
+      parse_cultures_dir_flag!
+      puts "Available cultures in #{cultures_dir}:\n\n"
+      each_test do |name, config|
+        puts "  \e[32m#{name}\e[0m"
+        puts "    #{config.description}"
+        puts "    env: #{config.environment[:name]}, mode: #{config.prompt_mode}, timeout: #{config.runtime[:timeout]}s"
+        puts ""
+      end
+    end
+
+    def cmd_results
+      test_filter = @argv.shift
+
+      unless File.directory?(results_dir)
+        puts "No results yet."
+        return
+      end
+
+      Dir.glob("#{results_dir}/*/").sort.each do |test_dir|
+        test_name = File.basename(test_dir)
+        next if test_filter && test_name != test_filter
+
+        runs = Dir.glob("#{test_dir}/*/").sort.reverse
+        next if runs.empty?
+
+        puts "\e[32m#{test_name}\e[0m (#{runs.size} run#{'s' if runs.size != 1})"
+        runs.each do |run_dir|
+          timestamp = File.basename(run_dir)
+          has_results = File.exist?(File.join(run_dir, "results.md"))
+          has_transcript = File.exist?(File.join(run_dir, "transcript.log"))
+          status = has_results ? "results" : "no results"
+          status += ", transcript" if has_transcript
+          puts "  #{timestamp}  (#{status})"
+        end
+        puts ""
+      end
+    end
+
+    def cmd_setup
+      clean = @argv.delete("--clean")
+      parse_cultures_dir_flag!
+      test_filter = @argv.shift
+
+      tests = if test_filter
+                validate_test!(test_filter)
+                [test_filter]
+              else
+                available_tests
+              end
+
+      if clean
+        tests.each { |name| teardown_test(name) }
+      else
+        tests.each { |name| setup_test(name) }
+      end
+    end
+
+    def setup_test(test_name)
+      config = Config.new(File.join(cultures_dir, test_name))
+      env = Environment.new(config.environment[:name])
+
+      puts "\e[32m[setup]\e[0m Setting up: #{test_name}"
+
+      if config.runtime[:work_dir] == "/tmp/sandbox-test"
+        setup_scratch_project
+      end
+
+      env.create!
+      env.merge_settings!(config.environment[:settings])
+      env.inject_hooks!(prompt_mode: config.prompt_mode)
+      env.trust!(config.runtime[:work_dir])
+
+      config.environment[:plugins].each do |plugin|
+        env.install_plugin!(marketplace: plugin[:marketplace], plugin: plugin[:plugin])
+      end
+
+      puts "\e[32m[setup]\e[0m #{test_name} ready\n\n"
+    end
+
+    def teardown_test(test_name)
+      config = Config.new(File.join(cultures_dir, test_name))
+      env = Environment.new(config.environment[:name])
+      puts "\e[32m[setup]\e[0m Cleaning: #{test_name}"
+      env.clean!
+    end
+
+    def setup_scratch_project
+      scratch = "/tmp/sandbox-test"
+      if File.directory?(File.join(scratch, ".git"))
+        puts "\e[32m[setup]\e[0m Scratch project already exists"
+        return
+      end
+
+      puts "\e[32m[setup]\e[0m Creating scratch project at #{scratch}"
+      FileUtils.mkdir_p(scratch)
+      system("git", "-C", scratch, "init")
+      File.write(File.join(scratch, "README.md"), "# Sandbox Test Project\n")
+      system("git", "-C", scratch, "add", "README.md")
+      system("git", "-C", scratch, "commit", "-m", "init")
+      FileUtils.mkdir_p(File.join(scratch, ".claude"))
+    end
+
+    def validate_test!(name)
+      test_dir = File.join(cultures_dir, name)
+      unless File.directory?(test_dir)
+        $stderr.puts "Culture not found: #{name}"
+        $stderr.puts "Cultures dir: #{cultures_dir}"
+        $stderr.puts "Available cultures: #{available_tests.join(', ')}"
+        exit 1
+      end
+    end
+
+    def available_tests
+      Dir.glob("#{cultures_dir}/*/config.yml").map { |p| File.basename(File.dirname(p)) }.sort
+    end
+
+    def each_test
+      available_tests.each do |name|
+        config = Config.new(File.join(cultures_dir, name))
+        yield name, config
+      end
+    end
+
+    def usage
+      puts <<~USAGE
+        Usage: petri-dish <command> [options]
+
+        Commands:
+          run <culture> [--deny] [--debug] [--keep] [--cultures-dir DIR]
+          list                    List available cultures
+          results [culture]       Show past results
+          setup [culture]         Create environments
+          setup --clean [culture] Tear down environments
+          help                    Show this help
+
+        Cultures directory resolution (in order):
+          1. --cultures-dir flag
+          2. $PETRIDISH_CULTURES_DIR environment variable
+          3. ./cultures/ relative to current directory
+      USAGE
+    end
+  end
+end

data/lib/petri_dish/config.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "pathname"
+
+module PetriDish
+  class Config
+    REQUIRED_KEYS = %w[name description environment runtime].freeze
+    REQUIRED_ENV_KEYS = %w[name].freeze
+    VALID_PROMPT_MODES = %w[accept deny].freeze
+
+    attr_reader :name, :description, :environment, :runtime, :prompt_mode, :test_dir
+
+    def initialize(test_dir)
+      @test_dir = Pathname.new(test_dir).expand_path
+      config_path = @test_dir / "config.yml"
+      raise "Config not found: #{config_path}" unless config_path.exist?
+
+      data = YAML.safe_load(config_path.read, permitted_classes: [Symbol])
+      validate!(data)
+
+      @name = data["name"]
+      @description = data["description"]
+      @environment = parse_environment(data["environment"])
+      @runtime = parse_runtime(data["runtime"])
+      @prompt_mode = parse_prompt_mode(data["prompt_mode"])
+    end
+
+    def prompt_path
+      test_dir / "prompt.md"
+    end
+
+    private
+
+    def validate!(data)
+      REQUIRED_KEYS.each do |key|
+        raise "Missing required key: #{key}" unless data.key?(key)
+      end
+      REQUIRED_ENV_KEYS.each do |key|
+        raise "Missing environment.#{key}" unless data.dig("environment", key)
+      end
+    end
+
+    def parse_environment(env)
+      {
+        name: env["name"],
+        plugins: (env["plugins"] || []).map { |p| { marketplace: p["marketplace"], plugin: p["plugin"] } },
+        settings: env["settings"] || {}
+      }
+    end
+
+    def parse_runtime(rt)
+      {
+        work_dir: expand_home(rt["work_dir"] || "."),
+        preamble: rt["preamble"],
+        inject_results_file: rt.fetch("inject_results_file", true),
+        part_suffix: rt["part_suffix"],
+        model: rt["model"],
+        timeout: rt.fetch("timeout", 300),
+        prepare: Array(rt["prepare"])
+      }
+    end
+
+    def parse_prompt_mode(mode)
+      mode ||= "accept"
+      raise "Invalid prompt_mode: #{mode}" unless VALID_PROMPT_MODES.include?(mode)
+
+      mode
+    end
+
+    def expand_home(path)
+      path.sub(/\A~/, Dir.home)
+    end
+  end
+end