claude_swarm 1.0.0 → 1.0.2

data/examples/v2/hooks/post_tool_use_exit_1.yml

@@ -0,0 +1,24 @@
+# Test: post_tool_use with exit 1
+# Expected: stderr added to log stream, execution continues (non-blocking error)
+# Run: bundle exec exe/swarm run lib/swarm_sdk/examples/hooks/post_tool_use_exit_1.yml -p "Run 'ls' command"
+
+version: 2
+swarm:
+  name: "post_tool_use Exit 1 Test"
+  lead: agent
+
+  agents:
+    agent:
+      description: "Test agent"
+      model: gpt-5
+      provider: openai
+      system_prompt: "You are a test agent."
+      tools:
+        - Bash
+
+      hooks:
+        post_tool_use:
+          - matcher: "Bash"
+            type: command
+            command: "echo 'Warning: Bash tool execution metrics collection failed' >&2 && exit 1"
+            timeout: 5

data/examples/v2/hooks/post_tool_use_exit_2.yml

@@ -0,0 +1,24 @@
+# Test: post_tool_use with exit 2
+# Expected: Tool already ran, stderr sent to agent to process
+# Run: bundle exec exe/swarm run lib/swarm_sdk/examples/hooks/post_tool_use_exit_2.yml -p "Run 'ls' command"
+
+version: 2
+swarm:
+  name: "post_tool_use Exit 2 Test"
+  lead: agent
+
+  agents:
+    agent:
+      description: "Test agent"
+      model: gpt-5
+      provider: openai
+      system_prompt: "You are a test agent."
+      tools:
+        - Bash
+
+      hooks:
+        post_tool_use:
+          - matcher: "Bash"
+            type: command
+            command: "echo 'ERROR: Bash tool produced suspicious output. Review the command output carefully for security issues.' >&2 && exit 2"
+            timeout: 5

data/examples/v2/hooks/post_tool_use_multi_matcher_exit_0.yml

@@ -0,0 +1,26 @@
+# Test: post_tool_use with multiple tool matcher (Read|Grep|Glob) and exit 0
+# Expected: stdout logged, execution continues
+# Run: bundle exec exe/swarm run lib/swarm_sdk/examples/hooks/post_tool_use_multi_matcher_exit_0.yml -p "Search README.md for 'swarm'"
+
+version: 2
+swarm:
+  name: "post_tool_use Multi-Matcher Exit 0"
+  lead: agent
+
+  agents:
+    agent:
+      description: "Test agent"
+      model: gpt-5
+      provider: openai
+      system_prompt: "You are a test agent."
+      tools:
+        - Read
+        - Grep
+        - Glob
+
+      hooks:
+        post_tool_use:
+          - matcher: "Read|Grep|Glob"
+            type: command
+            command: "echo 'File access logged successfully for audit' && exit 0"
+            timeout: 5

data/examples/v2/hooks/post_tool_use_multi_matcher_exit_1.yml

@@ -0,0 +1,26 @@
+# Test: post_tool_use with multiple tool matcher (Read|Grep|Glob) and exit 1
+# Expected: stderr logged as warning, execution continues
+# Run: bundle exec exe/swarm run lib/swarm_sdk/examples/hooks/post_tool_use_multi_matcher_exit_1.yml -p "Search README.md for 'swarm'"
+
+version: 2
+swarm:
+  name: "post_tool_use Multi-Matcher Exit 1"
+  lead: agent
+
+  agents:
+    agent:
+      description: "Test agent"
+      model: gpt-5
+      provider: openai
+      system_prompt: "You are a test agent."
+      tools:
+        - Read
+        - Grep
+        - Glob
+
+      hooks:
+        post_tool_use:
+          - matcher: "Read|Grep|Glob"
+            type: command
+            command: "echo 'Warning: Could not update file access statistics' >&2 && exit 1"
+            timeout: 5

data/examples/v2/hooks/post_tool_use_multi_matcher_exit_2.yml

@@ -0,0 +1,26 @@
+# Test: post_tool_use with multiple tool matcher (Read|Grep|Glob) and exit 2
+# Expected: Tools already ran, stderr sent to agent to review output
+# Run: bundle exec exe/swarm run lib/swarm_sdk/examples/hooks/post_tool_use_multi_matcher_exit_2.yml -p "Search README.md for 'swarm'"
+
+version: 2
+swarm:
+  name: "post_tool_use Multi-Matcher Exit 2"
+  lead: agent
+
+  agents:
+    agent:
+      description: "Test agent"
+      model: gpt-5
+      provider: openai
+      system_prompt: "You are a test agent."
+      tools:
+        - Read
+        - Grep
+        - Glob
+
+      hooks:
+        post_tool_use:
+          - matcher: "Read|Grep|Glob"
+            type: command
+            command: "echo 'SECURITY WARNING: File access tool detected potential sensitive data exposure. Review the output carefully before proceeding.' >&2 && exit 2"
+            timeout: 5

data/examples/v2/hooks/pre_tool_use_exit_0.yml

@@ -0,0 +1,24 @@
+# Test: pre_tool_use with exit 0
+# Expected: stdout added to log stream, execution continues
+# Run: bundle exec exe/swarm run lib/swarm_sdk/examples/hooks/pre_tool_use_exit_0.yml -p "Run 'ls' command"
+
+version: 2
+swarm:
+  name: "pre_tool_use Exit 0 Test"
+  lead: agent
+
+  agents:
+    agent:
+      description: "Test agent"
+      model: gpt-5
+      provider: openai
+      system_prompt: "You are a test agent."
+      tools:
+        - Bash
+
+      hooks:
+        pre_tool_use:
+          - matcher: "Bash"
+            type: command
+            command: "echo 'Validation passed - allowing Bash tool' && exit 0"
+            timeout: 5

data/examples/v2/hooks/pre_tool_use_exit_1.yml

@@ -0,0 +1,24 @@
+# Test: pre_tool_use with exit 1
+# Expected: stderr added to log stream, execution continues (non-blocking error)
+# Run: bundle exec exe/swarm run lib/swarm_sdk/examples/hooks/pre_tool_use_exit_1.yml -p "Run 'ls' command"
+
+version: 2
+swarm:
+  name: "pre_tool_use Exit 1 Test"
+  lead: agent
+
+  agents:
+    agent:
+      description: "Test agent"
+      model: gpt-5
+      provider: openai
+      system_prompt: "You are a test agent."
+      tools:
+        - Bash
+
+      hooks:
+        pre_tool_use:
+          - matcher: "Bash"
+            type: command
+            command: "echo 'Warning: unusual Bash usage detected' >&2 && exit 1"
+            timeout: 5

data/examples/v2/hooks/pre_tool_use_exit_2.yml

@@ -0,0 +1,24 @@
+# Test: pre_tool_use with exit 2
+# Expected: Blocks tool execution, stderr sent to agent
+# Run: bundle exec exe/swarm run lib/swarm_sdk/examples/hooks/pre_tool_use_exit_2.yml -p "Run 'ls' command"
+
+version: 2
+swarm:
+  name: "pre_tool_use Exit 2 Test"
+  lead: agent
+
+  agents:
+    agent:
+      description: "Test agent"
+      model: gpt-5
+      provider: openai
+      system_prompt: "You are a test agent."
+      tools:
+        - Bash
+
+      hooks:
+        pre_tool_use:
+          - matcher: "Bash"
+            type: command
+            command: "echo 'Bash tool is disabled by policy. Please use alternative methods.' >&2 && exit 2"
+            timeout: 5

data/examples/v2/hooks/pre_tool_use_multi_matcher_exit_0.yml

@@ -0,0 +1,26 @@
+# Test: pre_tool_use with multiple tool matcher (Read|Grep|Glob) and exit 0
+# Expected: stdout logged, tools execute normally
+# Run: bundle exec exe/swarm run lib/swarm_sdk/examples/hooks/pre_tool_use_multi_matcher_exit_0.yml -p "Search README.md for 'swarm'"
+
+version: 2
+swarm:
+  name: "pre_tool_use Multi-Matcher Exit 0"
+  lead: agent
+
+  agents:
+    agent:
+      description: "Test agent"
+      model: gpt-5
+      provider: openai
+      system_prompt: "You are a test agent."
+      tools:
+        - Read
+        - Grep
+        - Glob
+
+      hooks:
+        pre_tool_use:
+          - matcher: "Read|Grep|Glob"
+            type: command
+            command: "echo 'Validating file access tool usage' && exit 0"
+            timeout: 5

data/examples/v2/hooks/pre_tool_use_multi_matcher_exit_1.yml

@@ -0,0 +1,26 @@
+# Test: pre_tool_use with multiple tool matcher (Read|Grep|Glob) and exit 1
+# Expected: stderr logged as warning, tools execute normally
+# Run: bundle exec exe/swarm run lib/swarm_sdk/examples/hooks/pre_tool_use_multi_matcher_exit_1.yml -p "Search README.md for 'swarm'"
+
+version: 2
+swarm:
+  name: "pre_tool_use Multi-Matcher Exit 1"
+  lead: agent
+
+  agents:
+    agent:
+      description: "Test agent"
+      model: gpt-5
+      provider: openai
+      system_prompt: "You are a test agent."
+      tools:
+        - Read
+        - Grep
+        - Glob
+
+      hooks:
+        pre_tool_use:
+          - matcher: "Read|Grep|Glob"
+            type: command
+            command: "echo 'Warning: File access monitoring service unavailable' >&2 && exit 1"
+            timeout: 5

data/examples/v2/hooks/pre_tool_use_multi_matcher_exit_2.yml

@@ -0,0 +1,27 @@
+# Test: pre_tool_use with multiple tool matcher (Read|Grep|Glob) and exit 2
+# Expected: Tools blocked, stderr sent to agent
+# Run: bundle exec exe/swarm run lib/swarm_sdk/examples/hooks/pre_tool_use_multi_matcher_exit_2.yml -p "Search README.md for 'swarm'"
+
+version: 2
+swarm:
+  name: "pre_tool_use Multi-Matcher Exit 2"
+  lead: agent
+
+  agents:
+    agent:
+      description: "Test agent"
+      model: gpt-5
+      provider: openai
+      system_prompt: "You are a test agent."
+      tools:
+        - Read
+        - Grep
+        - Glob
+        - Bash  # Allow Bash as alternative
+
+      hooks:
+        pre_tool_use:
+          - matcher: "Read|Grep|Glob"
+            type: command
+            command: "echo 'File access tools are disabled. Use Bash with cat/grep commands instead.' >&2 && exit 2"
+            timeout: 5

data/examples/v2/hooks/swarm_summary.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+#
+# Example swarm_stop hook: Generate execution summary
+#
+# This demonstrates:
+# - Reading JSON from stdin
+# - Accessing swarm metadata
+# - Generating output
+# - Exit 0 to continue (allow swarm to finish)
+
+# Read JSON input from stdin
+input=$(cat)
+
+# Parse fields using jq (if available) or basic grep
+if command -v jq &> /dev/null; then
+    swarm_name=$(echo "$input" | jq -r '.swarm // "Unknown"')
+    success=$(echo "$input" | jq -r '.success // false')
+    duration=$(echo "$input" | jq -r '.duration // 0')
+    cost=$(echo "$input" | jq -r '.total_cost // 0')
+else
+    swarm_name="Unknown"
+    success="unknown"
+fi
+
+# Print summary to stderr (visible in logs)
+echo "========================================" >&2
+echo "Swarm Execution Summary" >&2
+echo "========================================" >&2
+echo "Swarm: $swarm_name" >&2
+echo "Success: $success" >&2
+echo "Duration: ${duration}s" >&2
+echo "Cost: \$${cost}" >&2
+echo "========================================" >&2
+
+# Output success JSON
+cat << EOF
+{
+  "success": true,
+  "message": "Summary generated"
+}
+EOF
+
+# Exit 0 to allow swarm to finish normally
+exit 0

data/examples/v2/hooks/user_prompt_exit_0.yml

@@ -0,0 +1,21 @@
+# Test: user_prompt with exit 0
+# Expected: stdout appended to prompt and shown to agent
+# Run: bundle exec exe/swarm run lib/swarm_sdk/examples/hooks/user_prompt_exit_0.yml -p "What is 2+2?"
+
+version: 2
+swarm:
+  name: "user_prompt Exit 0 Test"
+  lead: agent
+
+  agents:
+    agent:
+      description: "Test agent"
+      model: gpt-5
+      provider: openai
+      system_prompt: "You are a test agent."
+
+      hooks:
+        user_prompt:
+          - type: command
+            command: "echo 'Additional context from hook: Current timestamp is' $(date) && exit 0"
+            timeout: 5

data/examples/v2/hooks/user_prompt_exit_1.yml

@@ -0,0 +1,21 @@
+# Test: user_prompt with exit 1
+# Expected: stderr added to log stream, execution continues (non-blocking error)
+# Run: bundle exec exe/swarm run lib/swarm_sdk/examples/hooks/user_prompt_exit_1.yml -p "What is 2+2?"
+
+version: 2
+swarm:
+  name: "user_prompt Exit 1 Test"
+  lead: agent
+
+  agents:
+    agent:
+      description: "Test agent"
+      model: gpt-5
+      provider: openai
+      system_prompt: "You are a test agent."
+
+      hooks:
+        user_prompt:
+          - type: command
+            command: "echo 'Warning: Unable to fetch additional context for this prompt' >&2 && exit 1"
+            timeout: 5

data/examples/v2/hooks/user_prompt_exit_2.yml

@@ -0,0 +1,21 @@
+# Test: user_prompt with exit 2
+# Expected: Blocks prompt processing, prompt erased, stderr to logs only (NOT to agent)
+# Run: bundle exec exe/swarm run lib/swarm_sdk/examples/hooks/user_prompt_exit_2.yml -p "Any dangerous prompt"
+
+version: 2
+swarm:
+  name: "user_prompt Exit 2 Test"
+  lead: agent
+
+  agents:
+    agent:
+      description: "Test agent"
+      model: gpt-5
+      provider: openai
+      system_prompt: "You are a test agent."
+
+      hooks:
+        user_prompt:
+          - type: command
+            command: "echo 'This prompt violates content policy and has been blocked' >&2 && exit 2"
+            timeout: 5

data/examples/v2/hooks/validate_bash.rb

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example hook script: Validate Bash commands
+#
+# This demonstrates SwarmSDK hooks with JSON I/O and exit codes.
+#
+# Exit codes:
+#   0 - Success (continue execution)
+#   2 - Block execution with error feedback to LLM
+#   Other - Non-blocking error (log warning, continue)
+#
+# Input (stdin): JSON with event details
+# Output (stdout): JSON with success/error info
+
+require "json"
+
+# Read input from stdin
+begin
+  input_data = JSON.parse($stdin.read)
+rescue JSON::ParserError => e
+  $stderr.puts JSON.generate(success: false, error: "Invalid JSON input: #{e.message}")
+  exit(1)
+end
+
+# Extract command from parameters
+parameters = input_data["parameters"] || {}
+command = parameters["command"] || ""
+
+# Define dangerous patterns
+dangerous_patterns = [
+  [%r{rm\s+-rf\s+/}, "Recursive force removal from root"],
+  [/dd\s+if=/, "dd command (can overwrite data)"],
+  [/mkfs/, "Filesystem formatting"],
+  [/:\(\)\{.*\|.*&\};:/, "Fork bomb pattern"],
+  [%r{>\s*/dev/sd}, "Writing to disk devices"],
+  [/chmod\s+777/, "Insecure permissions"],
+]
+
+# Check for dangerous patterns
+dangerous_patterns.each do |pattern, description|
+  next unless command.match?(pattern)
+
+  # Exit 2 to block with error
+  output = {
+    success: false,
+    error: "Dangerous command blocked: #{description}\nCommand: #{command}",
+  }
+  puts JSON.generate(output)
+  exit 2 # Exit 2 = block execution
+end
+
+# Validation passed - allow execution
+output = {
+  success: true,
+  message: "Bash command validation passed",
+}
+puts JSON.generate(output)
+exit 0 # Exit 0 = continue

data/examples/v2/multi_directory_permissions.yml

@@ -0,0 +1,221 @@
+# Multi-Directory Access via Permissions
+#
+# This example demonstrates the new v1.0 approach to multi-directory access.
+#
+# BREAKING CHANGE (v0.x → v1.0):
+# - OLD: directories: ['.', 'lib/', 'test/']  # Multiple directories
+# - NEW: directory: 'lib/'                    # Single directory + permissions
+#
+# WHY THE CHANGE?
+# 1. Correctness: Tools now operate where agents expect (not in Dir.pwd)
+# 2. Fiber-safe: No reliance on process-global Dir.pwd
+# 3. Security: Explicit permission model for cross-directory access
+# 4. Simplicity: One directory = clear mental model
+#
+# MIGRATION GUIDE:
+# If your agent needs access to multiple directories:
+# 1. Choose ONE primary directory (where agent "lives")
+# 2. Use permissions to grant access to other directories
+# 3. Use relative paths like '../other_dir/file.txt'
+#
+# Run: swarm-cli run -f lib/swarm_sdk/examples/multi_directory_permissions.yml
+
+version: 2
+
+swarm:
+  name: "Multi-Directory Access Demo"
+  lead: backend_dev
+
+  # Global permissions example (optional)
+  # Uncomment to apply permissions to ALL agents
+  # all_agents:
+  #   permissions:
+  #     Read:
+  #       denied_paths: [".env", "**/.env", "**/secrets/**"]
+  #     Bash:
+  #       denied_commands: ["^rm -rf /", "^sudo .*"]
+
+  agents:
+    # Backend developer works primarily in backend/ directory
+    # but needs access to shared configuration and utilities
+    backend_dev:
+      description: "Backend developer with cross-directory access"
+      model: gpt-5-nano
+      provider: openai
+
+      # Primary working directory (singular!)
+      directory: backend/
+
+      tools:
+        - Read
+        - Write
+        - Edit
+        - Grep
+        - Glob
+        - Bash
+
+      # Permissions grant access beyond the primary directory
+      permissions:
+        # File operations: allow access to shared utilities and config
+        Read:
+          # Relative paths are resolved against agent's directory (backend/)
+          # So '../shared/**' means 'shared/' from project root
+          allowed_paths:
+            - "**/*"              # All files in backend/ (agent's directory)
+            - "../shared/**"      # Shared utilities (project_root/shared/)
+            - "../config/**"      # Configuration files (project_root/config/)
+            - "../README.md"      # Project README at root
+          denied_paths:
+            - "../frontend/**"    # Cannot read frontend code
+            - "**/.env"           # Cannot read environment secrets
+            - "**/secrets/**"     # Cannot read secrets directory
+
+        Write:
+          # More restrictive for writes
+          allowed_paths:
+            - "**/*"              # Can write anywhere in backend/
+            - "../shared/utils/**" # Can write shared utilities
+          denied_paths:
+            - "../config/**"      # Cannot modify config files
+            - "**/*.env"          # Cannot write .env files
+
+        Edit:
+          # Same as Write (Edit is just a different operation)
+          allowed_paths:
+            - "**/*"
+            - "../shared/utils/**"
+          denied_paths:
+            - "../config/**"
+
+        # Bash commands: restrict dangerous operations
+        Bash:
+          allowed_commands:
+            - "^git .*"           # All git commands
+            - "^npm (install|test|run).*" # Safe npm commands
+            - "^ruby .*"          # Ruby scripts
+            - "^bundle .*"        # Bundler commands
+          denied_commands:
+            - "^rm -rf /.*"       # No recursive root deletion
+            - "^sudo .*"          # No sudo
+            - "^curl.*\\|.*sh.*"  # No piping curl to shell
+
+      system_prompt: |
+        You are a backend developer working in the backend/ directory.
+
+        Your working directory is: backend/
+        - Relative paths like "server.rb" resolve to: backend/server.rb
+        - Relative paths like "../shared/utils.rb" resolve to: shared/utils.rb (project root)
+
+        You have permission to:
+        ✅ Read/write all files in backend/
+        ✅ Read shared utilities (../shared/**)
+        ✅ Read configuration (../config/**)
+        ✅ Read project README (../README.md)
+        ✅ Write to shared utilities (../shared/utils/**)
+
+        You do NOT have permission to:
+        ❌ Access frontend code (../frontend/**)
+        ❌ Modify configuration files (../config/**)
+        ❌ Read/write .env or secrets files
+        ❌ Run dangerous bash commands (rm -rf /, sudo, etc.)
+
+        When file operations fail with "Permission denied", check if:
+        1. The file is outside your allowed paths
+        2. The file is explicitly denied
+        3. You're trying to Write/Edit where you only have Read access
+
+    # Frontend developer: similar pattern, different directory
+    frontend_dev:
+      description: "Frontend developer with limited backend access"
+      model: gpt-5-nano
+      provider: openai
+
+      # Primary working directory
+      directory: frontend/
+
+      tools: [Read, Write, Edit, Grep, Glob, Bash]
+
+      permissions:
+        Read:
+          allowed_paths:
+            - "**/*"              # All files in frontend/
+            - "../shared/**"      # Shared utilities
+            - "../backend/api/**" # Can read API documentation
+          denied_paths:
+            - "../backend/secrets/**"
+            - "**/.env"
+
+        Write:
+          allowed_paths:
+            - "**/*"              # Can write anywhere in frontend/
+            - "../shared/ui/**"   # Can write shared UI components
+
+        Edit:
+          allowed_paths:
+            - "**/*"
+            - "../shared/ui/**"
+
+        Bash:
+          allowed_commands:
+            - "^git .*"
+            - "^npm .*"
+            - "^yarn .*"
+            - "^node .*"
+
+      system_prompt: |
+        You are a frontend developer working in the frontend/ directory.
+
+        Your working directory is: frontend/
+        - Relative paths like "index.html" resolve to: frontend/index.html
+        - Relative paths like "../shared/ui.css" resolve to: shared/ui.css
+
+        You have permission to:
+        ✅ Read/write all files in frontend/
+        ✅ Read shared utilities and UI components
+        ✅ Read backend API documentation (../backend/api/**)
+        ✅ Write to shared UI components (../shared/ui/**)
+
+        You do NOT have permission to:
+        ❌ Modify backend code
+        ❌ Read backend secrets
+        ❌ Read/write .env files
+
+    # Coordinator: works in project root, can delegate to specialists
+    coordinator:
+      description: "Coordinator with read-only access to entire project"
+      model: gpt-5-nano
+      provider: openai
+
+      # Works in project root
+      directory: .
+
+      tools: [Read, Grep, Glob, TodoWrite]
+      delegates_to: [backend_dev, frontend_dev]
+
+      # Read-only access to everything except secrets
+      permissions:
+        Read:
+          allowed_paths: ["**/*"]
+          denied_paths: ["**/.env", "**/secrets/**"]
+
+      system_prompt: |
+        You are a project coordinator with read-only access to the entire codebase.
+
+        Your working directory is the project root.
+        - Relative path "README.md" → ./README.md (root)
+        - Relative path "backend/server.rb" → ./backend/server.rb
+        - Relative path "frontend/index.html" → ./frontend/index.html
+
+        You can:
+        ✅ Read any file in the project (except secrets)
+        ✅ Search across all directories
+        ✅ Delegate work to backend_dev and frontend_dev
+
+        You cannot:
+        ❌ Write or edit files (delegate to specialists)
+        ❌ Read .env or secrets files
+
+        When delegating:
+        - Backend work → backend_dev
+        - Frontend work → frontend_dev
+        - Complex tasks → use TodoWrite to track progress